PCjs Machines

Home of the original IBM PC emulator for browsers.

Logo

MS QuickBASIC 4.5 Language Reference

The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.

Microsoft QuickBASIC: Language Reference


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


Microsoft(R) QuickBASIC BASIC: Language Reference

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, and XENIX are registered trademarks of Microsoft Corporation.

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

Hercules is a registered trademark and InColor is a trademark of Hercules
Computer Technology.

IBM and PC/AT are registered trademarks and PC/XT is a trademark of
International Business Machines Corporation.

Intel is a registered trademark of Intel Corporation.

Olivetti is a registered trademark of Ing. C. Olivetti.

Document No. 410700018-450-R00-1188



────────────────────────────────────────────────────────────────────────────
Table of Contents

Introduction
        Document Conventions
        Reference Page Format

PART 1  LANGUAGE FUNDAMENTALS

Chapter 1  Language Elements
        1.1  Character Set
        1.2  The BASIC Program Line
        1.2.1   Using Line Identifiers
        1.2.2   BASIC Statements
        1.2.3   BASIC Line Length

Chapter 2  Data Types
        2.1  Data Types
        2.1.1   Elementary Data Types──String
        2.1.2   Elementary Data Types──Numeric
            2.1.2.1   Integer Numbers
            2.1.2.2   Floating-Point Numbers
        2.1.3   User-Defined Data Types
        2.2  Constants
        2.2.1   Literal Constants
        2.2.2   Symbolic Constants
        2.3  Variables
        2.3.1   Variable Names
        2.3.2   Declaring Variable Types
            2.3.2.1   Type-Declaration Suffix
            2.3.2.2   AS Declaration Statements
            2.3.2.3   DEFtype Declaration Statements
            2.3.2.4   Declaring Array Variables
        2.3.3   Variable Storage Allocation
        2.4  Scope of Variables and Constants
        2.4.1   Global Variables and Constants
        2.4.2   Local Variables and Constants
        2.4.3   Sharing Variables
        2.4.4   DEF FN Functions
        2.4.5   Summary of Scope Rules
        2.5  Static and Dynamic Arrays
        2.6  Automatic and Static Variables
        2.7  Type Conversion

Chapter 3  Expressions and Operators
        3.1  Expressions and Operators Defined
        3.2  Hierarchy of Operations
        3.3  Arithmetic Operators
        3.3.1   Integer Division
        3.3.2   Modulo Arithmetic
        3.3.3   Overflow and Division by Zero
        3.4  Relational Operators
        3.5  Logical Operators
        3.6  Functional Operators
        3.7  String Operators

Chapter 4  Programs and Modules
        4.1  Modules
        4.2  Procedures
        4.2.1   FUNCTION Procedures
        4.2.2   SUB Procedures
        4.2.3   DEF FN Functions
        4.3  Passing by Reference and Passing by Value
        4.4  Recursion

PART 2  STATEMENT AND FUNCTION REFERENCE

        ABS Function
        ASC Function
        ATN Function
        BEEP Statement
        BLOAD Statement
        BSAVE Statement
        CALL Statement (BASIC)
        CALL, CALLS Statement (Non-BASIC)
        CALL ABSOLUTE Statement
        CALL INT86OLD Statements
        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
        CVSMBF, CVDMBF Functions
        CVI, CVS, CVL, CVD Functions
        DATA Statement
        DATE$ Function
        DATE$ Statement
        DECLARE Statement (BASIC)
        DECLARE Statement (Non-BASIC)
        DEF FN Statement
        DEF SEG Statement
        DEFtype Statements
        DIM Statement
        DO...LOOP Statement
        DRAW Statement
        END Statement
        ENVIRON Statement
        ENVIRON$ Function
        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 Statement
        INKEY$ Function
        INP Function
        INPUT$ Function
        INPUT Statement
        INPUT # Statement
        INSTR Function
        INT Function
        IOCTL$ Function
        IOCTL Statement
        KEY (n) Statements
        KEY 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
        ONevent Statements
        ON...GOSUB, ON...GOTO Statement
        ON UEVENT GOSUB Statement
        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 StatementsP
        PMAP Function
        POINT Function
        POKE Statement
        POS Function
        PRESET Statement
        PRINT Statement
        PRINT USING Statement
        PRINT #, PRINT # USING Statements
        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

Appendix A  Keyboard Scan Codes and ASCII Character Codes
        A.1  Keyboard Scan Codes
        A.2  ASCII Character Codes

Appendix B  Error Messages
        B.1  Error-Message Display
        B.2  Invocation, Compile-Time, and Run-Time Error Messages
        B.3  LINK Error Messages
        B.4  LIB Error Messages

Index

Figures
        2.1  BASIC Numeric Representations
        R.1  WINDOW and WINDOW SCREEN

Tables
        2.1  Types of Numeric Constants
        2.2  Variable-Type Memory Requirements
        3.1  Relational Operators and Their Functions
        3.2  BASIC Logical Operators
        3.3  Values Returned by Logical Operations
        R.1  INT86OLD and INT86XOLD Register Values
        R.2  FILEATTR Mode Codes
        R.3  Values for Bits per Pixel per Plane and for Planes
        R.4  Keyboard Scan Codes
        R.5  SCREEN Color and Attribute Ranges
        R.6  MDPA Screen Modes
        R.7  Hercules Screen Modes
        R.8  CGA Screen Modes
        R.9  EGA Screen Modes
        R.10 Default Attributes: SCREEN 10, Monochrome Display
        R.11 Color Values: SCREEN 10, Monochrome Display
        R.12 VGA Screen Modes
        R.13 MCGA Screen Modes
        R.14 Default Attributes and Colors for SCREEN Modes 1 and 9
        R.15 Default Attributes and Colors for SCREEN Modes 2 and 11
        R.16 Default Attributes and Colors for SCREEN Modes 0, 7, 8, 9,
            12, and 13



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

    Microsoft(R) QuickBASIC 4.5 is a powerful programming language for either
    commercial applications or quick development of single-use programs.
    QuickBASIC is compatible with BASICA, adding advanced features such as
    user-defined data types and recursive procedures to the elements that have
    traditionally made BASIC an ideal language for new programmers.

    The Microsoft BASIC Language Reference describes the QuickBASIC
    programming language. Use this manual as a printed reference guide while
    you are programming to find the syntax or effect of particular statements
    and functions. You can also use this book to explore BASIC by reading
    about unfamiliar statements and trying them in the short example programs
    provided.

    The BASIC Language Reference has these parts:

    ■ Part 1, "Language Fundamentals," describes the elements of the BASIC
    language: characters, program lines, data types, constants, variables,
    modules, programs, and procedures.

    ■ Part 2, "Statement and Function Reference," contains reference material
    on each BASIC statement and function, organized alphabetically.

    ■ The appendixes list the keyboard scan and ASCII character codes and
    provide quick reference information on error messages.

    This volume is a companion to the other books supplied with QuickBASIC
    Version 4.5. Learning to Use Microsoft QuickBASIC explains how to use the
    QuickBASIC environment and introduces BASIC programming. Programming in
    BASIC contains more advanced programming information.


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.
                            Keywords are a required part of statement syntax,
    Example of Convention    Description
    ──────────────────────────────────────────────────────────────────────────
                            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)
                            marks the beginning of a comment in sample
    Example of Convention    Description
    ──────────────────────────────────────────────────────────────────────────
                            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 chevrons 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.

    ALT+F1                   Capital letters are used for the names of keys
    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.
                            Other machines may use different names.
    Example of Convention    Description
    ──────────────────────────────────────────────────────────────────────────
                            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.
────────────────────────────────────────────────────────────────────────────


Reference Page Format

    Each statement and function description in Part 2, "Statement and
    Function Reference," uses the following format:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Heading                  Function
    ──────────────────────────────────────────────────────────────────────────
    Action                   Summarizes what the statement or function does.

    Syntax                   Gives the correct syntax for the statement or
    Heading                  Function
    ──────────────────────────────────────────────────────────────────────────
    Syntax                   Gives the correct syntax for the statement or
                            function.

    Remarks                  Describes arguments and options in detail and
                            explains how to use the statement or function.

    Differences from BASICA  Optional section that tells whether or not the
                            given statement or function is new, enhanced, or
                            different from the same statement in the
                            Microsoft BASIC 2.0 Interpreter described in the
                            IBM Personal Computer BASICA reference manual.

    See Also                 Mentions related statements and functions (also
                            an optional section).

    Example                  Gives sample commands, programs, and program
                            segments illustrating the use of the statement or
                            function (also an optional section).

    Heading                  Function
    ──────────────────────────────────────────────────────────────────────────

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





────────────────────────────────────────────────────────────────────────────
PART 1  LANGUAGE FUNDAMENTALS
────────────────────────────────────────────────────────────────────────────

    Part 1 describes aspects of the BASIC language. Chapter 1 gives
    information on the BASIC character set and the structure of a BASIC
    program line. Chapter 2 discusses data types, constants, variables, and
    arrays. Chapter 3 talks about BASIC operators and expressions. Chapter
    4 explains how to use modules and procedures in BASIC programming. This
    chapter also describes the relationship between programs and modules and
    discusses the SUB and FUNCTION procedures available in QuickBASIC.



────────────────────────────────────────────────────────────────────────────
Chapter 1   Language Elements

        1.1  Character Set
        1.2  The BASIC Program Line
        1.2.1   Using Line Identifiers
        1.2.2   BASIC Statements
        1.2.3   BASIC Line Length

    This chapter discusses some of the fundamental elements of the QuickBASIC
    version of the BASIC language. As in virtually all programming languages,
    characters from the BASIC character set form labels, keywords, variables,
    and operators. These then combine to form the statements that make up a
    program.

    ■ The BASIC character set and the special meanings of some characters

    ■ The format of a line in a BASIC program

    ■ Line labels

    ■ Executable and nonexecutable statements

    ■ Program line length

    Chapter 2, "Data Types," and Chapter 3, "Expressions and Operators,"
    discuss other parts of statements, including expressions.


1.1  Character Set

    The Microsoft BASIC character set consists of alphabetic characters,
    numeric characters, and special characters.

    The alphabetic characters in BASIC are the uppercase letters (A-Z) and
    lowercase letters (a-z) of the alphabet.

    The BASIC numeric characters are the digits 0-9. The letters A-F and a-f
    can be used as parts of hexadecimal numbers. The characters in Table 1.1
    have special meanings in BASIC statements and expressions.

    Table 1.1   BASIC Character Set

╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖
    Character          Name
    ──────────────────────────────────────────────────────────────────────────
    ENTER              Terminates input of a line
                        Blank (or space)
    !                  Exclamation point (single-precision data-type suffix)
    #                  Number sign (double-precision data-type suffix)
    $                  Dollar sign (suffix for string data type)
    %                  Percent (suffix for integer data type)
    &                  Ampersand (suffix for long-integer data type)
    '                  Single quotation mark (apostrophe)
    (                  Left parenthesis
    )                  Right parenthesis
    *                  Asterisk (multiplication symbol)
    +                  Plus sign
    ,                  Comma
    -                  Minus sign
    .                  Period (decimal point)
    Character          Name
    ──────────────────────────────────────────────────────────────────────────
    .                  Period (decimal point)
    /                  Slash (division symbol)
    :                  Colon
    ;                  Semicolon
    <                  Less than
    =                  Equal sign (relational operator or assignment symbol)
    >                  Greater than
    ?                  Question mark
    @                  At symbol
    [                  Left bracket
    ]                  Right bracket
    \                  Backslash (integer division symbol)
    ^                  Up arrow or caret (exponentiation symbol)
    _                  Underscore (line continuation)
    ──────────────────────────────────────────────────────────────────────────



1.2  The BASIC Program Line

    BASIC program lines have the following syntax:

    [[line-identifier]] [[statement]] [[: statement]]...[[comment]]

1.2.1  Using Line Identifiers

    BASIC supports two types of line-identifiers──line numbers and
    alpha-numeric line labels:

    1. A line number may be any combination of digits from 0 to 65,529. The
        following are examples of valid line numbers:

        1
        200
        300PRINT "hello"    '300 is the line number.
        65000

        Using 0 as a line number is not recommended. Error- and event-trapping
        statements (ON ERROR and ONevent) interpret the presence of line number
        0 to mean that trapping is disabled (stopped). For example, the
        following statement disables error trapping but does not branch to line
        0 if an error occurs:

        ON ERROR GOTO 0

        In addition, RESUME 0 continues execution on the line where the error
        occurred, not at line number 0.

    2. An alphanumeric line label may be any combination of from 1 to 40
        letters and digits, starting with a letter and ending with a colon.
        BASIC keywords are not permitted. The following are valid alphanumeric
        line labels:

        Alpha:
        ScreenSub:
        Test3A:

        Case is not significant. The following line labels are equivalent:

        alpha:
        Alpha:
        ALPHA:

    Line numbers and labels may begin in any column, as long as they are the
    first characters other than blanks or tabs on the line. Blanks and tabs
    are also allowed between an alphanumeric label and the colon following it.
    A line can have only one label.

    BASIC does not require each line in a source program to have the same type
    of identifier, either a line number or label. You may mix alphanumeric
    labels and line numbers in the same program, and you may use alphanumeric
    labels as objects of any BASIC statement where line numbers are permitted,
    except as the object of an IF...THEN statement. In IF...THEN statements,
    BASIC permits only a line number, unless you explicitly use a GOTO
    statement. For example, the form of the following statement is correct:

    IF A = 10 THEN 500

    However, if the object of the IF...THEN statement is a line label, a GOTO
    statement is required:

    IF A = 10 THEN GOTO IncomeData

    If you are trapping errors, the ERL function returns only the last line
    number located before the error. Neither RESUME nor RESUME NEXT requires
    line labels or line numbers. See the entries for ERL and RESUME for more
    information.

    Line numbers do not determine the order in which statements are executed
    in QuickBASIC. For example, QuickBASIC executes statements in the
    following program in the order 100, 10, 5:

    100 PRINT "The first line executed."
    10 PRINT "The second line executed."
    5 PRINT "The third and final line executed."

    Some older BASICs, such as BASICA, would execute the lines in numerical
    order: 5, 10, 100.

1.2.2  BASIC Statements

    A BASIC statement is either "executable" or nonexecutable." An executable
    statement advances the flow of a program's logic by telling the program
    what to do next (telling it to read input, write output, add two numbers
    together and store the resulting value in a variable, open a file, branch
    to another part of the program, or take some other action). In contrast, a
    nonexecutable statement does not advance the flow of a program's logic.
    Instead, nonexecutable statements perform tasks such as allocating storage
    for variables, declaring and defining variable types, and designating
    variables to be shared among all the procedures in a source file.

    The following BASIC statements are nonexecutable:

    ■ COMMON

    ■ CONST

    ■ DATA

    ■ DECLARE

    ■ DEFtype

    ■ DIM (static arrays only)

    ■ OPTION BASE

    ■ SHARED

    ■ STATIC

    ■ TYPE...END TYPE

    Another type of nonexecutable statement is a "comment" used to clarify a
    program's operation and purpose. A comment is introduced by the REM
    statement or a single quote character ('). The following lines are
    equivalent:

    PRINT "Quantity remaining" : REM Print report label.
    PRINT "Quantity remaining"     ' Print report label.

    More than one BASIC statement can be placed on a line, but colons (:) must
    separate statements, as illustrated below:

    FOR I=1 TO 5 : PRINT "G'day, mate." : NEXT I

1.2.3  BASIC Line Length

    If you enter your programs using QuickBASIC's built-in editor, you are
    limited to lines of 256 characters. The QuickBASIC editor does not
    recognize the underscore character (_) as a line continuation.

    If you use your own editor, you may use an underscore as the last
    character to create a program line, like the following, that extends
    across more than one physical line:

    IF (TestChar$ = " " OR TestChar$ = ".") AND _
    LineNumber < 23 AND NOT EOF(FileNumber) THEN

    When QuickBASIC loads your program, the underscores are removed and the
    continued lines are joined to form a single line. The line-length limit is
    relaxed in this case. Underscores cannot be used to continue DATA or REM
    statements.



────────────────────────────────────────────────────────────────────────────
Chapter 2   Data Types

        2.1  Data Types
        2.1.1   Elementary Data Types──String
        2.1.2   Elementary Data Types──Numeric
            2.1.2.1   Integer Numbers
            2.1.2.2   Floating-Point Numbers
        2.1.3   User-Defined Data Types
        2.2  Constants
        2.2.1   Literal Constants
        2.2.2   Symbolic Constants
        2.3  Variables
        2.3.1   Variable Names
        2.3.2   Declaring Variable Types
            2.3.2.1   Type-Declaration Suffix
            2.3.2.2   AS Declaration Statements
            2.3.2.3   DEFtype Declaration Statements
            2.3.2.4   Declaring Array Variables
        2.3.3   Variable Storage Allocation
        2.4  Scope of Variables and Constants
        2.4.1   Global Variables and Constants
        2.4.2   Local Variables and Constants
        2.4.3   Sharing Variables
        2.4.4   DEF FN Functions
        2.4.5   Summary of Scope Rules
        2.5  Static and Dynamic Arrays
        2.6  Automatic and Static Variables
        2.7  Type Conversion

    This chapter contains seven sections that provide the following
    information about the data types, constants, and variables in BASIC:

    ■ The elementary data types (string and numeric)

    ■ The formation of literal and symbolic constants

    ■ The rules for naming a BASIC variable and for determining a variable's
    type, and how BASIC allocates variable storage

    ■ The scope rules that BASIC follows to decide to which object a variable
    name refers

    ■ The difference between static and dynamic arrays

    ■ The use of automatic and static variables in SUB and FUNCTION procedures

    ■ The conversions from one numeric type to another that BASIC may perform
    when doing calculations


2.1  Data Types

    Every variable in BASIC has a data type that determines what can be stored
    in the variable. There are two categories of data in BASIC: string data
    and numeric data. Each category includes elementary data types. The next
    section summarizes the elementary data types.

2.1.1  Elementary Data Types──String

    The two kinds of strings are as follows:

    ■ Variable-length string

    A variable-length string is a sequence of up to 32,767 characters. The
    codes for these characters range from 0-127 for American Standard Code
    for Information Interchange (ASCII) characters, and from 128-255 for
    non-ASCII characters (see Appendix A, "Keyboard Scan Codes and ASCII
    Character Codes").

    ■ Fixed-length string

    A fixed-length string contains a declared number of characters.
    Fixed-length strings can be no longer than 32,767 characters.
    Fixed-length strings, like variable-length strings, contain characters
    with codes ranging from 0-255.

2.1.2  Elementary Data Types──Numeric

    BASIC has two types of integers and two types of floating-point values.
    Figure 2.1 shows the internal (memory) formats of these four different
    numeric types. The following table summarizes the types:

    Numeric Type             Description
    ──────────────────────────────────────────────────────────────────────────
    Integer (2 bytes)        Integers are stored as signed 16-bit binary
                            numbers ranging in value from -32,768 to +32,767.

    Long integer (4 bytes)   "Long" integers are stored as signed 32-bit
                            binary numbers ranging in value from
                            -2,147,483,648 to +2,147,483,647.

    Single-precision         "Single-precision" numbers are accurate to seven
    floating point (4 bytes) decimal places, and have ranges of -3.402823E+38
                            to -1.40129E-45 for negative values and
                            1.40129E-45 to 3.402823E+38 for positive values.

    Double-precision         "Double-precision" numbers are accurate to 15 or
    floating point (8 bytes) 16 digits and have an extended range:
                            -1.797693134862316E+308 to -4.94065E-324 for
                            negative numbers and 4.94065E-324 to
                            1.797693134862316E+308 for positive values.
    ──────────────────────────────────────────────────────────────────────────

    2.1.2.1  Integer Numbers


        Integer
        1514                     0
    ┌─┬───────────────────────┐
    │ │                       │
    └─┴───────────────────────┘
        │
    sign

    Long integer
    31 30                               0
    ┌─┬─────────────────────────────────┐
    │ │                                 │
    └─┴─────────────────────────────────┘

    Single-precision real
    31 30  23 22                        0
    ┌─┬─────┬───────────────────────────┐
    │ │     │                           │
    └─┴─────┴───────────────────────────┘
        │ └─┬─┘│└──────────┬──────────────┘
        │   │  │           │
    sign  │Implied    Mantissa
            │  bit
            │
        Exponent

    Double Precision real
    63 62   52 51
    ┌─┬───────┬───────────────────────────────────────────────────────┐
    │ │       │                                                       │
    └─┴───────┴───────────────────────────────────────────────────────┘
        │ └─┬───┘│└──────────────────────┬──────────────────────────────┘
        │   │    │                       │
    sign  │Implied                  Mantissa
            │  bit
            │
        Exponent

            Figure 2.1 BASIC Numeric Representations

    All BASIC integers are represented as two's complement values, the most
    common way of representing integers on a computer. Integers use 16 bits (2
    bytes) and long integers use 32 bits (4 bytes).

    In two's complement representation, positive values are represented as
    straightforward binary numbers. For example, BASIC would store an integer
    value of 4 as a sequence of the following 16 bits:

    0000000000000100

    Negative values are represented as the two's complement of the
    corresponding positive value. To form the two's complement (the negative)
    of the integer value 4, first take the representation above and change all
    ones to zeroes and all zeroes to ones:

    1111111111111011

    Then add one to the result:

    1111111111111100

    The final result is how BASIC represents -4 as a binary number.

    Because of the way two's complement numbers are formed, every combination
    of bits representing a negative value has a 1 as the leftmost bit.

    2.1.2.2  Floating-Point Numbers

    QuickBASIC Version 4.5 uses IEEE-format floating-point numbers rather than
    the Microsoft Binary format used in earlier versions. (IEEE is an acronym
    for Institute of Electrical and Electronics Engineers, Inc.) IEEE format
    gives more accurate results and makes it possible to use an 8087 or 80287
    math coprocessor.

    Floating-point values are represented in a different format from integers.
    In floating-point format each number consists of three parts: the sign,
    the exponent, and the mantissa. You can think of this format as a
    variation of scientific notation. In scientific notation, the number 1000
    would be represented as 1.0 x 10^3. To save space, you could just remember
    the exponent, 3, and the mantissa, 1.0, and reconstruct the value later by
    raising 10 to the power 3 and multiplying by the mantissa. Floating-point
    notation works by saving just the exponent and the mantissa. The only
    difference from scientific notation is that in this format the exponent
    represents a power of 2, not a power of 10.

    In a single-precision number, the sign takes 1 bit, the exponent takes 8
    bits, and the mantissa uses the remaining 23 bits and an additional
    implied bit. Double-precision values occupy 8 bytes or 64 bits: 1 bit for
    the sign, 11 bits for the exponent, and an implied bit and 52 actual bits
    for the mantissa.

    The following program (included on the QuickBASIC distribution disks in
    the file FLPT.BAS) can be used to examine the internal format of
    single-precision values:

    DECLARE FUNCTION MHex$ (X AS INTEGER)
    ' Display how a given real value is stored in memory.

    DEFINT A-Z
    DIM Bytes(3)
    CLS
    PRINT "Internal format of IEEE number (in hexadecimal)"
    PRINT
    DO

    ' Get the value.
    INPUT "Enter the value (END to end): ", A$
    IF UCASE$(A$) = "END" THEN EXIT DO
    RealValue! = VAL(A$)
    ' Convert the real value to a long without changing any of
    ' the bits.
    AsLong& = CVL(MKS$(RealValue!))
    ' Make a string of hex digits, and add leading zeroes.
    Strout$ = HEX$(AsLong&)
    Strout$ = STRING$(8 - LEN(Strout$), "0") + Strout$
    ' Save the sign bit, and then eliminate it so it doesn't
    ' affect breaking out the bytes.
    SignBit&=AsLong& AND &H80000000&
    AsLong&=AsLong& AND &H7FFFFFFF&
    ' Split the real value into four separate bytes.
    ' --the AND removes unwanted bits; dividing by 256 shifts
    ' the value right 8 bit positions.
    FOR I = 0 TO 3
        Bytes(I) = AsLong& AND &HFF&
        AsLong& = AsLong&  256&
    NEXT I
    ' Display how the value appears in memory.
    PRINT
    PRINT "Bytes in Memory"
    PRINT "  High    Low"
    FOR I = 1 TO 7 STEP 2
        PRINT " "; MID$(Strout$, I, 2);
    NEXT I
    PRINT:PRINT
    ' Set the value displayed for the sign bit.
    Sign = ABS(SignBit& <> 0)

    ' The exponent is the right seven bits of byte 3 and the
    ' leftmost bit of byte 2. Multiplying by 2 shifts left and
    ' makes room for the additional bit from byte 2.
    Exponent = Bytes(3) * 2 + Bytes(2)  128

    ' The first part of the mantissa is the right seven bits
    ' of byte 2. The OR operation makes sure the implied bit
    ' is displayed by setting the leftmost bit.
    Mant1 = (Bytes(2) OR &H80)
    PRINT " Bit 31    Bits 30-23  Implied Bit & Bits 22-0"
    PRINT "Sign Bit  Exponent Bits     Mantissa Bits"
    PRINT TAB(4); Sign; TAB(17); MHex$(Exponent);
    PRINT TAB(33); MHex$(Mant1);MHex$(Bytes(1));MHex$(Bytes(0))
    PRINT

    LOOP

    ' MHex$ makes sure we always get two hex digits.
    FUNCTION MHex$ (X AS INTEGER) STATIC
        D$ = HEX$(X)
        IF LEN(D$) < 2 THEN D$ = "0" + D$
        MHex$ = D$
    END FUNCTION

    Output

    Enter the value (END to end): 4

    Bytes in Memory
    High    Low
    40 80 00 00

    Bit 31    Bits 30-23  Implied Bit & Bits 22-0
    Sign Bit  Exponent Bits     Mantissa Bits
        0           81              800000

    The program displays the sign, exponent, and mantissa of the
    single-precision value. The mantissa's implied bit is automatically
    included. All values are printed out in hexadecimal values (base 16
    numbers), which are a shorthand way of writing binary numbers. Each
    hexadecimal digit represents a pattern of 4 bits: 0 hexadecimal represents
    0000 binary, 8 hexadecimal represents 1000, and F hexadecimal (a digit for
    the value 15 in decimal) represents 1111.

    Looking at the output from the program, the decimal value 4 is represented
    in memory as a series of 4 bytes:

    40 80 00 00

    These 4 bytes break down into a single-sign bit of 0, a 1-byte exponent of
    &H81, and a mantissa of &H800000.

    The exponent value of &H81 represents a biased exponent, not the true
    exponent. With a biased exponent, a fixed value (a "bias") is added to the
    true exponent and the result is stored as part of the number. For
    single-precision values, the bias is &H7F or 127. Double-precision values
    use a bias of &H3FF or 1023. Using a biased exponent avoids having to use
    one of the exponent bits to represent the sign. In the output, 4 is a
    power of 2, so the true exponent is 2. Adding the bias (&H7F) gives the
    stored exponent value of &H81.

    A normalized mantissa refers to a mantissa that is multiplied by 2
    (shifted to the left) and the exponent decreased until the leftmost bit is
    a 1. By eliminating leading zeroes from the mantissa, more significant
    bits can be stored. In memory, the mantissa for a value of 4 is all
    zeroes. This is so because the mantissa is normalized and the leftmost bit
    is assumed.

    Because the mantissa is always normalized, the leftmost bit is always a 1.
    And because the leftmost bit is always a 1, there is no reason to store it
    as part of the number. BASIC thus stores 23 bits (number 22 to 0) for the
    mantissa of a single-precision number but also includes a 24th, implied
    bit that is always a 1.

    There is an implied "binary point" (analogous to a decimal point) to the
    right of the implied bit. The binary point indicates that bits 22 to 0 in
    the mantissa are really a binary fraction. Thus, in the example, the
    mantissa is really a single 1 (the implied bit) followed by a zero binary
    fraction (bits 22 to 0). The mantissa of 1 multiplied by 2 taken to the
    power of the exponent, 2, is 1 x 2^2, or 4.

2.1.3  User-Defined Data Types

    BASIC lets you define new data types using the TYPE statement. A
    user-defined type is an aggregate type made up of elementary BASIC types.
    For example, the following TYPE statement defines a type, SymTabEntry:

    TYPE SymTabEntry
        Identifier AS STRING*40
        LineNumber AS LONG
        Value      AS LONG
    END TYPE

    The new type contains a fixed-length string and two long integers. A
    variable of a user-defined type occupies only as much storage as the sum
    of its components. A SymTabEntry takes up 48 bytes: 40 bytes for the
    fixed-length string and 4 bytes each for the two long integers.

    You may use any of the BASIC data types (except variable-length strings)
    in a user-defined type: short and long integers, single- and
    double-precision floating-point values, and fixed-length strings. However,
    user-defined types cannot include arrays.


2.2  Constants

    Constants are predefined values that do not change during program
    execution. There are two general types of constants: literal constants
    (such as numbers and strings) and symbolic constants.

2.2.1  Literal Constants

    BASIC has two kinds of literal constants: string and numeric. A string
    constant is a sequence of up to 32,767 alphanumeric characters enclosed by
    double quotation marks. These alphanumeric characters can be any of the
    characters (except the double quote character and any carriage-return and
    line-feed sequences) whose ASCII codes fall within the range 0-255. This
    range includes both the actual ASCII characters (0-127) and the extended
    characters (128-255). The following are all valid string constants:

    "HELLO"
    "$25,000.000"
    "Number of Employees"

    Numeric constants are positive or negative numbers. There are four types
    of numeric constants: integer, long integer, fixed point, and floating
    point. Table 2.1 below describes these types and provides examples.

    Fixed-point and floating-point numeric constants can be either
    single-precision or double-precision numbers. Single-precision numeric
    constants are stored with 7 digits of precision (plus the exponent).
    Double-precision numbers are stored with 15 or 16 digits of precision
    (plus the exponent).

    A single-precision constant is any numeric constant that has one of the
    following properties:

    ■ Exponential form denoted by "E"

    ■ A trailing exclamation mark (!)

    ■ A value containing a decimal point that does not have either a "D" in
    the exponent or a trailing number sign (#) and that has fewer than 15
    digits

    ■ A value without a decimal point that has fewer than 15 digits but cannot
    be represented as a long-integer value

    A double-precision constant is any numeric constant that has one of the
    following properties:

    ■ Exponential form denoted by "D"

    ■ A trailing number sign (#)

    ■ A decimal point, no "E" in the exponent or trailing exclamation mark
    (!), and more than 15 digits

    Table 2.1   Types of Numeric Constants

╓┌─┌──────────────────┌─────────────────┌──────────────────┌─────────────────╖
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
    Integer            Decimal           One or more        68 +407 -1
                                        decimal digits
                                        (0-9) with an
                                        optional sign
                                        prefix (+ or -).
                                        The range for
                                        integer decimal
                                        constants is
                                        -32,768 to
                                        +32,767.

    Integer            Hexadecimal       One or more        &H76 &H32F
                                        hexadecimal digits
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
                                        hexadecimal digits
                                        (0-9, a-f, or A-F)
                                        with the prefix &H
                                        or &h. The range
                                        for integer
                                        hexadecimal
                                        constants is &h0
                                        to &hFFFF.

    Integer            Octal             One or more octal  &o347 &1234
                                        digits (0-7) with
                                        the prefix &O, &o,
                                        or &. The range
                                        for integer octal
                                        constants is &o0
                                        to &o177777.

    Long integer       Decimal           One or more        95000000 -400141
                                        decimal digits
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
                                        decimal digits
                                        (0-9) with an
                                        optional sign
                                        prefix (+ or -)
                                        and the suffix &.
                                        The range for long
                                        decimal constants
                                        is -2,147,483,648
                                        to +2,147,483,647.

    Long integer       Hexadecimal       One or more        &H0& &H1AAAAA&
                                        hexadecimal digits
                                        (0-9, a-f, or A-F)
                                        with the prefix &H
                                        or &h and the
                                        suffix &. The
                                        range for long
                                        hexadecimal
                                        constants is &h0&
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
                                        constants is &h0&
                                        to &hFFFFFFFF&.

    Long integer       Octal             One or more octal  &o347& &555577733&
                                        digits (0-7) with
                                        the prefix &O, &o,
                                        or & and the
                                        suffix &. The
                                        range for long
                                        octal constants is
                                        &o0& to
                                        &o37777777777&.

    Fixed point                          Positive or        9.0846
                                        negative real
                                        numbers──numbers
                                        containing decimal
                                        points.

    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────

    Floating point     Single precision  Positive or        2235.988E-7 2359E6
                                        negative numbers
                                        represented in
                                        exponential form
                                        (similar to
                                        scientific
                                        notation). A
                                        single-precision
                                        floating-point
                                        constant is an
                                        optionally signed
                                        integer or
                                        fixed-point number
                                        (the mantissa)
                                        followed by the
                                        letter E and an
                                        optionally signed
                                        integer (the
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
                                        integer (the
                                        exponent). The
                                        constant's value
                                        is the mantissa
                                        multiplied by the
                                        power of ten
                                        represented by the
                                        exponent. The
                                        range for
                                        single-precision
                                        constants is
                                        -3.37E+38 to
                                        3.37E+38.

    Floating point     Double precision  Double-precision   4.35D-10
                                        floating-point
                                        constants have the
                                        same form as
                                        single-precision
    Type               Subtype           Description        Examples
    ──────────────────────────────────────────────────────────────────────────
                                        single-precision
                                        floating-point
                                        constants, but use
                                        D, rather than E,
                                        to indicate the
                                        exponent.
                                        Double-precision
                                        constants have a
                                        range of
                                        -1.67D+308 to
                                        1.67D+308.
    ──────────────────────────────────────────────────────────────────────────


    Numeric constants in BASIC cannot contain commas. The following are
    examples of numeric constants:

    Single Precision         Double Precision
    ──────────────────────────────────────────────────────────────────────────
    46.8                     345692811.5375901
    -1.09E-6                 -1.09432D-06
    3489.0                   3489.0#
    22!                      987654321.1234567
    ──────────────────────────────────────────────────────────────────────────

2.2.2  Symbolic Constants

    BASIC provides symbolic constants that can be used in place of numeric or
    string values. The following fragment declares two symbolic constants and
    uses one to dimension an array:

    CONST MAXCHARS%=254, MAXBUF%=MAXCHARS%+1
    DIM Buffer%(MAXBUF%)

    The name of a symbolic constant follows the same rules as a BASIC variable
    name. You may include a type-declaration character (%, #, !, or $) in the
    name to indicate its type, but this character is not part of the name. For
    example, after the following declaration, the names N!, N#, N$, N%, and N&
    cannot be used as variable names because they have the same name as the
    constant:

    CONST N=45

    A constant's type is determined either by an explicit type-declaration
    character or the type of the expression. Symbolic constants are unaffected
    by DEFtype statements.

    If you omit the type-declaration character, the constant is given a type
    based on the expression. Strings always yield a string constant. With
    numeric expressions, the expression is evaluated and the constant is given
    the simplest type that can represent it. For example, if the expression
    gives a result that can be represented as an integer, the constant is
    given an integer type.

    See Section 2.4 below, "Scope of Variables and Constants," for
    information about the scope of constants. See the entry for CONST in Part
    2, "Statement and Function Reference," for more information about where
    and how to use symbolic constants.


2.3  Variables

    A variable is a name that refers to an object──a particular number,
    string, or record. (A record is a variable declared to be a user-defined
    type.) Simple variables refer to a single number, string, or record. Array
    variables refer to a group of objects, all of the same type.

    A numeric variable, whether simple or array, can be assigned only a
    numeric value (either integer, long integer, single precision, or double
    precision); a string variable can be assigned only a character-string
    value. You can assign one record variable to another only if both
    variables are the same user-defined type. However, you can always assign
    individual elements of a record to a variable of the corresponding type.

    The following list shows some examples of variable assignments:

    Variable Assignment      Example
    ──────────────────────────────────────────────────────────────────────────
    A constant value         A = 4.5

    The value of another     B$ = "ship of fools" A$ = B$ Profits =
    string or numeric        NetEarnings
    variable
    The value of a record    TYPE EmployeeRec EName AS STRING*25 SocSec AS
    element                  STRING*9 END TYPE DIM CurrentEmp AS EmployeeRec .
                            . . OutSocSec$=CurrentEmp.SocSec

    The value of one record  TYPE FileBuffer EName AS STRING*25 JobClass AS
    variable to another of   INTEGER END TYPE DIM Buffer1 AS FileBuffer DIM
    the same type            Buffer2 AS FileBuffer . . . Buffer2=Buffer1

    The value obtained by    CONST PI = 3.141593 Conversion = 180/PI TempFile$
    combining other          = FileSpec$+".BAK"
    variables, constants,
    and operators
    ──────────────────────────────────────────────────────────────────────────

    See Chapter 3, "Expressions and Operators," for more information on the
    operators used in BASIC for combining variables and constants. In any
    case, the variable must always match the type of data (numeric or string)
    assigned to it.

    Before a variable is assigned a value, its value is assumed to be zero
    (for numeric variables) or null (for string variables). All fields in a
    record, including string fields, are initialized to zero.

2.3.1  Variable Names

    A BASIC variable name may contain up to 40 characters. The characters
    allowed in a variable name are letters, numbers, the decimal point, and
    the type-declaration characters (%, &, !, #, and $).

    The first character in a variable name must be a letter. If a variable
    begins with FN, it is assumed to be a call to a DEF FN function. (As a
    general rule, the use of a FUNCTION is preferred over a DEF FN.)

    A variable name cannot be a reserved word, but embedded reserved words are
    allowed. For example, the following statement is illegal because LOG is a
    reserved word (BASIC is not case sensitive):

    Log = 8

    However, the following statement is legal:

    TimeLog = 8

    Reserved words include all BASIC commands, statements, function names, and
    operator names (see Appendix E, "BASIC Reserved Words," in Programming in
    BASIC for a complete list of reserved words).

    Variable names must also be distinct from both SUB and FUNCTION procedure
    names and symbolic constant (CONST) names.

2.3.2  Declaring Variable Types

    Simple variables can be numeric, string, or record variables. You may
    specify simple variable types by the use of a type-declaration suffix, in
    an AS declaration statement, or in a DEFtype declaration statement.
    Variables may also be declared as arrays.

    2.3.2.1  Type-Declaration Suffix

    Append one of the following type-declaration suffixes to the variable
    name:

    % & ! # $

    The dollar sign ($) is the type-declaration character for string
    variables; that is, it "declares" that the variable represents a string
    and that you can assign a string constant to it of up to 32,767
    characters, as in the example below.

    A$ = "SALES REPORT"

    Numeric-variable names can declare integer values (denoted by the %
    suffix), long-integer values (denoted by the & suffix), single-precision
    values (denoted by the ! suffix), or double-precision values (denoted by
    the # suffix). Single precision is the default for variables without a
    type suffix.

    There is no type-declaration character for a user-defined type.

    2.3.2.2  AS Declaration Statements

    Declare the variable in a declaration having the form

    declare variablename AS type

    where declare can be either DIM, COMMON, REDIM, SHARED, or STATIC, and
    type can be either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a
    user-defined type. For example, the following statement declares the
    variable A as having a long-integer type:

    DIM A AS LONG

    String variables declared in an AS STRING clause can be either
    variable-length strings or fixed-length strings. Variable-length strings
    are "expandable": their length depends on the length of any string
    assigned to them. Fixed-length strings have a constant length, specified
    by adding * number to the AS STRING clause, where number is the length of
    the string in bytes. For example:

    ' String1 can have a variable length:
    DIM String1 AS STRING

    ' String2 has a fixed length of 7 bytes:
    DIM String2 AS STRING*7

    String1  = "1234567890"
    String2  = "1234567890"
    PRINT String1
    PRINT String2

    Output

    1234567890
    1234567

    For more on fixed-length and variable-length strings, see Chapter 4,
    "String Processing," in Programming in BASIC. Declare record variables by
    using the name of the user type in the AS clause:

    TYPE InventoryItem
        Description AS STRING*25
        Number AS STRING*10
        Quantity AS LONG
        OrderPoint AS LONG
    END TYPE
    DIM CurrentItem AS InventoryItem, PreviousItem AS InventoryItem

    Use the format variablename.elementname to refer to individual elements of
    the new variable, as in the following example:

    IF CurrentItem.Description = "Ergonomic Desk Chair" THEN
        PRINT CurrentItem.Number; CurrentItem.Quantity
    END IF

    If you declare a variable with an AS clause, every declaration of the
    variable must use the AS clause. For example, in the following fragment
    the AS clause is required in the COMMON statement because AS was also used
    in the DIM statement:

    CONST MAXEMPLOYEES=250
    DIM EmpNames(MAXEMPLOYEES) AS STRING
    COMMON EmpNames() AS STRING
    .
    .
    .

    2.3.2.3  DEFtype Declaration Statements

    Use the BASIC statements DEFINT, DEFLNG, DEFSTR, DEFSNG, and DEFDBL to
    declare the types for certain variable names. By using one of these
    DEFtype statements, you can specify that all variables starting with a
    given letter or range of letters are one of the elementary variable types,
    without using the trailing declaration character.

    DEFtype statements only affect variable names in the module in which they
    appear. See the DEFtype statement reference pages in Part 2, "Statement
    and Function Reference," for more information.

    The type-declaration suffixes for variable names, the type names accepted
    in AS type declarations, and the memory (in bytes) required for each
    variable type to store the variable's value are listed in Table 2.2.

    Table 2.2   Variable-Type Memory Requirements

╓┌─┌──────────────────┌─────────────────┌──────────────────┌─────────────────╖
                        AS Type           Variable           Size
    Suffix             Name              Type               of Data
                        AS Type           Variable           Size
    Suffix             Name              Type               of Data
    ──────────────────────────────────────────────────────────────────────────
    %                  INTEGER           Integer            2

    &                  LONG              Long integer       4

    !                  SINGLE            Single precision   4

    #                  DOUBLE            Double precision   8

    $                  STRING            Variable-length    Takes 4 bytes for
                                        string             descriptor, 1 byte
                                                            for each character
                                                            in string

    $                  STRING*num        Fixed-length       Takes num bytes
                                        string
    None               Declared          Record variable    Takes as many
                        user-defined type                    bytes as the
                                                            individual
                        AS Type           Variable           Size
    Suffix             Name              Type               of Data
    ──────────────────────────────────────────────────────────────────────────
                                                            individual
                                                            elements require
    ──────────────────────────────────────────────────────────────────────────


    2.3.2.4  Declaring Array Variables

    An array is a group of objects referenced with the same variable name. The
    individual values in an array are elements. Array elements are also
    variables and can be used in any BASIC statement or function that uses
    variables. You "dimension" an array when you use it the first time or when
    you declare the name, type, and number of elements in the array.

    Each element in an array is referred to by an array variable subscripted
    with an integer or an integer expression. (You may use noninteger numeric
    expressions as array subscripts; however, they are rounded to integer
    values.) The name of an array variable has as many subscripts as there are
    dimensions in the array. For example, V(10) refers to a value in a
    one-dimensional array, while T$(1,4) refers to a value in a
    two-dimensional string array.

    The default upper subscript value for any array dimension is 10. The
    maximum subscript value and the number of dimensions can be set by using
    the DIM statement. (See the reference pages for DIM in Part 2, "Statement
    and Function Reference," for more information.) The maximum number of
    dimensions for an array is 60. The maximum number of elements per
    dimension is 32,767.

    You may have arrays of any simple variable type, including records. To
    declare an array of records, first declare the data type in a TYPE
    statement and then dimension the array:

    TYPE TreeNode
        LeftPtr AS INTEGER
        RightPtr AS INTEGER
        DataField AS STRING*20
    END TYPE
    DIM Tree(500) AS TreeNode

    Each element of the array Tree is a record of type TreeNode. To use a
    particular element of a record in an array, use form
    variablename.elementname (dot notation form):

    CONST MAXEMPLOYEES=500

    TYPE EmployeeRec
        EName  AS STRING*25
        SocSec AS STRING*9
    END TYPE
    DIM Employees(MAXEMPLOYEES) AS EmployeeRec
    .
    .
    .
    PRINT Employees(I).EName;" ";Employees(I).SocSec

    Array names are distinct from simple variable names. The array variable T
    and the simple variable T in the following example are two different
    variables:

    DIM T(11)
    T = 2 : T(0) = 1                   'T is simple variable.
    FOR I% = 0 TO 10                   'T(0) is element of array.
        T(I% + 1) = T * T(I%)
    NEXT

    Array elements, like simple variables, require a certain amount of memory,
    depending on the variable type. See Table 2.2 for information on the
    memory requirements for storing individual array elements.

    To find the total amount of memory required by an array, multiply the
    number of elements by the bytes per element required for the array type.
    For example, consider the following two arrays:

    DIM Array1(1 TO 100) AS INTEGER
    DIM Array#(-5 TO 5)

    The first array, Array1, has 100 integer elements, so its values take 200
    bytes of memory. The second array, Array2, has 11 double-precision
    elements, so its values require 88 bytes of memory. Because BASIC must
    store information about the array along with the array's values, arrays
    take more memory than just the space for the values.

2.3.3  Variable Storage Allocation

    BASIC stores different kinds of variables in different areas in memory.
    You need to worry about where variables are stored only if you are either
    doing mixed-language programming or using one of the following BASIC
    statements or functions:

    ■ CALL, CALLS (non-BASIC procedures)

    ■ DECLARE (non-BASIC procedures)

    ■ SADD

    ■ SETMEM

    ■ VARPTR

    ■ VARSEG

    ■ VARPTR$

    BASIC stores variables either in an area called DGROUP or as far objects.
    (DGROUP is the name of the default data segment, the segment referenced
    when DEF SEG is used without an address.) Variables stored in DGROUP can
    be referenced by using near addresses or pointers. A near address consists
    of a single value or offset from the beginning of a segment or block of
    memory. Far objects are referenced by using far addresses or pointers. A
    far address consists of two parts: the starting address of a segment or
    block of memory and the offset within the segment. See the entries for the
    statements listed above for information about getting and using far
    pointers.

    Whether a variable is stored in DGROUP or as a far object depends first on
    whether it is a simple variable or an array. All simple variables are
    stored in DGROUP. Array storage is a little more complex and is slightly
    different between programs run as .EXE files and programs run within the
    QuickBASIC environment.

    In programs run as .EXE files, array variables are stored as follows:

    ■ All static arrays are stored in DGROUP and can be referenced with near
    addresses.

    ■ All dynamic arrays of variable-length strings are also stored in DGROUP
    and can also be referenced with near addresses.

    ■ All other dynamic arrays are stored as far objects and require far
    addresses.

    See Section 2.5 for a description of static and dynamic arrays. In
    programs run within the QuickBASIC environment, array variable storage
    follows these rules:

    ■ All static arrays in a COMMON block are stored in DGROUP and can be
    referenced with near addresses.

    ■ All arrays of variable-length strings are also stored in DGROUP and can
    also be referenced with near addresses.

    ■ All other arrays are stored as far objects and require far addresses.

    Because BASIC attempts to make the most efficient use of memory
    possible, several different things may cause a variable's memory
    location to change. These include a reference to a string literal or
    expression, the invocation of a DEF FN or FUNCTION, the use of a BASIC
    string or memory-related function, and a reference to an implicitly
    dimensioned array.

    To generate accurate results and because BASIC variables may move, use the
    results of VARPTR, VARSEG, VARTPR$, or SADD immediately after a function
    call that affects a variable.


2.4  Scope of Variables and Constants

    Any time a variable appears, BASIC follows a set of rules in determining
    to which object the variable refers. These rules describe a variable's
    scope──the range of statements over which the variable is defined.

    The BASICA interpreter has a very simple scope rule: a variable exists
    when you first use it and persists until the program ends. The scope of a
    variable is from its first use through the end of the program.

    In QuickBASIC, you can control the scope of variables and symbolic
    constants──which helps you write compact, well-defined SUB and FUNCTION
    procedures that don't interfere with each other. You can also make some
    variables available to all procedures in a module, and thereby share
    important data structures among procedures.

    You may think of variables and constants as having one of two scopes:
    global or local. Global variables, once declared, may be used anywhere in
    a module to refer to some single object. Local variables are local to some
    part of the module, the module-level code or one of the procedures. In
    addition, variables can be shared in such a way that they aren't quite
    global, nor are they completely local.

    The rest of this section discusses global and local scope, and shared
    variables. The following skeleton of a program is used in this discussion.
    The program, a main program and two procedures, replaces runs of blanks in
    a file with tab characters──a simple first step in compressing a file.
    (The program is included on the QuickBASIC release disks in the file
    ENTAB.BAS.)

    DEFINT a-z
    DECLARE FUNCTION ThisIsATab(Column AS INTEGER)

    CONST MAXLINE=255, TABSPACE=8
    CONST NO=0, YES=NOT NO
    DIM SHARED TabStops(MAXLINE)
    .
    .
    .
    ' Set the tab positions (uses the global array TabStops).
    CALL SetTabPos
    .
    .
    .
        IF ThisIsATab(CurrentColumn) THEN
            PRINT CHR$(9);
            LastColumn=CurrentColumn
        END IF
    .
    .
    .

    '==================SUB SetTabPos=========================
    ' Set the tab positions in the array TabStops.
    '
    SUB SetTabPos STATIC
        FOR I=1 TO MAXLINE
        TabStops(I)=((I MOD TABSPACE)=1)
        NEXT I
    END SUB

    '===============FUNCTION ThisIsATab======================
    ' Answer the question, "Is this a tab position?"
    '
    FUNCTION ThisIsATab(LastColumn AS INTEGER) STATIC
        IF LastColumn>MAXLINE THEN
        ThisIsATab=YES
        ELSE
        ThisIsATab=TabStops(LastColumn)
        END IF
    END FUNCTION

2.4.1  Global Variables and Constants

    Both variables and symbolic constants can be global in BASIC programs. A
    global variable or global symbolic constant is defined for the entire
    module. For a variable, the only way to make it global is to declare it in
    the module-level code with the SHARED attribute in a DIM, REDIM, or COMMON
    statement. A symbolic constant is a global constant if it is declared in
    the module-level code using a CONST statement.

    In the sample program, the array TabStops is a global variable. Because
    TabStops is declared in a DIM statement with the SHARED attribute, it is
    shared with every procedure in the module. Notice that both procedures in
    the program (ThisIsATab and SetTabPos) use TabStops by making a reference
    to it. Global variables do not require any additional declarations to be
    used in procedures in the module. Similarly, the symbolic constants
    MAXLINE and TABSPACE are global constants. If you use the name of a global
    variable or constant in a procedure, you are referring to the global
    variable and not a local variable of the same name.

────────────────────────────────────────────────────────────────────────────
NOTE
    The SHARED statement allows procedures to share variables with the
    module-level code. This is not the same as making the variable global. See
    Section 2.4.3 below, "Sharing Variables," for more information.
────────────────────────────────────────────────────────────────────────────

2.4.2  Local Variables and Constants

    A local variable or constant exists only within a procedure or the
    module-level code. If the name of a local variable is used in another
    procedure in a module, the name represents a different variable and refers
    to a different object.

    The sample program ENTAB.BAS above includes many local variables. The
    variables CurrentColumn and LastColumn are local to the module-level code.
    The variable I is local to the subprogram SetTabPos. Finally, the variable
    LastColumn in the parameter list of ThisIsATab can be thought of as a
    local variable because it is a formal parameter. (Remember, however, that
    a formal parameter stands for the actual argument passed to the procedure.
    See Section 4.3, "Passing by Reference and Passing by Value," for
    additional information.)

    It is simplest to think of a local variable as any variable that isn't
    global. Any variable that appears in module-level code or in a procedure
    is local if it isn't declared in a DIM, REDIM, or COMMON statement with
    the SHARED attribute. (There is one exception. See Section 2.4.3,
    "Sharing Variables," below.) Even if a variable appears in one of these
    statements, you may still use a local variable of the same name in a
    procedure by declaring the variable in a STATIC statement. If the sample
    program had a DIM SHARED statement declaring I to be a global variable in
    the main program, you could make I a local variable in SetTabPos by adding
    a STATIC statement just after the SUB statement:

    SUB SetTabPos STATIC
    STATIC I
    .
    .
    .

    Any symbolic constant declared inside a SUB or FUNCTION procedure is a
    local constant. For example, in the following fragment, ENDOFLIST is a
    local symbolic constant that exists only in the function FindElement:
    FUNCTION FindElement(X())
    CONST ENDOFLIST = -32767
    .
    .
    .
    END FUNCTION

────────────────────────────────────────────────────────────────────────────
NOTE
    The STATIC statement not only declares a variable to be local: it also
    directs the compiler to save the value of the variable between procedure
    calls. Do not use STATIC statements in recursive procedures if you do not
    want a variable's value saved between calls. See Section 2.6, "Automatic
    and STATIC Variables," for more information.
────────────────────────────────────────────────────────────────────────────

2.4.3  Sharing Variables

    You can share variables among parts of a module without making the
    variables global by using the SHARED statement. For example, to share
    TabStops without making it a global variable, you would remove the SHARED
    attribute in the module-level code and add SHARED statements to the two
    procedures:

    DIM TabStops(MAXLINE)
    .
    .
    .
    SUB SetTabPos STATIC
    SHARED TabStops()
    .
    .
    .
    FUNCTION ThisIsATab(LastColumn AS INTEGER) STATIC
    SHARED TabStops()
    .
    .
    .

    The SHARED statements indicate that the name TabStops in both procedures
    refers to the same variable defined at the module level.

2.4.4  DEF FN Functions

    The DEF FN function is an exception to the BASIC scope rules. Every
    variable in a DEF FN function that isn't in its parameter list is part of
    the module-level code. To make a variable local to a DEF FN, you must
    declare the variable in a STATIC statement. The STATIC statement in the
    following DEF FN function makes the variable I local:

    CONST NO = 0, YES = NOT NO

    DEF FNIsThereAZ (A$)
    STATIC I
        FOR I = 1 TO LEN(A$)
        IF UCASE$(MID$(A$, I, 1)) = "Z" THEN
            FNIsThereAZ = YES
            EXIT DEF
        END IF
        NEXT I
        FNIsThereAZ = NO
    END DEF

    Remember, as a general rule a FUNCTION is preferred over a DEF FN because
    of the improved portability and increased modularity the FUNCTION
    provides.

2.4.5  Summary of Scope Rules

    The following list summarizes BASIC's scope rules:

    ■ A variable declared in a DIM, REDIM, or COMMON statement with the SHARED
    attribute is a global variable. Any SUB or FUNCTION procedure can refer
    to the variable.

    ■ A symbolic constant is global if it is declared in a CONST statement in
    the module-level code. Symbolic constants declared in a SUB or FUNCTION
    are local.

    ■ A variable is a local variable if it appears in a procedure and is not
    declared as a global variable. You can use the name of a global variable
    as a local variable in a procedure by declaring it in the procedure with
    the STATIC statement or by using it as a formal parameter.

    ■ The SHARED statement lets you share a variable with the module-level
    code and other procedures with equivalent SHARED statements without
    making the variable a global variable.

    ■ All variables in a DEF FN function are part of the module-level code
    unless they are either explicitly made local in a STATIC statement or
    are formal parameters.


2.5  Static and Dynamic Arrays

    You can get better control of your program's use of memory by controlling
    when storage is set aside for arrays. Storage for arrays can be set aside
    when the program is compiled or when the program is running. Arrays given
    storage when the program is compiled are static arrays. Dynamic arrays
    have storage set aside when the program is run. The storage taken by
    dynamic arrays can be eliminated while the program is not running in order
    to free memory for other uses. See the entries for DIM, ERASE, and REDIM
    in Part 2, "Statement and Function Reference," for specific information
    about manipulating dynamic arrays.

    How an array is declared can determine whether the array is static or
    dynamic. By default, arrays dimensioned with constant subscripts or arrays
    that are implicitly dimensioned are static arrays. Arrays dimensioned with
    variable subscripts or that are first declared in a COMMON statement are
    dynamic arrays. In a SUB or FUNCTION not declared static, all arrays are
    dynamic.

    You can also use the ¢STATIC and ¢DYNAMIC metacommands to control how
    array storage is allocated. However, the ¢STATIC metacommand cannot force
    arays to be static in a procedure not declared static; in such a procedure
    all arrays are dynamic. See Appendix F, "Metacommands," in Programming in
    BASIC for more information.

    In some cases, you can allow more space for strings by replacing static
    arrays with dynamic arrays. In programs run as .EXE files, the space for
    static arrays is allocated from DGROUP, an area where strings are stored.
    On the other hand, dynamic arrays, other than variable-length string
    arrays, do not take any space in DGROUP; they are stored as far objects
    and require far addresses.


2.6  Automatic and Static Variables

    BASIC procedures can use both automatic and static variables. Automatic
    variables are initialized at the start of each call to the FUNCTION or
    SUB; static variables retain values between calls.

    You can control whether the default is automatic or static by using or
    omitting the STATIC keyword in the SUB or FUNCTION statement. If you omit
    STATIC, then the default for variables is automatic. When you use STATIC,
    the default for all variables in the procedure is static: the values of
    the variables are saved between procedure calls.

    You can make selected variables in a procedure static by making the
    default automatic (omitting STATIC from the SUB or FUNCTION statement) and
    using the STATIC statement. The following program uses a FUNCTION that has
    two static variables: Start% and SaveStr$. The other variables are
    automatic. The FUNCTION takes a string and returns one token──a string of
    characters──until the end of the string is reached. On the first call,
    StrTok$ makes a local copy of the string Srce$ in the static variable
    SaveStr$. After the first call, StrTok$ returns additional tokens from the
    string using the static variable Start% to remember where it left off. All
    of the other variables (BegPos%, Ln%, etc.) are automatic. (This program
    is included on the QuickBASIC distribution disks under the file name
    TOKEN.BAS.)

    DECLARE FUNCTION StrTok$(Source$,Delimiters$)

    LINE INPUT "Enter string: ",P$
    ' Set up the characters that separate tokens.
    Delimiters$=" ,;:().?"+CHR$(9)+CHR$(34)
    ' Invoke StrTok$ with the string to tokenize.
    Token$=StrTok$(P$,Delimiters$)
    WHILE Token$<>""
        PRINT Token$
        ' Call StrTok$ with a null string so it knows this
        ' isn't the first call.
        Token$=StrTok$("",Delimiters$)
    WEND

    FUNCTION StrTok$(Srce$,Delim$)
    STATIC Start%, SaveStr$

        ' If first call, make a copy of the string.
        IF Srce$<>"" THEN
        Start%=1 : SaveStr$=Srce$
        END IF

        BegPos%=Start% : Ln%=LEN(SaveStr$)
        ' Look for start of a token (character that isn't
        ' delimiter).
        WHILE(BegPos%<=Ln% AND INSTR(Delim$,MID$(SaveStr$,BegPos%,1))<>0)
        BegPos%=BegPos%+1
        WEND
        ' Test for token start found.
        IF BegPos% > Ln% THEN
        StrTok$="" : EXIT FUNCTION
        END IF
        ' Find the end of the token.
        End%=BegPos%
        WHILE(End%<=Ln%AND INSTR(Delim$,MID$(SaveStr$,End%,1))=0)
        End%=End%+1
        WEND

    StrTok$=MID$(SaveStr$,BegPos%,End%-BegPos%)
        ' Set starting point for search for next token.
        Start%=End%

    END FUNCTION

    Output

    Enter string: Allen spoke: "What's a hacker, anyway?"
    Allen
    spoke
    What's
    a
    hacker
    anyway


2.7  Type Conversion

    When necessary, BASIC converts a numeric constant from one type to
    another, according to the following rules:

    ■ If a numeric constant of one type is set equal to a numeric variable of
    a different type, the numeric constant is stored as the type declared in
    the variable name, as in the following example:

    A% = 23.42
    PRINT A%

    Output

    23

    If a string variable is set equal to a numeric value, or vice versa, an
    error message is generated that reads Type Mismatch.

    ■ During expression evaluation, the operands in an arithmetic or
    relational operation are converted to the same degree of precision, that
    of the most precise operand, as each operation is performed. Also, the
    result of an arithmetic operation is returned to the final degree of
    precision, as in this example:

    X% = 2 : Y! = 1.5 : Z# = 100
    A! = X% / Y!
    PRINT A! * Z#

    Output

    133.3333373069763

    Although the preceding result is displayed in double precision (because
    of the double-precision variable Z#), it has only single-precision
    accuracy because the assignment to A! forced the result of X% / Y! to be
    reduced to single-precision accuracy. This explains the nonsignificant
    digits (73069763) after the fifth decimal place. Contrast this with the
    output from the following example in which the intermediate result of X%
    / Y! is retained in double-precision:

    X% = 2 : Y# = 1.5 : Z# = 100
    PRINT X% / Y# * Z#

    Output

    133.3333333333333

    ■ Logical operators such as AND and NOT convert their operands to long
    integers if necessary. Operands must be in the range -2,147,483,648 to
    +2,147,483,647 or an Overflow error message is generated. See Chapter
    3, "Expressions and Operators," for more information on logical
    operators.

    ■ When a floating-point value is converted to an integer, the fractional
    portion is rounded, as in this example:

    Total% = 55.88
    PRINT Total%

    Output

    56



────────────────────────────────────────────────────────────────────────────
Chapter 3   Expressions and Operators

        3.1  Expressions and Operators Defined
        3.2  Hierarchy of Operations
        3.3  Arithmetic Operators
        3.3.1   Integer Division
        3.3.2   Modulo Arithmetic
        3.3.3   Overflow and Division by Zero
        3.4  Relational Operators
        3.5  Logical Operators
        3.6  Functional Operators
        3.7  String Operators

    This chapter discusses how to combine, modify, compare, or get information
    about expressions by using the operators available in BASIC.

    Anytime you do a calculation or manipulate a string, you are using
    expressions and operators. This chapter describes how expressions are
    formed, discusses the order in which BASIC uses operators, and concludes
    by describing the following five kinds of operators:

    ■ Arithmetic operators, used to perform calculations

    ■ Relational operators, used to compare strings and numeric values

    ■ Logical operators, used to test complex conditions or manipulate
    individual bits

    ■ Functional operators, used to supplement simpler operators

    ■ String operators, used to combine and compare strings


3.1  Expressions and Operators Defined

    An expression can be a string or numeric constant, a variable, or a single
    value obtained by combining constants, variables, and other expressions
    with operators. Operators perform mathematical or logical operations on
    values. The operators provided by BASIC can be divided into five
    categories, as follows:

    1. Arithmetic

    2. Relational

    3. Logical

    4. Functional

    5. String


3.2  Hierarchy of Operations

    The BASIC operators have an order of precedence: when several operations
    take place within the same program statement, some operations are done
    before others. Operations are executed in the following order:

    1. Arithmetic operations

        a. Exponentiation (^)

        b. Negation (-)

        c. Multiplication and division (*,/)

        d. Integer division (\)

        e. Modulo arithmetic (MOD)

        f. Addition and subtraction (+,-)

    2. Relational operations (=, >, <, <>, <=, >=)

    3. Logical operations

        a. NOT

        b. AND

        c. OR

        d. XOR

        e. EQV

        f. IMP

    An exception to the order of operations listed above occurs when an
    expression has adjacent exponentiation and negation operators. In this
    case, the negation is done first. For example, the following statement
    prints the value .0625 (equivalent to 4^-2), not -16 (equivalent to
    -(4^2)):

    PRINT 4 ^ - 2

    If the operations are different and are of the same level, the leftmost
    one is executed first and the rightmost last, as explained below.

    A = 3 + 6 / 12 * 3 - 2    'A = 2.5

    The order of operations in the preceding example is as follows:

    Operation                Result
    ──────────────────────────────────────────────────────────────────────────
    6 / 12                   0.5
    0.5 * 3                  1.5
    3 + 1.5                  4.5
    4.5 - 2                  2.5
    ──────────────────────────────────────────────────────────────────────────

    In a series of additions or a series of multiplications, there is no fixed
    evaluation order. Either 3 + 5 or 5 + 6 may be calculated first in the
    following statement:

    C = 3 + 5 + 6

    Usually this does not cause problems. However, it may cause a problem if
    you have a series of FUNCTION procedure calls:

    C = Incr(X) + Decr(X) + F(X)

    If any of the three FUNCTION procedures modify X or change shared
    variables, the result depends on the order in which BASIC does the
    additions. You can avoid the situation by assigning the results of the
    FUNCTION calls to temporary variables and then performing the addition:

    T1 = Incr(X) : T2 = Decr(X) : T3 = F(X)
    C = T1 + T2 + T3


3.3  Arithmetic Operators

    Parentheses change the order in which arithmetic operations are performed.
    Operations within parentheses are performed first. Inside parentheses, the
    usual order of operation is maintained. Here are some sample algebraic
    expressions and their BASIC counterparts:

    Algebraic Expression     BASIC Expression
    ──────────────────────────────────────────────────────────────────────────
    X - Y
    -----                    (X-Y)/Z
    Z

    XZ
    ---                      X*Y/Z
    Z

    X + Y
    -----                    (X+Y)/Z
    Z

    (X<^>2)<^>Y              (X^2)^Y

    X<^>YZ                   X^(Y*Z)

    X(-Y)                    X*(-Y)
    ──────────────────────────────────────────────────────────────────────────

    :BTGenerally, two consecutive operators must be separated by parentheses.
    Exceptions to this rule are * - , * +, ^ -, and ^ + . The last expression
    in the right-hand column above could also be written X*-Y.

    See the preceding section for information about the order in which
    arithmetic operations are performed.

3.3.1  Integer Division

    Integer division is denoted by the backslash (\) instead of the forward
    slash (/), which indicates floating-point division. Before integer
    division is performed, operands are rounded to integers or long integers,
    and thus must be greater than -2,147,483,648.5 and less than
    +2,147,483,647.5. The quotient of an integer division is truncated to an
    integer, as illustrated below:

    PRINT 10\4, 10/4, -32768.499\10, -32768.499/10

    Output

    2             2.5          -3276         -3276.8499

3.3.2  Modulo Arithmetic

    Modulo arithmetic is denoted by the modulus operator MOD. Modulo
    arithmetic provides the remainder, rather than the quotient, of an integer
    division, as in this example:

    X% = 10.4\4
    REMAINDER% = INT(10.4) - 4*X%
    '10\4 = 2, with remainder 2
    PRINT REMAINDER%, 10.4 MOD 4

    Output

    2             2

3.3.3  Overflow and Division by Zero

    Dividing by zero, raising zero to a negative power, and arithmetic
    overflow produce run-time errors. These errors can be trapped by an
    error-trapping routine. See Chapter 6, "Error and Event Trapping," in
    Programming in BASIC for more information about writing error-trapping
    routines.


3.4  Relational Operators

    Relational operators are used to compare two values, as shown in Table
    3.1. The result of the comparison is either "true" (nonzero) or "false"
    (zero). This result can then be used to make a decision regarding program
    flow. Although BASIC treats any nonzero value as true, true is usually
    represented by -1.

    Table 3.1   Relational Operators and Their Functions

    Operator           Relation Tested                      Expression
    ──────────────────────────────────────────────────────────────────────────
    =                  Equality☼                            X = Y
    < >                Inequality                           X < > Y
    <                  Less than                            X < Y
    >                  Greater than                         X > Y
    <=                 Less than or equal to                X <= Y
    =                  Greater than or equal to             X >= Y
    ──────────────────────────────────────────────────────────────────────────

    When arithmetic and relational operators are combined in one expression,
    the arithmetic operations are always done first. For example, the
    following expression is true if the value of X + Y is less than the value
    of (T - 1)/Z:

    X + Y < (T - 1)/Z

    Be careful using relational operators with single- and double-precision
    values. Calculations may give extremely close but not identical results.
    In particular, avoid testing for identity between two values. For example,
    the PRINT statement in the following IF statement is not executed unless
    A! is exactly equal to 0.0:

    IF A! = 0.0 THEN PRINT "Exact result."

    When A! is an extremely small value, for example 1.0E-23, the PRINT
    statement is not executed.

    In addition, a compiled program (an .EXE file) may give different results
    than the same program run in the QuickBASIC environment. Files with the
    .EXE extension23 contain more efficient code that may change the way
    single- and double-precision values are compared. For example, the
    following fragment prints Equal when run in the environment, but prints
    Not Equal when compiled:

    B!=1.0
    A!=B!/3.0
    IF A!=B!/3.0 THEN PRINT "Equal" ELSE PRINT "Not Equal"

    Because the .EXE file version makes more extensive use of a math
    coprocessor chip (or coprocessor emulation), A! and B!/3.0 are slightly
    different values.

    You can avoid problems in comparisons by performing calculations outside
    comparisons. The following rewritten fragment produces the same results in
    the environment and as an .EXE file:

    B!=1.0
    A!=B!/3.0
    Tmp!=B!/3.0
    IF A!=Tmp! THEN PRINT "Equal" ELSE PRINT "Not Equal"


3.5  Logical Operators

    Logical operators perform tests on multiple relations, bit manipulations,
    or Boolean operations and return a true (nonzero) or false (zero) value to
    be used in making a decision.

■ Examples

    IF D < 200 AND F < 4 THEN 80

    WHILE I > 10 OR K < 0
    .
    .
    .
    WEND

    IF NOT P THEN PRINT "Name not found"

    There are six logical operators in BASIC; they are listed in Table 3.2 in
    order of precedence:

    Table 3.2   BASIC Logical Operators

    Operator                 Meaning
    ──────────────────────────────────────────────────────────────────────────
    NOT                      Logical complement
    AND                      Conjunction
    OR                       Disjunction (inclusive "or")
    XOR                      Exclusive "or"
    EQV                      Equivalence
    IMP                      Implication
    ──────────────────────────────────────────────────────────────────────────

    Each operator returns results as indicated in Table 3.3. A "T" indicates
    a true value and an "F" indicates a false value. Operators are listed in
    order of operator precedence.

    Table 3.3   Values Returned by Logical Operations

    Values of                  Value Returned by Logical Operator
                                X        X        X         X        X
                        NOT      AND      OR       XOR       EQV      IMP
    X        Y          X        Y        Y        Y         Y        Y
    ──────────────────────────────────────────────────────────────────────────
    T        T          F        T        T        F         T        T
    T        F          F        F        T        T         F        F
    F        T          T        F        T        T         F        T
    F        F          T        F        F        F         T        T
    ──────────────────────────────────────────────────────────────────────────

    In an expression, logical operations (also known as Boolean operations)
    are performed after arithmetic and relational operations. The operands of
    logical operators must be in the range -2,147,483,648 to +2,147,483,647.
    Operands are converted to integers (or, if necessary, long integers)
    before the logical operation is done. (If the operands are not in this
    range, an error results.) If the operands are either 0 or -1, logical
    operators return 0 or -1 as the result, as in the following example. (Note
    the similarity of the output from this program to Table 3.3: "T" becomes
    -1 and "F" becomes 0.)

■ Example

    PRINT " X       Y      NOT     AND     OR      ";
    PRINT "XOR     EQV     IMP"
    PRINT
    I = 10 : J = 15
    X = (I = 10) : Y = (J = 15)  'X is true (-1); Y is true (-1)
    CALL TruthTable (X,Y)
    X = (I > 9) : Y = (J > 15)   'X is true (-1); Y is false (0)
    CALL TruthTable (X,Y)
    X = (I <> 10) : Y = (J < 16) 'X is false (0); Y is true (-1)
    CALL TruthTable (X,Y)
    X = (I < 10) : Y = (J < 15)  'X is false (0); Y is false (0)
    CALL TruthTable (X,Y)
    END

    SUB TruthTable(X,Y) STATIC
    PRINT X "    " Y "    ";NOT X "   " X AND Y "     " X OR Y;
    PRINT "    " X XOR Y "    " X EQV Y "    " X IMP Y
    PRINT
    END SUB

    Output

    X      Y     NOT    AND     OR     XOR    EQV    IMP

    -1     -1      0     -1     -1      0     -1     -1

    -1      0      0      0     -1     -1      0      0

    0     -1     -1      0     -1     -1      0     -1

    0      0     -1      0      0      0     -1     -1

    Logical operators compare each bit of the first operand with the
    corresponding bit in the second operand to compute the bit in the result;
    in these "bit-wise" comparisons, a 0 bit is equivalent to a "false" value
    (F) in Table 3.3, while a 1 bit is equivalent to a "true" value (T).

    It is possible to use logical operators to test bytes for a particular bit
    pattern. For example, the AND operator can be used to mask all but one of
    the bits of a status byte, while the OR operator can be used to merge two
    bytes to create a particular binary value.

■ Example

    PRINT 63 AND 16

    PRINT -1 AND 8

    PRINT 10 OR 9

    PRINT 10 XOR 10,           'Always 0

    PRINT NOT 10, NOT 11, NOT 0     'NOT X = -(X + 1)

    Output

    16
    8
    11
    0          -11           -12           -1

    The first PRINT statement uses AND to combine 63 (111111 binary) and 16
    (10000). When BASIC calculates the result of an AND, it combines the
    numbers bit by bit, producing a one only when both bits are one. Because
    the only bit that is a one in both numbers is the fifth bit, only the
    fifth bit in the result is a one. The result is 16, or 10000 in binary. In
    the second PRINT statement, the numbers -1 (binary 1111111111111111) and 8
    (binary 1000) are combined using another AND operation. The only bit that
    is a one in both numbers is the fourth bit, so the result is 8 decimal or
    1000 binary. The third PRINT statement uses an OR to combine 10 (binary
    1010) and 9 (binary 1001). An OR produces a one bit whenever either bit is
    a one, so the result of the OR in the third PRINT is 11 (binary 1011). The
    XOR in the fourth PRINT combines the number 10 (1010 binary) with itself.
    The result is a zero because an XOR produces a one only when either, but
    not both, bits are one.

    Performing a NOT on a number changes all one bits to zeros and all zero
    bits to ones. Because of the way two's complement numbers work, taking the
    NOT of a value is the same as adding one to the number and then negating
    the number. In the final PRINT statement, the expression NOT 10 yields a
    result of -11.


3.6  Functional Operators

    A function is used in an expression to call a predetermined operation to
    be performed on an operand. For example, SQR is a functional operator used
    twice in the following assignment statement:

    A = SQR (20.25) + SQR (37)

    BASIC incorporates two kinds of functions: intrinsic and user-defined.
    Many predefined (intrinsic) functions are built into the language.
    Examples are the SQR (square root) and SIN (sine) functions.

    You may define your own functions with the FUNCTION...END FUNCTION
    construction and the older, obsolete DEF FN...END DEF construction. Such
    functions are defined only for the life of the program (unless they are in
    a Quick library) and are not part of the BASIC language. In addition to
    FUNCTION and DEF FN, BASIC allows you to define subprograms with SUB. For
    more information on defining your own functions and subprograms, see the
    appropriate entries in Chapter 4, "Programs and Modules," and Part 2,
    "Statement and Function Reference," in this manual, as well as Chapter 2,
    "SUB and FUNCTION Procedures," in Programming in BASIC.


3.7  String Operators

    A string expression consists of string constants, string variables, and
    other string expressions combined by string operators. There are two
    classes of string operations: concatenation and string function.

    The act of combining two strings is called concatenation. The plus symbol
    (+) is the concatenation operator for strings. For example, the following
    program fragment combines the string variables A$ and B$ to produce the
    output shown:

    A$ = "FILE": B$ = "NAME"
    PRINT A$ + B$
    PRINT "NEW " + A$ + B$

    Output

    FILENAME
    NEW FILENAME

    Strings can be compared using the following relational operators (see
    Table 3.1):

    < > = < > <= >=

    Note that these are the same relational operators used with numbers.

    String comparisons are made by taking corresponding characters from each
    string and comparing their ASCII codes. If the ASCII codes are the same
    for all the characters in both strings, the strings are equal. If the
    ASCII codes differ, the lower code number precedes the higher. If the end
    of one string is reached during string comparison, the shorter string is
    smaller if they are equal up to that point. Leading and trailing blanks
    are significant. The following are examples of true string expressions:

    "AA" < "AB"
    "FILENAME" = "FILE"+"NAME"
    "X&" > "X#"
    "CL " > "CL"
    "kg" > "KG"
    "SMYTH" < "SMYTHE"
    B$ < "9/12/78"              'where B$ = "8/12/85"

    String comparisons can be used to test string values or to alphabetize
    strings. All string constants used in comparison expressions must be
    enclosed in quotation marks. See Appendix A, "Keyboard Scan Codes and
    ASCII Character Codes," for more information about the ASCII codes.



────────────────────────────────────────────────────────────────────────────
Chapter 4   Programs and Modules

        4.1  Modules
        4.2  Procedures
        4.2.1   FUNCTION Procedures
        4.2.2   SUB Procedures
        4.2.3   DEF FN Functions
        4.3  Passing by Reference and Passing by Value
        4.4  Recursion

    This chapter discusses the largest parts of a program──modules and
    procedures. The chapter describes how modules are organized and how BASIC
    procedures communicate with other parts of a program.

    Specifically, the chapter explains how to

    ■ Organize modules

    ■ Understand different kinds of QuickBASIC procedures

    ■ Pass arguments to a procedure

    ■ Write recursive code


4.1  Modules

    BASIC programs consist of one or more modules. A module is a source file
    that can be separately compiled. Declarations, executable statements──any
    BASIC statement──can appear in a module.

    A module may contain SUB and FUNCTION procedures, as well as code not
    directly part of a SUB or FUNCTION. Statements that are not part of a SUB
    or FUNCTION are called module-level code. Module-level code includes
    declarative statements like DIM and TYPE as well as error- and
    event-handling code.

    A program has one special module, the main module. The main module
    contains the entry point of the program (the place where the program
    starts running). Each program contains only one main module; module-level
    code it contains corresponds to what is often called the main program.


4.2  Procedures

    This section discusses the two newer QuickBASIC procedures: FUNCTION
    procedures and SUB procedures. It also covers the older DEF FN function
    and compares it with the newer procedures.

    See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for
    examples and information about when to use different kinds of procedures.

4.2.1  FUNCTION Procedures

    FUNCTION procedures provide a powerful alternative to DEF FN functions.
    Like DEF FN functions, FUNCTION procedures are used in expressions and
    directly return a single value. There are, however, important differences.

    FUNCTION procedures pass values by reference, so a FUNCTION procedure can
    return additional values by changing variables in its argument list. In
    addition, FUNCTION procedures can be used recursively──a function can call
    itself (see Section 4.4 below for more information).

    Unlike DEF FN functions, a FUNCTION procedure may be used outside the
    module in which it is defined. You must include a DECLARE statement if you
    use a FUNCTION defined in another module. QuickBASIC automatically
    generates DECLARE statements for FUNCTION procedures defined and used in
    the same module. You can also enter the DECLARE yourself:

    DECLARE FUNCTION Log10(X)

    INPUT "Enter a number: ",Num
    PRINT "10 ^ Log10(";Num;") is" 10.0^Log10(Num)
    END
    ' Function to find log base 10 of a number using
    ' BASIC's built-in natural logarithm function.
    FUNCTION Log10 (X) STATIC
        Log10=LOG(X)/LOG(10.0)
    END FUNCTION

    FUNCTION procedures also differ from DEF FN functions in that they are not
    part of the module-level code.

4.2.2  SUB Procedures

    Unlike DEF FN functions and FUNCTION procedures, SUB is invoked as a
    separate statement:

    ' Print a message in the middle of the screen.
    CLS
    CALL PrntMsg(12,40,"Hello!")
    END

    ' Print message at the designated row and column.
    SUB PrntMsg(Row%,Col%,Message$) STATIC
        ' Save current cursor position.
        CurRow%=CSRLIN
        CurCol%=POS(0)
        ' Print the message at the location.
        LOCATE Row%,Col% : PRINT Message$;
        ' Restore cursor location.
        LOCATE CurRow%,CurCol%
    END SUB

    SUB procedures can be used to return multiple values to a calling routine
    and are not invoked as part of an expression.

    All SUB arguments are passed by reference. This allows SUB procedures to
    return values by changing variables in the argument list──the only way a
    SUB can return a value.

    You can invoke SUB procedures without using the CALL keyword if the SUB is
    declared:

    DECLARE SUB PrntMsg (Row%,Col%,Msg$)

    ' Print a message in the middle of the screen.
    CLS
    PrntMsg 12,40,"Hello!"    'Note the missing parentheses.
    END
    .
    .
    .

    SUB procedures can be used recursively──that is, you can write a SUB
    procedure that calls itself.

4.2.3  DEF FN Functions

    DEF FN functions are always part of a program's module-level code. For
    this reason, their use is more limited than that of SUB or FUNCTION
    procedures. Like FUNCTION procedures, DEF FN functions return single
    values and are used like built-in BASIC functions:

    ' Function to find log base 10 of a number using
    ' BASIC's built-in natural logarithm function.
    DEF FNLog10 (X)
        FNLog10=LOG(X)/LOG(10.0)
    END DEF

    INPUT "Enter a number: ",Num
    PRINT "10 ^ Log10(";Num;") is" 10.0^FNLog10(Num)
    END

    DEF FN function arguments are passed by value (see Section 4.3 below for
    more information). The name of a DEF FN function always begins with FN. In
    addition, DEF FN functions cannot be used recursively and must be defined
    before they are used. DEF FN functions cannot be called from outside the
    module in which they are defined.


4.3  Passing by Reference and Passing by Value

    BASIC uses two different ways of passing arguments to a procedure. The
    phrase "passing by reference," used with SUB and FUNCTION procedures,
    means the address of each argument is passed to the procedure by placing
    the address on the stack. The phrase "passing by value," used in DEF FN
    functions, indicates that the value of the argument is placed on the
    stack, rather than the address. Because the procedure does not have access
    to the variable when an argument is passed by value, the procedure cannot
    change the variable's value.

    Sometimes passing an argument by value to a SUB or FUNCTION is more
    convenient. You can simulate a pass by value by using an expression in the
    SUB call or FUNCTION invocation:

    Xcoordinate=Transform((A#))

    Because(A#) is an expression, BASIC calculates its value, A#, and passes
    the address of a temporary location containing the value. An address is
    still passed, but because it is the address of a temporary location, the
    action simulates a pass by value.


4.4  Recursion

    QuickBASIC lets you write recursive SUB or FUNCTION procedures (procedures
    that call themselves). For example, the following program uses a recursive
    FUNCTION to reverse a string of characters:

    DECLARE FUNCTION Reverse$ (StringVar$)

    LINE INPUT "Enter string to reverse: ", X$
    PRINT Reverse$(X$)

    END

    FUNCTION Reverse$ (S$)

        C$ = MID$(S$, 1, 1)
        IF C$ = "" THEN
        ' The first character is null, so return
        ' null--there's no more string left.
        Reverse$ = ""
        ELSE
        ' The reverse of a nonnull string is the first
        ' character appended to the reverse of the remaining
        ' string.
        Reverse$ = Reverse$(MID$(S$, 2)) + C$
        END IF

    END FUNCTION

    Output

    Enter string to reverse: abcdefgh...tuvwxyz
    zyxwvut...hgfedcba

    Reverse$ reverses a string by first testing for the simplest case──a null
    string. If the string is null, then a null string is returned. If the
    string is not null──there are characters──then Reverse$ simplifies the
    problem. The reverse of a non-null string is the rest of the string (C$)
    with the first character of the string concatenated to it. So Reverse$
    calls itself to reverse the rest of the string and when this is done
    concatenates the first character to the reversed string.

    Recursion can use a lot of memory because automatic variables inside the
    FUNCTION or SUB must be saved in order to restart the procedure when the
    recursive call is finished. Because automatic variables are saved on the
    stack, you may need to increase the stack size with the CLEAR statement to
    keep from running out of stack space. Use the FRE function to determine by
    how many bytes you need to adjust the stack size.



────────────────────────────────────────────────────────────────────────────
PART 2  STATEMENT AND FUNCTION REFERENCE
────────────────────────────────────────────────────────────────────────────

    Part 2 is a dictionary of BASIC statements and functions. Each entry
    includes information on the statement's action or effect and its syntax.
    The statement's arguments, options, and typical usage are explained
    further under "Remarks."

    The "See Also" sections refer you to related statements. Differences from
    BASICA are included where appropriate. Finally, a sample program (or a
    reference to one) is included for each QuickBASIC statement or function so
    you can see exactly how it works.


────────────────────────────────────────────────────────────────────────────
ABS Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the absolute value of a numeric expression

■ Syntax

    ABS(numeric-expression)

■ Remarks

    The absolute value function returns the unsigned magnitude of its
    argument. For example, ABS(-1) and ABS(1) are both 1.

■ Example

    The following example finds an approximate value for a cube root. It uses
    ABS to find the difference between two guesses to see if the current guess
    is accurate enough.

    DEFDBL A-Z

    FUNCTION CubeRoot(Value,Precision) STATIC
    '  Make the first two guesses.
        X1=0.0# : X2=Value

    '  Go until the difference between two guesses is
    '  less than the required precision.

        DO UNTIL ABS(X1-X2) < Precision
        X=(X1+X2)/2.0#
        ' Adjust the guesses.
        IF X*X*X-Value < 0.0# THEN
            X1=X
        ELSE
            X2=X
        END IF
        LOOP
        CubeRoot=X
    END FUNCTION

    INPUT "Enter a value: ",X
    PRINT "The cube root is ";CubeRoot(X,.0000001#)

■ Output

    Enter a value: 27
    The cube root is  2.999999972060323


────────────────────────────────────────────────────────────────────────────
ASC Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a numeric value that is the ASCII code for the first character in
    a string expression

■ Syntax

    ASC(stringexpression)

■ Remarks

    If stringexpression is null, ASC produces a run-time error message
    (Illegal function call).

■ See Also

    CHR$; Appendix A, "Keyboard Scan Codes and ASCII Character Codes"

■ Example

    The following example uses ASC to calculate a hash value──an index value
    for a table or file──from a string:

    CONST HASHTABSIZE=101

    FUNCTION HashValue(S$,Size) STATIC

        TmpVal=0
        FOR I=1 TO LEN(S$)
        ' Convert the string to a number by summing the values
        ' of individual letters.
        TmpVal=TmpVal+ASC(MID$(S$,I,1))
        NEXT I
        ' Divide the sum by the size of the table.
        HashValue=TmpVal MOD Size

    END FUNCTION

    INPUT "Enter a name: ",Nm$
    PRINT "The hash value is ";HashValue(Nm$,HASHTABSIZE)

■ Output

    Enter a name: Bafflegab
    The hash value is  66


────────────────────────────────────────────────────────────────────────────
ATN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the arctangent of a numeric expression (the angle whose tangent is
    equal to the numeric expression)

■ Syntax

    ATN(numeric-expression)

■ Remarks

    The numeric-expression can be of any numeric type.

    The result is given in radians and is in the range -π/2 to π/2 radians,
    where π=3.141593. ATN is evaluated by default in single precision unless
    numeric-expression is a double-precision value. Then ATN is evaluated in
    double precision.

■ Example

    The following example first finds the tangent of π/4 and then takes the
    arctangent of the value. The result is π/4.

    CONST PI=3.141592653

    PRINT ATN(TAN(PI/4.0)), PI/4.0

■ Output

    .78539816325  .78539816325


────────────────────────────────────────────────────────────────────────────
BEEP Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sounds the speaker

■ Syntax

    BEEP

■ Remarks

    The BEEP statement makes a sound through the loudspeaker. This statement
    makes the same sound as the following statement:

    PRINT CHR$(7)

■ Example

    The following example uses BEEP to indicate an error in the response:

    DO
        INPUT "Continue (Y or N)";Response$
        R$=UCASE$ (MID$ (Response$,1,1))
        IF R$="Y" OR R$="N" THEN EXIT DO
        BEEP
    LOOP


────────────────────────────────────────────────────────────────────────────
BLOAD Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Loads a memory-image file, created by BSAVE, into memory from an input
    file or device

■ Syntax

    BLOAD filespec «,offset»

■ Remarks

    The BLOAD statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filespec                 A string expression containing the file
                            specification. Input devices other than the
                            keyboard (KYBD:) are supported.

    offset                   The offset of the address where loading is to
                            start.
    ──────────────────────────────────────────────────────────────────────────

    The BLOAD statement allows a program or data saved as a memory-image file
    to be loaded anywhere in memory. A memory-image file is a byte-for-byte
    copy of what was originally in memory.

────────────────────────────────────────────────────────────────────────────
NOTE
    Programs written in earlier versions of BASIC no longer work if they use
    VARPTR to access numeric arrays.
────────────────────────────────────────────────────────────────────────────

    The starting address for loading is determined by the specified offset and
    the most recent DEF SEG statement. If offset is omitted, the segment
    address and offset contained in the file (the address used in the BSAVE
    statement) are used. Thus, the file is loaded at the address used when
    saving the file.

    If you supply an offset, the segment address used is the segment set by
    the most recently executed DEF SEG statement. If there has been no DEF SEG
    statement, the BASIC data segment (DS) is used as the default.

    If the offset is a single-precision or double-precision number it is
    coerced to an integer. If the offset is a negative number in the range -1
    to -32,768, it is treated as an unsigned 2-byte offset.

────────────────────────────────────────────────────────────────────────────
NOTE
    Because BLOAD does not perform an address-range check, it is possible to
    load a file anywhere in memory. You must be careful not to write over
    BASIC or the operating system. Since different screen modes use memory
    differently, do not load graphic images in a screen mode other than the
    one used when they were created. Also, because BASIC program code and data
    items are not always stored in the same locations as they were in BASICA,
    do not use BLOAD with files created by BASICA programs.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    BLOAD does not support the cassette device.

■ See Also

    BSAVE, DEF SEG, VARPTR, VARSEG

■ Example

    This example uses BLOAD to retrieve a drawing saved in a disk file using
    BSAVE. See the example for BSAVE to see how the drawing was saved.

    DIM Cube(1 TO 675)

    ' Set the screen mode--the mode should be the same as the
    ' mode used to create the original drawing.
    SCREEN 1

    ' Load the drawing into the array Cube.
    DEF SEG=VARSEG(Cube(1)) ' Get the array's segment.
    BLOAD "magcube.grh",VARPTR(Cube(1))
    DEF SEG   ' Restore the default segment.
    ' Put the drawing on the screen.
    PUT (80,10),Cube


────────────────────────────────────────────────────────────────────────────
BSAVE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Transfers the contents of an area of memory to an output file or device

■ Syntax

    BSAVE filespec,offset,length

■ Remarks

    The BSAVE statement has the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filespec                 A string expression containing the file or device
                            name. Output devices other than the console
                            (SCRN: and CONS:) are supported.

    offset                   The offset of the starting address of the area in
                            memory to be saved.

    length                   The number of bytes to save. This is a numeric
                            expression returning an unsigned integer in the
                            range 0-65,535.
    ──────────────────────────────────────────────────────────────────────────

    The BSAVE statement allows data or programs to be saved as memory-image
    files on disk. A memory-image file is a byte-for-byte copy of what is in
    memory along with control information used by BLOAD to load the file.

────────────────────────────────────────────────────────────────────────────
NOTE
    Programs written in earlier versions of BASIC no longer work if they use
    VARPTR to access numeric arrays.
────────────────────────────────────────────────────────────────────────────

    The starting address of the area saved is determined by the offset and the
    most recent DEF SEG statement.

    If no DEF SEG statement is executed before the BSAVE statement, the
    program uses the default BASIC data segment (DS). Otherwise, BSAVE begins
    saving at the address specified by the offset and by the segment set in
    the most recent DEF SEG statement.

    If the offset is a single- or double-precision floating-point value, it is
    coerced to an integer. If the offset is a negative number in the range -1
    to -32,768, it is treated as an unsigned 2- byte offset.

────────────────────────────────────────────────────────────────────────────
NOTE
    Because different screen modes use memory differently, do not load graphic
    images in a screen mode other than the one used when the images were
    created.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    BSAVE does not support the cassette device.

■ See Also

    BLOAD

■ Example

    This example draws a graphic and then saves it as a memory-image file. See
    the example for the BLOAD statement to see how the file would be
    retrieved.

    ' This program draws on the screen, stores the drawing in an
    ' array, and then saves the drawing in a disk file using BSAVE.
    '
    DIM Cube(1 TO 675)

    SCREEN 1
    ' Draw a white box.
    LINE (140,25)-(140+100,125),3,b
    ' Draw the outline of a magenta cube inside the box.
    DRAW "C2 BM140,50 M+50,-25 M+50,25 M-50,25"
    DRAW "M-50,-25 M+0,50 M+50,25 M+50,-25 M+0,-50 BM190,75 M+0,50"
    ' Save the drawing in the array Cube.
    GET (140,25)-(240,125),Cube
    ' Store the drawing in a disk file. Note: 2700 is the number
    ' of bytes in Cube (4 bytes per array element * 675).
    DEF SEG=VARSEG(Cube(1)) ' Set segment to array's segment.
    BSAVE "magcube.grh",VARPTR(Cube(1)),2700
    DEF SEG   ' Restore BASIC segment.


────────────────────────────────────────────────────────────────────────────
CALL Statement (BASIC Procedures)
────────────────────────────────────────────────────────────────────────────

■ Action

    Transfers control to a BASIC SUB

■ Syntax 1

    CALL name«( argumentlist )»

■ Syntax 2

    name« argumentlist »

■ Remarks

    The CALL statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    name                     The name, limited to 40 characters, of the BASIC
                            SUB being called. The name must appear in a SUB
                            statement if the SUB is in the same module.

    argumentlist             The variables or constants passed to the
                            subprogram. Arguments in the list are separated
                            by commas. Arguments passed by reference can be
                            changed by the subprogram.
    ──────────────────────────────────────────────────────────────────────────

    If the argumentlist includes an array argument, the array is specified by
    the array name followed by empty parentheses:

    DIM IntArray(1 TO 20)
    .
    .
    .
    CALL ShellSort(IntArray())

    When you use the CALL statement, the CALL keyword is optional. However, if
    you omit the CALL keyword, you must declare the procedure in a DECLARE
    statement. Notice also that when you omit the CALL keyword, you also omit
    the parentheses around the argument list. See Chapter 2 , "SUB and
    FUNCTION Procedures," in Programming in BASIC for more information.

    Arguments are passed by reference: the subprogram is given the address of
    the argument. This allows subprograms to change the argument values. BASIC
    can also pass arguments by value. The following statement calls a
    subprogram and passes a single argument by value:

    CALL SolvePuzzle((StartValue))

    Because StartValue is in parentheses, BASIC evaluates it as an expression.
    The result is stored in a temporary location, and the address of the
    temporary location is passed to the SUB. Any change made by the subprogram
    SolvePuzzle is made only to the temporary location and not to the
    variable.

■ See Also

    CALL, CALLS (Non BASIC); CALL ABSOLUTE; DECLARE (BASIC)

■ Example

    The program below copies a series of files into a new file, the last file
    in the series entered from the command line. In the program, the BASIC
    subprogram PRINTOUT is called after first splitting the command line into
    separate file names and storing them in the array FILE$. The PRINTOUT
    subprogram copies the contents of the files to the final file in the list
    and to the standard output device (default is to your screen).

    DEFINT A-Z
    CONST MAXFILES=5, ARRAYDIM=MAXFILES+1
    DIM File$(1 TO ARRAYDIM)
    ' Separate command line into arguments.
    CALL Comline (Numargs,File$(),ARRAYDIM)
    ' Test for too many or too few files.
    IF Numargs < 3 OR Numargs >MAXFILES THEN
    ' Too many or too few files.
        PRINT "Use more than 3 and fewer than";MAXFILES;"files"
    ELSE
    ' Send all files to Printout.
        CALL Printout(File$(),Numargs)
    END IF
    END


    ' See the example under COMMAND$ for the definition of
    ' Comline. Comline would appear here.

    SUB Printout(F$(1),N) STATIC
        ' Open target file.
        OPEN F$(N) FOR OUTPUT AS #3
        ' Loop executes once for each file.
        ' Copy the first N-1 files onto the Nth file.
        FOR File = 1 TO N-1
        OPEN F$(File) FOR INPUT AS #1
        DO WHILE NOT EOF(1)
            'Read file.
            LINE INPUT #1, Temp$
            'Write data to target file.
            PRINT #3, Temp$
            PRINT Temp$                 'Write file to standard
        LOOP                           'output.
        CLOSE #1
        NEXT
        CLOSE
    END SUB


────────────────────────────────────────────────────────────────────────────
CALL, CALLS Statement (Non-BASIC Procedures)
────────────────────────────────────────────────────────────────────────────

■ Action

    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)»

■ Remarks

    The following list describes the parts of the CALL statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    name                     The name of the procedure being called. A name is
                            limited to 40 characters.

    call-argumentlist        The variables or constants passed to the
                            procedure. The syntax of a call-argumentlist is
                            described below.

    calls-argumentlist       A list containing the variables and constants
                            that CALLS passes to the procedure. Entries are
                            separated by commas. Note that these arguments
                            are passed by reference as far addresses, using
                            the segment and offset of the variable. You
                            cannot use BYVAL or SEG in a calls-argumentlist.
    ──────────────────────────────────────────────────────────────────────────

    A call-argumentlist has the following syntax:

    ««{BYVAL|SEG}»argument»«,«{BYVAL|SEG}»argument»...

    If argument is an array, parentheses are required:

    ««{BYVAL|SEG}»argument«()»»«,«{BYVAL|SEG}»argument»...

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    BYVAL                    Indicates the argument is passed by value, rather
                            than by near reference (the default)

    SEG                      Passes the argument as a segmented (far) address

    argument                 A BASIC variable, array, or constant passed to
                            the procedure
    ──────────────────────────────────────────────────────────────────────────

    CALLS is the same as using CALL with a SEG before each argument: every
    argument in a CALLS statement is passed as a segmented address.

────────────────────────────────────────────────────────────────────────────
NOTE
    The syntax described above does not correctly invoke a BASIC
    procedure──only procedures in other languages. See also the separate entry
    for CALL (BASIC).
────────────────────────────────────────────────────────────────────────────

    If the argument list of either statement includes an array argument, the
    array is specified by the array name and a pair of parentheses:

    DIM IntArray(20) AS INTEGER
    .
    .
    .
    CALL ShellSort(IntArray() AS INTEGER)

    When you use the CALL statement, the CALL keyword is optional. However,
    when you omit CALL, you must declare the procedure in a DECLARE statement.
    Notice also that when you omit CALL, you also omit the parentheses around
    the argument list. See Chapter 2, "SUB and FUNCTION Procedures," in
    Programming in BASIC for more information about invoking procedures
    without the CALL keyword.

    The result of the BYVAL keyword differs from BASIC's pass by value:

    CALL Difference (BYVAL A,(B))

    For the first argument, only the value of A is passed to Difference. In
    contrast, (B) is evaluated, a temporary location is created for the value,
    and the address of the temporary location is passed to Difference. You can
    use BASIC's pass by value for an argument, but you must write the
    procedure in the other language so the procedure accepts an address.

────────────────────────────────────────────────────────────────────────────
NOTE
    If name refers to an assembly-language procedure, it must be a PUBLIC name
    (symbol). PUBLIC names beginning with "$" and "_" may conflict with names
    used by the BASIC run-time system. Duplicate names cause a linker error
    message (symbol already defined) to be generated.
────────────────────────────────────────────────────────────────────────────

    Be careful using the SEG keyword to pass arrays because BASIC may move
    variables in memory before the called routine begins execution. Anything
    in an argument list that causes memory movement may create problems. You
    can safely pass variables using SEG if the CALL statement's argument list
    contains only simple variables, arithmetic expressions, or arrays indexed
    without the use of intrinsic or user-defined functions.

    See Section 2.3.3, "Variable Storage Allocation," for a list of things
    that cause variable movement and for information about when to use near or
    far addresses for variables.

■ Differences From Basica

    Assembly-language programs invoked from BASICA that have string arguments
    must be changed because the string descriptor is now four bytes long. The
    four bytes are the low byte and high byte of the length followed by the
    low byte and high byte of the address.

    To locate the routine being called, the BASICA CALLS statement uses the
    segment address defined by the most recently executed DEF SEG statement.
    There is no need to use DEF SEG with the CALLS statement because all
    arguments are passed as far (segmented) addresses.

■ See Also

    CALL (BASIC); DECLARE (BASIC); DECLARE (Non-BASIC)

■ Example

    See the example for VARPTR.


────────────────────────────────────────────────────────────────────────────
CALL ABSOLUTE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Transfers control to a machine-language procedure

■ Syntax

    CALL ABSOLUTE («argumentlist,»integervariable)

■ Remarks

    The CALL ABSOLUTE statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    argumentlist             Optional arguments passed to a machine-language
                            procedure.

    integervariable          An integer variable containing a value that is
                            the offset from the beginning of the current code
                            segment, set by DEF SEG, to the starting location
                            of the procedure. The integervariable argument is
                            not passed to the procedure. Your program may
                            need to execute a DEF SEG statement before
                            executing CALL ABSOLUTE to set the code segment
                            for the called routine.

                            Using a noninteger value for integervariable
                            produces unpredictable results.
    ──────────────────────────────────────────────────────────────────────────

    Arguments in argumentlist are passed to the machine-language program as
    offsets (near pointers) from the current data segment. Although arguments
    are passed as offsets, the machine-language program is invoked with a far
    call.

────────────────────────────────────────────────────────────────────────────
NOTE
    The CALL ABSOLUTE statement is provided to maintain compatibility with
    earlier versions of BASIC. Mixed-language programming using the CALL
    statement extensions and the new DECLARE statement provide a simpler way
    to use assembly language with BASIC.

    In order to use CALL ABSOLUTE you must start QuickBASIC with the correct
    Quick library, link your program with QB.LIB, or use the QB.QLB Quick
    library. See the disk-contents list for the locations of these files.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    Assembly-language programs that are invoked from BASICA and that have
    string arguments must be changed because string descriptors are now four
    bytes long. The four bytes are the low byte and high byte of the string
    length followed by the low byte and high byte of the string address.

■ See Also

    CALL, CALLS (Non-BASIC)

■ Example

    The following example uses CALL ABSOLUTE to execute a machine-language
    program stored in an array:

    CONST nASMBYTES=14
    ' This program prints a message indicating whether or not
    ' a math coprocessor is installed.
    ' It uses a machine-language program stored in an array
    ' to get the information from the operating system.
    'AsmBytes is a label; nASMBYTES is a symbolic constant.
    DEFINT A-Z
    DIM AsmProg(1 TO (nASMBYTES/2))

    ' The machine-language program stored as data to read into
    ' the array.
    DATA &H55              :'PUSH BP       Save base pointer.
    DATA &H8B, &HEC        :'MOV  BP,SP    Get our own.
    DATA &HCD, &H11        :'INT  11H      Make the ROM-BIOS call.
    DATA &H8B, &H5E, &H06  :'MOV  BX,[BP+6] Get argument address.
    DATA &H89, &H07        :'MOV  [BX],AX  Save list in argument.
    DATA &H5D              :'POP  BP       Restore base pointer.
    DATA &HCA, &H02, &H00  :'RET  2        Pop argument off stack
                            '              and make far return.
    ' Get the starting offset of the array.
    P=VARPTR(AsmProg(1))
    ' Poke the machine-language program into the array.
    DEF SEG=VARSEG(AsmProg(1)) ' Change the segment.
    Restore AsmBytes
    FOR I=0 TO nASMBYTES-1
        READ J
        POKE(P+I),J
    NEXT I

    ' Execute the program. The program expects a single integer
    ' argument.
    CALL ABSOLUTE(X%,VARPTR(AsmProg(1)))
    DEF SEG   ' Restore the segment.
    ' X% now contains bit-encoded equipment list returned by DOS.
    ' Mask off all but the coprocessor bit (bit 2).
    CoProcessor=X% AND &H2
    ' Print the appropriate message.
    IF CoProcessor=2 THEN
    PRINT "Math coprocessor present."
    ELSE
    PRINT "No math coprocessor."
    END IF
    END


────────────────────────────────────────────────────────────────────────────
CALL INT86OLD Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Allows programs to perform DOS system calls

■ Syntax

    CALL INT86OLD (int_no,in_array(),out_array())
    CALL INT86XOLD (int_no,in_array(),out_array())

■ Remarks

    The CALL INTERRUPT statement provides an easier way to make DOS system
    calls. See the entry for CALL INTERRUPT for more information. The
    following list describes the arguments to INT86OLD and INT86XOLD:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    int_no                   The DOS interrupt to perform. It is an integer
                            between 0 and 255. See your DOS documentation for
                            the interrupt numbers.

    in_array()               An integer array specifying the register values
                            when the interrupt is performed.

                            INT86OLD uses an eight-element array, while
                            INT86XOLD uses a ten-element array. Table R.1
                            lists the array elements and the corresponding
                            registers.

    out_array()              Contains the postinterrupt register values. It
                            has the same structure as in_array.
    ──────────────────────────────────────────────────────────────────────────

    If an error occurs, int_no = -1 and values in out_array are unchanged.
    Errors are caused by int_no not being in the range 0-255.

    Table R.1   INT86OLD and INT86XOLD Register Values

    Array Element            Register
    ──────────────────────────────────────────────────────────────────────────
    in_array(x)              AX
    in_array(x+1)            BX
    in_array(x+2)            CX
    in_array(x+3)            DX
    in_array(x+4)            BP
    in_array(x+5)            SI
    in_array(x+6)            DI
    in_array(x+7)            FLAGS
    in_array(x+8)☼           DS
    in_array(x+9)☼           ES
    ──────────────────────────────────────────────────────────────────────────

    The INT86OLD and INT86XOLD routines alter all registers except BP and DS.

    INT86OLD and INT86XOLD provide compatibility with older programs using
    INT86 and INT86X. Like the INT86 and INT86X routines, INT86OLD and
    INT86XOLD are distributed in a Quick library (QB.QLB) and in a
    conventional library (QB.LIB) on the distribution disks. The disks also
    contain a header file (QB.BI) for use with the procedures. See the
    disk-contents list for specific information.

    Note that INT86OLD and INT86XOLD do not require the use of VARPTR. Also,
    the register values are stored in the arrays beginning with the first
    array element.

■ Example

    The following example uses INT86OLD to open a file and place some text in
    it:

    ' Include header file for INT86OLD, etc.
    ' ¢INCLUDE:'QB.BI'

    DIM INARY%(7),OUTARY%(7)          'Define input and output
                                    'arrays for INT86.
    '
    ' Define register-array indices to
    ' make program easier to understand.
    CONST AX=0, BX=1, CX=2, DX=3, BP=4, SI=5, DI=6, FL=7
    '
    INARY%(AX) = &H3C00               'DOS function to create a file.
    INARY%(CX) = 0                    'DOS attribute for created file.
    INARY%(DX) = SADD("FOO.TXT"+CHR$(0))
                                    'Pointer to file-name string
                                    'with zero byte termination.

    CALL INT86OLD(&H21,INARY%(),OUTARY%())
                                    'Perform the creation.
    '
    INARY%(BX) = OUTARY%(AX)   'Move created file handle for write.
    INARY%(AX) = &H4000
            'DOS function to write to file.
    TEXT$ = "hello, world"+CHR$(13)+CHR$(10)
                                    'Define text to write to file.

    INARY%(CX) = LEN(TEXT$)       'Get length of text string.
    INARY%(DX) = SADD(TEXT$)      'Get address of text string.
    CALL INT86OLD(&H21,INARY%(),OUTARY%())
                                    'Perform the write.
    '
    INARY%(AX) = &H3E00
            'DOS function to close a file.
    CALL INT86OLD(&H21,INARY%(),OUTARY%())
                                    'Perform the close.


────────────────────────────────────────────────────────────────────────────
CALL INTERRUPT Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Allows BASIC programs to perform DOS system calls

■ Syntax

    CALL INTERRUPT (interruptnum,inregs,outregs)
    CALL INTERRUPTX (interruptnum,inregs,outregs)

■ Remarks

    The following list describes the arguments for the CALL INTERRUPT and CALL
    INTERRUPTX statements:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    interruptnum             The DOS interrupt number. It is an integer
                            between 0 and 255. See your DOS documentation for
                            information about interrupts.

    inregs                   The inregs variable contains the register values
                            used when the interrupt is performed. It is
                            declared as type RegType. The user-defined type
                            RegType is described below.

    outregs                  The outregs variable contains the register values
                            after the interrupt is performed. It is declared
                            as type RegType. The user-defined type RegType is
                            described below.
    ──────────────────────────────────────────────────────────────────────────

    The CALL INTERRUPT and CALL INTERRUPTX statements replace the INT86 and
    INT86X routines used in earlier versions of BASIC. They provide a more
    convenient way for BASIC programs to use DOS interrupts and services.

    The register values before and after the interrupt are passed in variables
    declared as type RegType. The following statement defines the RegType
    user-defined type:

    TYPE RegType
        AX AS INTEGER
        BX AS INTEGER
        CX AS INTEGER
        DX AS INTEGER
        BP AS INTEGER
        SI AS INTEGER

    DI AS INTEGER
        FLAGS AS INTEGER
        DS AS INTEGER
        ES AS INTEGER
    END TYPE

    Each element of the type corresponds to a CPU register.

    INTERRUPTX uses the values in the DS and ES registers. To use the current
    values of these registers, set the record elements to -1.

    CALL INTERRUPT and CALL INTERRUPTX are available in a Quick Library
    (QB.QLB) and in a conventional library (QB.LIB) on your distribution
    disks. There is also a header file (QB.BI) on the disks with the necessary
    declarations for using these procedures. See the disk-contents list for
    specific information.

    To use CALL INTERRUPT or CALL INTERRUPTX when running a program within the
    QuickBASIC environment, the Quick library QB.QLB must be loaded with
    QuickBASIC.

■ Example

    The following program uses CALL INTERRUPT to change a file's attribute
    list so the file does not appear when you use the DIR command from DOS:

    DECLARE SUB TestError (AXReg%, flags%)
    ' ¢INCLUDE: 'QB.BI'

    DEFINT A-Z
    DIM InRegs AS RegType, OutRegs AS RegType

    ' Get the file name and action to perform.
    CLS
    PRINT "Hidden File Program": PRINT
    INPUT "Enter file name: ", FileName$
    DO
        INPUT "Hide or unhide (H or U): ", Action$
        Action$ = UCASE$(Action$)
    LOOP WHILE Action$ <> "H" AND Action$ <> "U"

    ' Tack a null (zero) byte onto the end of the string for the
    ' DOS function.
    FileName$ = FileName$ + CHR$(0)

    ' Get the current file attribute.
    ' Current attribute comes back in OutRegs.AX.
    InRegs.ax = &H4300
    InRegs.dx = SADD(FileName$)
    CALL INTERRUPT(&H21, InRegs, OutRegs)
    CALL TestError(OutRegs.ax, OutRegs.flags)

    ' Change the hidden attribute bit in the old attribute value.
    IF Action$ = "U" THEN
        InRegs.cx = OutRegs.cx AND &HFD
    ELSE
        InRegs.cx = OutRegs.cx OR &H2
    END IF

    ' Set AX to indicate the Change Attribute DOS function.
    InRegs.ax = &H4301
    CALL INTERRUPT(&H21, InRegs, OutRegs)
    CALL TestError(OutRegs.ax, OutRegs.flags)

    END
    ' If carry flag set, print error message and end program.
    SUB TestError (AXReg, flags) STATIC
        IF (&H1 AND flags) <> 0 THEN
        ' Get the error number out of AX.
        SELECT CASE AXReg AND &HF
            CASE 2
                PRINT "File not found."
            CASE 3
                PRINT "Path not found."
            CASE 5
                PRINT "Access denied."
            CASE ELSE
                PRINT "Unrecognized error."
        END SELECT
        END
        END IF
    END SUB


────────────────────────────────────────────────────────────────────────────
CDBL Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts a numeric expression to a double-precision number

■ Syntax

    CDBL(numeric-expression)

■ Remarks

    The numeric-expression may be any numeric expression. This function has
    the same effect as assigning the numeric expression to a double-precision
    variable.

    Note that the results of CDBL are no more accurate than the original
    expression. The added digits of precision are not significant unless the
    expression is calculated with double-precision accuracy.

■ Example

    The following example demonstrates how the precision of the numeric
    expression affects the result of using CDBL:

    X = 7/9
    X# = 7/9
    PRINT X
    'Both X# and CDBL(X) will be accurate to only 7 decimal
    'places, because 7/9 is evaluated in single precision.
    PRINT X#
    PRINT CDBL(X)
    'Accurate to 15 decimal places.
    PRINT 7#/9#

■ Output

    .7777778
    .7777777910232544
    .7777777910232544
    .7777777777777778


────────────────────────────────────────────────────────────────────────────
CHAIN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Transfers control from the current program to another program

■ Syntax

    CHAIN filespec

■ Remarks

    The filespec is a string expression that identifies the program to which
    control is passed. The filespec may include a path specification. Programs
    running within the QuickBASIC environment assume a .BAS extension (if no
    extension is given) and cannot chain to executable files (files with a
    .COM or .EXE extension). Programs running outside the QuickBASIC
    environment assume an .EXE extension and cannot chain to QuickBASIC source
    files (files with a .BAS extension).

    You can pass variables between programs using the COMMON statement to set
    up a blank COMMON block. See the entry for COMMON.

    If you are compiling a program outside the QuickBASIC environment, note
    that the BCOM45.LIB library does not support COMMON. There are two ways to
    use COMMON with chained programs outside the environment:

    ■ Use the default (BRUN45.EXE) by compiling the programs using the option
    in the Make EXE dialog box called EXE Requiring BRUN45.EXE.

    ■ Use BRUN45.LIB by compiling from the command line without the /O option.

    The behavior of CHAIN and RUN is almost identical. The principal
    differences are that RUN closes all open files and does not support COMMON
    data blocks.

────────────────────────────────────────────────────────────────────────────
NOTE
    When programs use BRUN45.LIB, files are left open during chaining unless
    they are explicitly closed with a CLOSE statement.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    BASICA assumes the extension .BAS. QuickBASIC assumes an extension of
    either .BAS or .EXE, depending on whether the program is run within the
    environment or compiled and run outside the environment. If you omit the
    file extension, CHAIN works the same in both QuickBASIC and BASICA.

    BASIC does not support the ALL, MERGE, or DELETE options available in
    BASICA, nor does it allow you to specify a line number.

    Without the line-number option, execution always starts at the beginning
    of the chained-to program. Thus, a chained-to program that chains back to
    a carelessly written chaining program can cause an endless loop.

■ See Also

    CALL (BASIC), COMMON, RUN

■ Example

    See example for the COMMON statement.


────────────────────────────────────────────────────────────────────────────
CHDIR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Changes the current default directory for the specified drive

■ Syntax

    CHDIR pathspec

■ Remarks

    The pathspec is a string expression identifying the directory that is to
    become the default directory. The pathspec must have fewer than 64
    characters. It has the following syntax:

    «drive:»«\»directory«\directory»...

    The argument drive: is an optional drive specification. If you omit drive,
    CHDIR changes the default directory on the current drive.

    CHDIR differs from the CHDIR command in DOS in two ways:

    1. The BASIC statement cannot be shortened to CD.

    2. There is no form of the CHDIR statement that returns the current
        directory.

────────────────────────────────────────────────────────────────────────────
    The CHDIR statement changes the default directory but not the default
    drive. For example, if the default drive is C, then the following CHDIR
    statement changes the default directory on drive D, but the default drive
    is still C:
────────────────────────────────────────────────────────────────────────────

    CHDIR "D:\TMP"

■ See Also

    MKDIR, RMDIR

■ Examples

    ' Makes \HOME\SALES the current directory on the default
    ' drive.
    CHDIR "\HOME\SALES"

    'Changes the current directory to USERS on drive B; it does
    'not, however, change the default drive to B.
    CHDIR "B:USERS"


────────────────────────────────────────────────────────────────────────────
CHR$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a one-character string whose ASCII code is the argument

■ Syntax

    CHR$(code)

■ Remarks

    CHR$ is commonly used to send a special character to the screen or
    printer. For example, you can send a form feed (CHR$(12)) to clear the
    screen and return the cursor to the home position.

    CHR$ can also be used to include a double quote (") in a string:

    Msg$=CHR$(34)+"Quoted string"+CHR$(34)

    This line adds a double-quote character to the beginning and the end of
    the string.

■ See Also

    ASC; Appendix A, "Keyboard Scan Codes and ASCII Character Codes"

■ Example

    The following example uses CHR$ to display graphics characters in the
    extended character set:

    DEFINT A-Z
    ' Display two double-sided boxes.
    CALL DBox(5,22,18,40)
    CALL DBox(1,4,4,50)
    END

    ' Subroutine to display boxes on the screen.
    '
    ' Parameters
    '  Urow%, Ucol% : Row and column of upper-left corner.
    '  Lrow%, Lcol% : Row and column of lower-right corner.
    ' Use constants for the extended character set graphic
    ' characters.
    CONST ULEFTC=201, URIGHTC=187, VERTICAL=186, HORIZONTAL=205
    CONST LLEFTC=200, LRIGHTC=188

    SUB DBox (Urow%, Ucol%, Lrow%, Lcol%) STATIC

        ' Draw top of box, starting with the upper left corner.
        LOCATE Urow%, Ucol% : PRINT CHR$(ULEFTC);
        LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORIZONTAL));
        LOCATE ,Lcol% : PRINT CHR$(URIGHTC);

        ' Draw the body of the box.
        FOR I=Urow%+1 TO Lrow%-1
        LOCATE I,Ucol% : PRINT CHR$(VERTICAL);
        LOCATE  ,Lcol% : PRINT CHR$(VERTICAL);
        NEXT I

        ' Draw the bottom of the box.
        LOCATE Lrow%, Ucol% : PRINT CHR$(LLEFTC);
        LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORIZONTAL));
        LOCATE ,Lcol% : PRINT CHR$(LRIGHTC);

    END SUB


────────────────────────────────────────────────────────────────────────────
CINT Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts a numeric expression to an integer by rounding the expression's
    fractional part

■ Syntax

    CINT(numeric-expression)

■ Remarks

    If numeric-expression is not in the range -32,768 to 32,767, the function
    produces a run-time error message that reads Overflow.

    CINT differs from the FIX and INT functions, which truncate, rather than
    round, the fractional part. See the example for the INT function for an
    illustration of the differences among these functions.

■ See Also

    CDBL, CSNG, FIX, INT

■ Example

    The following example converts an angle in radians to an angle in degrees
    and minutes:

    'Set up constants for converting radians to degrees.
    CONST PI=3.141593, RADTODEG=180./PI
    INPUT "Angle in radians = ",Angle  'Get the angle in radians.
    Angle = Angle * RADTODEG    'Convert radian input to degrees.
    Min = Angle - INT(Angle)    'Get the fractional part.
    'Convert fraction to value between 0 and 60.
    Min = CINT(Min * 60)
    Angle = INT(Angle)          'Get whole number part.
    IF Min = 60 THEN       '60 minutes = 1 degree.
        Angle = Angle + 1
        Min = 0
    END IF
    PRINT "Angle equals" Angle "degrees" Min "minutes"

■ Output

    Angle in radians = 1.5708
    Angle equals 90 degrees 0 minutes


────────────────────────────────────────────────────────────────────────────
CIRCLE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Draws an ellipse or circle with a specified center and radius

■ Syntax

    CIRCLE «STEP» (x,y),radius«,«color»«,«start»«,«end»«,aspect»»»»

■ Remarks

    The following list describes the parts of the CIRCLE statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    STEP                     The STEP option specifies that x and y are
                            offsets relative to the current graphics cursor
                            position.

    x,y                      The x- and y-coordinates for the center of the
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    x,y                      The x- and y-coordinates for the center of the
                            circle or ellipse.

    radius                   The radius of the circle or ellipse in the
                            current coordinate system.

    color                    The attribute of the desired color. See the
                            entries for the COLOR and SCREEN statements for
                            more information. The default color is the
                            foreground color.

    start, end               The start and end angles, in radians, for the arc
                            to draw. The start and end arguments are used to
                            draw partial circles or ellipses. The arguments
                            may range in value from -2π radians to 2π
                            radians, where π = appx. 3.141593. The default
                            value for start is 0 radians. The default value
                            for end is 2π radians.

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────

                            If start or end is negative, then CIRCLE draws a
                            radius to that point on the arc and treats the
                            angle it were positive.

                            The start angle can be less than the end angle.
                            If you specify end but not start, the arc is
                            drawn from 2π to end; if you specify start but
                            not end, the statement draws an arc from start to
                            zero.

    aspect                   The aspect ratio, or the ratio of the y-radius to
                            the x-radius. The default value for aspect is the
                            value required to draw a round circle in the
                            screen mode. This value is calculated as follows:

                            4 * (ypixels/xpixels)/3

                            where xpixels by ypixels is the screen
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            where xpixels by ypixels is the screen
                            resolution. For example, in screen mode 1, where
                            the resolution is 320 x 200, the default for
                            aspect is 4 * (200/320)/3, or 5/6.

                            If the aspect ratio is less than one, radius is
                            the x-radius. If aspect is greater than one,
                            radius is equal to the y-radius.
    ──────────────────────────────────────────────────────────────────────────


    To draw a radius to angle 0 (a horizontal line segment to the right), do
    not give the angle as -0; use a very small nonzero value instead as shown:

    ' Draws a pie-shaped one-quarter wedge of a circle:
    SCREEN 2
    CIRCLE (200,100),60,,-.0001,-1.57

    You may omit an argument in the middle of the statement, but you must
    include the argument's commas. In the following statement, the color
    argument has been omitted:

    CIRCLE STEP (150,200),94,,0.0,6.28

    If you omit the last argument, you do not include the commas.

    The last point that CIRCLE references, after drawing, is the center of the
    ellipse or circle. You may use coordinates that are outside the screen or
    viewport.

    You may show coordinates as absolutes, or you may use the STEP option to
    show the position of the center point in relation to the previous point of
    reference. For example, if the previous point of reference is (10,10),
    then the following statement causes a circle to be drawn with radius 75
    and center offset 10 from the current x coordinate and 5 from the current
    y coordinate. The circle's center is (20,15).

    CIRCLE STEP (10,5), 75

■ Example

    The following program first draws a circle with the upper left quarter
    missing. It then uses relative coordinates to position a second circle
    within the missing quarter circle. Finally, it uses a different aspect
    ratio to draw a small ellipse inside the small circle.

    CONST PI=3.141593
    SCREEN 2

    ' Draw a circle with the upper-left quarter missing.
    ' Use negative numbers so radii are drawn.
    CIRCLE (320,100), 200,, -PI, -PI/2

    ' Use relative coordinates to draw a circle within the missing
    ' quarter.
    CIRCLE STEP (-100,-42),100

    ' Draw a small ellipse inside the circle.
    CIRCLE STEP(0,0), 100,,,, 5/25

    ' Display the drawing until a key is pressed.
    LOCATE 25,1 : PRINT "Press any key to end.";
    DO
    LOOP WHILE INKEY$=""


────────────────────────────────────────────────────────────────────────────
CLEAR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Reinitializes all program variables, closes files, and sets the stack size

■ Syntax

    CLEAR «,,stack»

■ Remarks

    The CLEAR statement performs the following actions:

    ■ Closes all files and releases the file buffers

    ■ Clears all COMMON variables

    ■ Sets numeric variables and arrays to zero

    ■ Sets all string variables to null

    ■ Reinitializes the stack and, optionally, changes its size

    The stack parameter sets aside stack space for your program. QuickBASIC
    takes the amount of stack space it requires, adds the number of bytes
    specified by stack, and sets the stack size to the result.

────────────────────────────────────────────────────────────────────────────
NOTE
    Two commas are used before stack to keep QuickBASIC compatible with
    BASICA. BASICA included an additional argument that set the size of the
    data segment. Because QuickBASIC automatically manages the data segment,
    the first parameter is no longer required .
────────────────────────────────────────────────────────────────────────────

    If your program has deeply nested subroutines or procedures, or if you use
    recursive procedures, you may want to use a CLEAR statement to increase
    the stack size. You may also want to increase the stack size if your
    procedures have a large number of arguments.

    Clearing the stack destroys the return addresses placed on the stack
    during the execution of a GOSUB. This makes it impossible to execute a
    RETURN statement correctly and produces a RETURN without GOSUB run-time
    error message. Using a CLEAR statement in a SUB or FUNCTION produces a
    run-time error message that reads Illegal function call.

■ Differences From Basica

    BASICA programs using CLEAR may require modification. In BASICA programs,
    any DEF FN functions or data types declared with DEFtype statements are
    lost after a CLEAR statement. In compiled programs, this information is
    not lost because these declarations are fixed at compile time.

■ See Also

    FRE, SETMEMGT

■ Example

    The following statement clears all program variables and sets aside 2,000
    bytes on the stack for the program:

    CLEAR ,,2000


────────────────────────────────────────────────────────────────────────────
CLNG Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts a numeric expression to a long (4-byte) integer by rounding the
    fractional part of the expression

■ Syntax

    CLNG(numeric-expression)

■ Remarks

    If numeric-expression is not in the range -2,147,483,648 to 2,147,483,647,
    the function produces an error message that reads Overflow.

■ Example

    The following example shows how CLNG rounds before converting the number:

    A=32767.45
    B=32767.55
    PRINT CLNG(A); CLNG(B)

■ Output

    32767  32768


────────────────────────────────────────────────────────────────────────────
CLOSE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Concludes I/O to a file or device

■ Syntax

    CLOSE ««#» filenumber «,«#» filenumber»...»

■ Remarks

    The CLOSE statement complements the OPEN statement.

    The filenumber is the number under which the file was opened. A CLOSE
    statement with no arguments closes all open files and devices.

    The association of a file with a file number ends when a CLOSE statement
    is executed. You may then reopen the file using the same or a different
    file number. Once you close a file, you may use that file's number for any
    unopened file.

    A CLOSE for a file or device that was opened for sequential output writes
    the final buffer of output to that file or device.

    CLOSE releases all buffer space associated with the closed file or files.

    The CLEAR, END, RESET, RUN, and SYSTEM statements automatically close all
    files.

■ Example

    See the example for CALL (BASIC).


────────────────────────────────────────────────────────────────────────────
CLS Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Clears the screen

■ Syntax

    CLS «{0 | 1 | 2}»

■ Remarks

    There are several ways to use the CLS statement, as described in the
    following list:

    Statement                Description
    ──────────────────────────────────────────────────────────────────────────
    CLS 0                    Clears the screen of all text and graphics.

    CLS 1                    Clears only the graphics viewport if a VIEW
                            statement has been executed. Otherwise, CLS 1
                            clears the entire screen.

    CLS 2                    Clears only the text viewport, leaving the bottom
                            screen line (line 25, 30, 43, or 60 depending on
                            the screen mode) unchanged.

    CLS                      Clears either the graphics viewport or the text
                            viewport. If the graphics viewport is active,
                            then CLS with no argument clears only the
                            viewport. If the graphics viewport is inactive,
                            then CLS clears the text viewport and refreshes
                            the function key display line (the bottom screen
                            line).
    ──────────────────────────────────────────────────────────────────────────

    The CLS statement also returns the cursor to the home position in the top
    left corner of the screen.

■ See Also

    VIEW, VIEW PRINT, WINDOW

■ Example

    The following program draws random circles in a graphics viewport and
    prints in a text viewport. The graphics viewport is cleared after 30
    circles have been drawn. The program clears the text viewport after
    printing to it 45 times.

    RANDOMIZE TIMER
    SCREEN 1
    ' Set up a graphics viewport with a border.
    VIEW (5,5)-(100,80),3,1
    ' Set up a text viewport.
    VIEW PRINT 12 TO 24
    ' Print a message on the screen outside the text viewport.
    LOCATE 25,1 : PRINT "Press any key to stop."
    Count=0

    DO
        ' Draw a circle with a random radius.
        CIRCLE (50,40),INT((35-4)*RND+5),(Count MOD 4)
        ' Clear the graphics viewport every 30 times.
        IF (Count MOD 30)=0 THEN CLS 1
        PRINT "Hello. ";
        ' Clear the text viewport every 45 times.
        IF (Count MOD 45)=0 THEN CLS 2
        Count=Count+1
    LOOP UNTIL INKEY$<>""


────────────────────────────────────────────────────────────────────────────
COLOR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    With the COLOR statement, you can set the foreground and background colors
    for the display. In screen mode 0 a border color can also be selected. In
    screen mode 1 no foreground color can be selected, but one of two
    four-color palettes can be selected for use with graphics statements. In
    screen modes 12-13 only the foreground color can be set.

    The values of foreground in screen modes 7-10, 12, and 13 are attribute
    numbers (not color numbers) and display the color assigned to that
    attribute. See the PALETTE statement for a description of attributes.

    The COLOR statement does not determine the range of available colors. The
    combination of adapter, display, and the mode set by the SCREEN statement
    determine the color range. See the SCREEN statement for more information.

    The different syntaxes and their effects in different screen modes are
    described below:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
    0                        Modifies the current default text foreground and
                            background colors and the screen border. The
                            foreground color must be an integer expression in
                            the range 0-31. It determines the "foreground"
                            color in text mode──the default color of text.
                            Sixteen colors can be selected with the integers
                            0-15. You can select a blinking version of a
                            color by adding 16 to the color number. For
                            example, a blinking color 7 is equal to 7 + 16,
                            or 23.

                            The background color is an integer expression in
                            the range 0-7 and is the color of the background
                            for each text character. Blinking background
                            colors are not supported.

                            The border color──the color used to draw the
                            screen border──is an integer expression in the
                            range 0-15. The IBM Enhanced Graphics Adapter
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
                            range 0-15. The IBM Enhanced Graphics Adapter
                            (EGA), the IBM Video Graphics Array adapter
                            (VGA), and the IBM Multicolor Graphics Array
                            adapter (MCGA) do not support the border
                            argument.

    1                        In mode 1, the COLOR statement has a unique
                            syntax that includes a palette argument that is
                            an odd or even integer expression in the range 0
                            to 255. This argument determines which of two
                            sets of colors to use when displaying particular
                            color numbers.

                            The default colors for the palette parameter are
                            equivalent to the following PALETTE statements on
                            a system equipped with an EGA:

                            COLOR ,0     'Same as the next three
                                        'PALETTE statements.
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
                                        'PALETTE statements.
                            PALETTE 1,2  'Attribute 1 = color 2 (green)
                            PALETTE 2,4  'Attribute 2 = color 4 (red)
                            PALETTE 3,6  'Attribute 3 = color 6 (yellow)

                            COLOR ,1     'Same as the next three
                                        'PALETTE statements.
                            PALETTE 1,3  'Attribute 1 = color 3 (cyan)
                            PALETTE 2,5  'Attribute 2 = color 5 (magenta)
                            PALETTE 3,7  'Attribute 3 = color 7 (white)

                            Note that in screen mode 1, a COLOR statement
                            overrides previous PALETTE statements.

    2                        An Illegal function call message results if COLOR
                            is used in this mode.

    7-10                     In these modes, no border color can be specified.
                            The graphics background is given by the
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
                            The graphics background is given by the
                            background color number, which must be in the
                            range of valid color numbers for the screen mode.
                            The foreground color argument is the default
                            line-drawing color. In screen modes 7 to 10
                            foreground is an attribute number, while
                            background is a color number. See the SCREEN
                            statement for more details.

    11                       Use the PALETTE statement to set color in screen
                            mode 11.

    12, 13                   No background color can be specified in these
                            modes. The foreground argument is the attribute
                            used for the foreground graphics color. The
                            attribute must be in the correct range for the
                            screen mode. See the SCREEN statement for more
                            information.
    ──────────────────────────────────────────────────────────────────────────
    Screen Mode              Description
    ──────────────────────────────────────────────────────────────────────────
    ──────────────────────────────────────────────────────────────────────────


    Arguments that are outside the valid ranges produce error messages that
    read Illegal function call.

    The foreground can be the same color as the background, making displayed
    characters invisible. The default background is black, or color number 0
    for all display hardware configurations and all screen modes.

    In screen modes 12 and 13 you can set the background color by assigning a
    color to attribute 0 with a PALETTE statement. For example, to make the
    background color 8224 (a light violet), you would use the following
    PALETTE statement:

    PALETTE 0,8224

    In screen mode 11 you can set both the foreground and background color by
    assigning a color to attribute 0 with a PALETTE statement.

    With an EGA, VGA, or MCGA installed, the PALETTE statement gives you
    flexibility in assigning different display colors to the actual
    color-number ranges for the foreground, background, and border colors
    discussed above. See the PALETTE statement reference pages for more
    details.

■ See Also

    PAINT, PALETTE, SCREEN

■ Examples

    The following series of examples show COLOR statements and their effects
    in the various screen modes:

    SCREEN 0
    'foreground=1, background=2, border=3
    COLOR  1, 2, 3

    SCREEN 1
    'background=1, even palette number
    COLOR  1,0
    'background=2, odd palette number
    COLOR  2,1


────────────────────────────────────────────────────────────────────────────
COM Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables, disables, or inhibits event trapping of communications activity
    on a specified port

■ Syntax

    COM(n) ON
    COM(n) OFF
    COM(n) STOP

■ Remarks

    The parameter n is the number of the communications port; n can be either
    1 or 2.

    The COM ON statement enables communications event trapping. If a character
    arrives at a communications port after a COM ON statement, then the
    subroutine specified in the ON COM statement is executed.

    COM OFF disables communications event trapping. No communications trapping
    takes place until another COM ON statement is executed. Events occurring
    while trapping is off are ignored.

    COM STOP inhibits communications event trapping so no trapping takes place
    until a COM ON statement is executed. Events occurring while trapping is
    inhibited are remembered and processed when the next COM ON statement is
    executed.

    See Chapter 6, "Error and Event Trapping," in Programming in BASIC for an
    outline of event trapping.

■ See Also

    ON event

■ Example

    See the event-trapping examples in Chapter 6, "Error and Event Trapping,"
    in Programming in BASIC for an illustration of how to do event trapping.


────────────────────────────────────────────────────────────────────────────
COMMAND$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the command line used to invoke the program

■ Syntax

    COMMAND$

■ Remarks

    The COMMAND$ function returns the complete command line entered after your
    BASIC program name, including optional parameters. COMMAND$ removes all
    leading blanks from the command line and converts all letters to uppercase
    (capital letters). The COMMAND$ function can be used in stand-alone
    executable files or, if you are executing from the QuickBASIC environment,
    by using the /CMD command line option or by selecting Modify COMMAND$ on
    the Run menu.

■ Example

    The Comline subprogram in the following example breaks the command line
    into separate arguments and stores them in an array. Each argument is
    separated from adjoining arguments by one or more blanks or tabs on the
    command line.

    ' Default variable type is integer in this module.
    DEFINT A-Z

    ' Declare the Comline subprogram, as well as the number and
    ' type of its parameters.
    DECLARE SUB Comline(N, A$(),Max)

    DIM A$(1 TO 15)
    ' Get what was typed on the command line.
    CALL Comline(N,A$(),10)
    ' Print out each part of the command line.
    PRINT "Number of arguments = ";N
    PRINT "Arguments are: "
    FOR I=1 TO N : PRINT A$(I) : NEXT I

    ' Subroutine to get command line and split into arguments.
    ' Parameters:  NumArgs : Number of command line args found.
    '              Args$() : Array in which to return arguments.
    '              MaxArgs : Maximum number of arguments array
    '                        can return.

    SUB Comline(NumArgs,Args$(),MaxArgs) STATIC
    CONST TRUE=-1, FALSE=0

        NumArgs=0 : In=FALSE
    ' Get the command line using the COMMAND$ function.
        Cl$=COMMAND$
        L=LEN(Cl$)

    ' Go through the command line a character at a time.
        FOR I=1 TO L
        C$=MID$(Cl$,I,1)
        'Test for character being a blank or a tab.
        IF (C$<>" " AND C$<>CHR$(9)) THEN
        ' Neither blank nor tab.
        ' Test to see if you're already
        ' inside an argument.
            IF NOT In THEN
        ' You've found the start of a new argument.
        ' Test for too many arguments.
                IF NumArgs=MaxArgs THEN EXIT FOR
                NumArgs=NumArgs+1
                In=TRUE
            END IF
        ' Add the character to the current argument.
            Args$(NumArgs)=Args$(NumArgs)+C$
        ELSE
        ' Found a blank or a tab.
        ' Set "Not in an argument" flag to FALSE.
            In=FALSE
        END IF
        NEXT I

    END SUB

    The following is a sample command line and output for a stand-alone
    executable file (assumes program name is arg.exe):

    arg one  two   three    four     five      six

■ Output

    Number of arguments =  6
    Arguments are:
    ONE
    TWO
    THREE
    FOUR
    FIVE
    SIX


────────────────────────────────────────────────────────────────────────────
COMMON Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines global variables for sharing between modules or for chaining to
    another program

■ Syntax

    COMMON «SHARED»  «/blockname/» variablelist

■ Remarks

    The following list describes the parts of the COMMON statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    SHARED                   An optional attribute indicating that the
                            variables are to be shared with all SUB or
                            FUNCTION procedures in the module. SHARED can
                            eliminate the need for a SHARED statement inside
                            SUB or FUNCTION procedures.

    blockname                A valid BASIC identifier (up to 40 characters)
                            used to identify a group of variables. Use a
                            blockname to share only specific groups of
                            variables. When a blockname is used, the COMMON
                            block is a named COMMON block. When blockname is
                            omitted, the block is a blank COMMON block. Items
                            in a named COMMON block are not preserved across
                            a chain to a new program. See "Using Named
                            COMMON" and "Using COMMON with Chain," below.

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────

    variablelist             A list of variables to be shared between modules
                            or chained-to programs. The same variable may not
                            appear in more than one COMMON statement in a
                            module.
    ──────────────────────────────────────────────────────────────────────────


    A variablelist has the following syntax:

    variable«( )»«AS type»«, variable«( )»«AS type»»...

    The following list describes the parts of a variablelist:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    variable                 Any valid BASIC variable name.

    AS type                  Declares variable to be of type type. The type
                            may be INTEGER, LONG, SINGLE, DOUBLE, STRING, or
                            a user-defined type.
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    Older versions of BASIC required the number of dimensions to appear after
    the name of a dynamic array in a COMMON statement. The number of
    dimensions is no longer required, although QuickBASIC accepts the older
    syntax to maintain compatibility with earlier versions.
────────────────────────────────────────────────────────────────────────────

    A COMMON statement establishes storage for variables in a special area
    that allows them to be shared between modules or with other programs
    invoked with a CHAIN statement.

    Because COMMON statements establish global variables for an entire
    program, they must appear before any executable statements. All statements
    are executable, except the following:

    ■ COMMON

    ■ CONST

    ■ DATA

    ■ DECLARE

    ■ DEFtype

    ■ DIM (for static arrays)

    ■ OPTION BASE

    ■ REM

    ■ SHARED

    ■ STATIC

    ■ TYPE...END TYPE

    ■ All metacommands

    Variables in COMMON blocks are matched by position and type, not by name.
    Thus, variable order is significant in COMMON statements. In the following
    fragment, it is the order of the variables in the COMMON statements that
    links the variables, not the names:

    ' Main program.
    COMMON A, D, E
    A = 5 : D = 8 : E = 10
    .
    .
    .

    ' Common statement in another module.
    COMMON A, E, D           'A = 5, E = 8, D = 10
    .
    .
    .

    Both static and dynamic arrays are placed in COMMON by using the array
    name followed by parentheses. A static array must be dimensioned with
    integer-constant subscripts in a DIM statement preceding the COMMON
    statement. A dynamic array must be dimensioned in a later DIM or REDIM
    statement. The elements of a dynamic array are not allocated in the COMMON
    block. Only an array descriptor is placed in common. (See Chapter 2,
    "Data Types," in this manual and Appendix F, "Metacommands," in
    Programming in BASIC for more information about static and dynamic
    arrays.)

    The size of a common area can be different from that in another module or
    chained program if a blank COMMON block has been used. When a BASIC
    program shares COMMON blocks with a routine in the user library, the
    calling program may not redefine the COMMON block to a larger size.

    Errors caused by mismatched COMMON statements are subtle and difficult to
    find. An easy way to avoid this problem is to place COMMON declarations in
    a single "include" file and use the ¢INCLUDE metacommand in each program.
    See Appendix F, "Metacommands," in Programming in BASIC for a discussion
    of ¢INCLUDE.

    The following program fragment shows how to use the ¢INCLUDE metacommand
    to share a file containing COMMON statements among programs:

    'This file is menu.bas.
    '¢INCLUDE:'COMDEF.BI'
    .
    .
    .
    CHAIN "PROG1"
    END


    'This file is prog1.bas.
    '¢INCLUDE:'COMDEF.BI'
    .
    .
    .
    END


    'This file is comdef.bi.
    DIM A(100),B$(200)
    COMMON I,J,K,A()
    COMMON A$,B$(),X,Y,Z
    'End comdef.bi.

    The next three sections discuss using named COMMON blocks, using the
    SHARED keyword, and using COMMON when chaining programs.

    USING NAMED COMMON

    A named COMMON block provides a convenient way to group variables so that
    different modules have access only to the common variables that they need.

    The following program, which calculates the volume and density of a
    rectangular prism, uses named COMMON blocks to share different sets of
    data with two subprograms. The subprogram VOLUME needs to share only the
    variables representing the lengths of the sides (in COMMON block SIDES).
    The subprogram DENSITY also needs variables representing the weight (in
    COMMON block WEIGHT).

    'Main program.
    DIM S(3)
    COMMON /Sides/ S()
    COMMON /Weight/ C

    C=52
    S(1)=3:S(2)=3:S(3)=6
    CALL Volume
    CALL Density
    END

    'Subprogram VOLUME in a separate module.
    DIM S(3)
    COMMON SHARED /Sides/ S()

    SUB Volume STATIC
        Vol=S(1)*S(2)*S(3)
        PRINT "The volume is "; Vol
    END SUB


    'Subprogram DENSITY in a separate module.
    DIM S(3)
    COMMON SHARED /Sides/ S()
    COMMON SHARED /Weight/ W

    SUB Density STATIC
        Vol=S(1)*S(2)*S(3)
        Dens=W/Vol
        PRINT "The density is "; Dens
    END SUB

────────────────────────────────────────────────────────────────────────────
NOTE
    Named COMMON blocks are not preserved across chained programs. Use blank
    COMMON blocks to pass variables to a chained program.
────────────────────────────────────────────────────────────────────────────

    USING COMMON WITH CHAIN

    The COMMON statement provides the only way to pass the values of variables
    directly to a chained program. To pass variables, both programs must
    contain COMMON statements. Remember that variable order and type are
    significant, not variable names. The order and type of variables must be
    the same for all COMMON statements communicating between chaining
    programs.

    Although the order and type of variables is critical for making sure the
    right values are passed, the COMMON blocks do not have to be the same
    size. If the COMMON block in the chained-to program is smaller than the
    COMMON block in the chaining program, the extra COMMON variables in the
    chaining program are ignored. If the size of the COMMON block in the
    chained-to program is larger, then additional COMMON numeric variables are
    initialized to zero. Additional string variables are initialized to null
    strings.

    Static arrays passed in COMMON by the chaining program must be declared as
    static in the chained-to program. Similarly, dynamic arrays placed in
    common by the chaining program must be dynamic in the chained-to program.

────────────────────────────────────────────────────────────────────────────
NOTE
    To use COMMON with CHAIN when you are compiling outside the BASIC
    environment, you must use the BRUN45.EXE module. This module is used when
    you compile from the command line without the /O option or when you use
    the option from the Make EXE dialog box called EXE Requiring BRUN45.EXE.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CALL (BASIC), CHAIN, FUNCTION, SUB

■ Examples

    The following example uses a COMMON statement to pass variables between
    two chained programs. The first program reads in a series of numeric
    values, stores the values in an array, and then chains to the other
    program. The second program finds and prints the average of the values.

    DIM Values(1 TO 50)
    COMMON Values(), NumValues

    PRINT "Enter values one per line. Enter END to quit."
    NumValues=0
    DO
        INPUT "-> ",N$
        IF I>=50 OR UCASE$(N$)="END" THEN EXIT DO
        NumValues=NumValues+1
        Values(NumValues)=VAL(N$)
    LOOP

    CHAIN "average"

    The program named average appears as follows (notice that average is an
    entirely separate program):

    DIM X(1 TO 50)
    COMMON X(), N

    IF N>0 THEN
        Sum=0
        FOR I=1 TO N
        Sum=Sum+X(I)
        NEXT I
        PRINT "The average of the values is";Sum/N
    END IF


────────────────────────────────────────────────────────────────────────────
CONST Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Declares symbolic constants for use in place of numeric or string values

■ Syntax

    CONST constantname = expression «,constantname = expression»...

■ Remarks

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    constantname             A name following the same rules as a BASIC
                            variable name. You may add to the name a
                            type-declaration character (%, &, !, #, or $) to
                            indicate its type, but this character is not part
                            of the name.

    expression               An expression consisting of literals (such as
                            1.0), other constants, or any of the arithmetic
                            and logical operators except exponentiation (^).
                            You may also use a single literal string such as
                            "Error on input". You cannot use string
                            concatenation, variables, user-defined functions,
                            or intrinsic functions like SIN or CHR$ in
                            expressions assigned to constants.
    ──────────────────────────────────────────────────────────────────────────

    If you use a type-declaration character in the name, you may omit the
    character when the name is used, as shown in the following example:

    CONST MAXDIM% = 250
    .
    .
    .
    DIM AccountNames$(MAXDIM)

    If you omit the type-declaration character, the constant is given a type
    based on the expression in the CONST statement. Strings always yield a
    string constant. With numeric expressions, the expression is evaluated and
    the constant is given the simplest type that can represent the constant.
    For example, if the expression gives a result that can be represented as
    an integer, the constant is given an integer type.

────────────────────────────────────────────────────────────────────────────
NOTE
    Names of constants are not affected by DEFtype statements such as DEFINT.
    A constant's type is determined either by an explicit type-declaration
    character or by the type of the expression.
────────────────────────────────────────────────────────────────────────────

    Constants must be defined before they are referenced. The following
    example produces an error because the constant ONE is not defined before
    it is used to define TWO (constants are defined from left to right):

    CONST TWO = ONE + ONE, ONE = 1

    Constants declared in a SUB or FUNCTION are local to the SUB or FUNCTION.
    A constant declared outside a procedure is defined throughout the module.
    You can use constants anywhere that you would use an expression.

    A common programming practice is to use a statement like the following
    (recall that any nonzero value represents "true"):

    TRUE=-1

    Constants offer several advantages over using variables for constant
    values:

    ■ Constants need to be defined only once for an entire module.

    ■ Constants cannot be inadvertently changed.

    ■ In stand-alone programs, using constants produces more efficient code
    than using variables.

    ■ Constants make programs easier to modify.

■ Examples

    The following program uses the CONST statement to declare symbolic
    constants for the ASCII values of nonprinting characters such as tab and
    line feed:

    ' This program counts words, lines, and characters.
    ' A word is any sequence of nonblank characters.
    DEFINT a-z

    CONST BLANK = 32, ENDFILE = 26, CR = 13, LF = 10
    CONST TABC = 9, YES = -1, NO = 0

    ' Get the file name from the command line.
    FileName$=COMMAND$
    IF FileName$="" THEN
        INPUT "Enter input file name: ",FileName$
        IF FileName$="" THEN END
    END IF

    OPEN FileName$ FOR INPUT AS #1

    Words=0
    Lines=0
    Characters=0

    ' Set a flag to indicate you're not looking at a
    ' word, then get the first character from the file.
    InaWord=NO
    DO UNTIL EOF(1)
        C=ASC(INPUT$(1,#1))
        Characters=Characters+1
        IF C=BLANK or C=CR or C=LF or C=TABC THEN

    ' If the character is a blank, carriage return,
    ' line feed, or tab, you're not in a word.
        IF C=CR THEN Lines=Lines+1
        InaWord=NO
        ELSEIF InaWord=NO THEN

    ' The character is a printing character,
    ' so this is the start of a word.
    ' Count the word and set the flag.
        InaWord=YES
        Words=Words+1
        END IF

    LOOP
    PRINT Characters, Words, Lines
    END

    Constants also make programs easier to modify. The following program
    fragment declares a single constant to dimension a series of arrays. To
    increase or decrease the size of the arrays, it is necessary to change
    only the value in the CONST statement.

    CONST MAXCUSTOMERS = 250
    .
    .
    .
    DIM  AccountNumber$(MAXCUSTOMERS), Balance(MAXCUSTOMERS)
    DIM  Contact$(MAXCUSTOMERS), PastDueAmount(MAXCUSTOMERS)
    .
    .
    .

────────────────────────────────────────────────────────────────────────────
NOTE
    Using a variable here, instead of a symbolic constant, makes the arrays
    dynamic arrays. Using a symbolic constant, as in the previous example,
    declares these arrays as static arrays. See Chapter 2, "Data Types," in
    this manual and Appendix F, "Metacommands," in Programming in BASIC for
    more information about static and dynamic arrays.
────────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────
COS Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the cosine of an angle given in radians

■ Syntax

    COS(numeric-expression)

■ Remarks

    The expression, numeric-expression, can be any numeric type.

    By default, the cosine is calculated in single precision. If
    numeric-expression is a double-precision value, the cosine is calculated
    in double precision.

    You can convert an angle measurement from degrees to radians by
    multiplying the degrees by π/180, where π = 3.141593.

■ See Also

    ATN, SIN, TAN

■ Example

    The following program plots the graph of the polar equation r = nq for
    values of n from 0.1-1.1. This program uses the conversion factors x =
    cos(q) and y = sin(q) to change polar coordinates to Cartesian x,y
    coordinates. The figure plotted is sometimes known as the Spiral of
    Archimedes.

    CONST PI = 3.141593
    'Gray background.
    SCREEN 1 : COLOR 7
    'Define window large enough for biggest spiral.
    WINDOW (-4,-6)-(8,2)
    'Draw line from origin to the right.
    LINE (0,0)-(2.2*PI,0),1
    'Draw ten spirals.
    FOR N = 1.1 TO .1 STEP -.1
        'Plot starting point.
        PSET (0,0)
        FOR Angle = 0 TO 2*PI STEP .04
        'Polar equation for spiral.
        R = N * Angle
        'Convert polar coordinates to Cartesian coordinates.
        X = R * COS(Angle)
        Y = R * SIN(Angle)
        'Draw line from previous point to new point.
        LINE -(X,Y),1
        NEXT
    NEXT


────────────────────────────────────────────────────────────────────────────
CSNG Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts a numeric expression to a single-precision value

■ Syntax

    CSNG(numeric-expression)

■ Remarks

    The CSNG function has the same effect as assigning the numeric-expression
    to a single-precision variable.

    CSNG rounds the value, if necessary, before converting it.

■ See Also

    CDBL, CINT

■ Example

    The following example shows how CSNG rounds before converting the value:

    A#=975.3421115#
    B#=975.3421555#
    PRINT A#; CSNG(A#); B#; CSNG(B#)

■ Output

    975.3421115  975.3421  975.3421555  975.3422


────────────────────────────────────────────────────────────────────────────
CSRLIN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current line (row) position of the cursor

■ Syntax

    CSRLIN

■ Remarks

    To return the current column position, use the POS function.

■ See Also

    LOCATE, POS

■ Example

    The following program uses a subprogram that prints a message on the
    screen without disturbing the current cursor position:

    ' Move cursor to center of screen, then print message.
    ' Cursor returned to center of screen.
        LOCATE 12,40
        CALL MsgNoMove("A message not to be missed.",9,35)
        INPUT "Enter anything to end: ",A$

    ' Print a message without disturbing current
    ' cursor position.
    SUB MsgNoMove (Msg$,Row%,Col%) STATIC

        ' Save the current line.
        CurRow%=CSRLIN
        ' Save the current column.
        CurCol%=POS(0)
        ' Print the message at the given position.
        LOCATE Row%,Col% : PRINT Msg$;
        ' Move the cursor back to original position.
        LOCATE CurRow%, CurCol%

    END SUB


────────────────────────────────────────────────────────────────────────────
CVSMBF, CVDMBF Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts strings containing Microsoft Binary format numbers to IEEE-format
    numbers

■ Syntax

    CVSMBF (4-byte-string)
    CVDMBF (8-byte-string)

■ Remarks

    The CVSMBF and CVDMBF functions allow you to read old random-access files
    containing real numbers stored as strings in Microsoft Binary format.
    These functions convert the string read from the old file to an
    IEEE-format number:

    Function                 Description
    ──────────────────────────────────────────────────────────────────────────
    CVSMBF                   Converts 4-byte-string containing a Microsoft
                            Binary format number to a single-precision
                            IEEE-format number.

    CVDMBF                   Converts 8-byte-string containing a Microsoft
                            Binary format number to a double-precision
                            IEEE-format number.
    ──────────────────────────────────────────────────────────────────────────

    The example below shows you how to read data from an old file by using
    CVSMBF and user-defined types for records. See Appendix B, "Differences
    from Previous Versions of QuickBASIC," in Programming in BASIC for more
    information about converting old data files.

■ See Also

    FIELD; MKSMBF$, MKDMBF$

■ Example

    The following program reads records from a random-access file containing
    Microsoft Binary format real numbers stored as strings. Each record
    contains a student's name and a test score.

    ' Define a user type for the data records.
    TYPE StudentRec
        NameField AS STRING*20
        Score AS STRING*4
    END TYPE

    ' Define a variable of the user type.
    DIM Rec AS StudentRec

    ' Open the file.
    OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(Rec)

    Max=LOF(1)/LEN(Rec)

    ' Read and print all of the records.
    FOR I=1 TO Max
        ' Read a record into the user-type variable Rec.
        GET #1,I,Rec
        ' Convert the score from a string containing a Microsoft
        ' Binary format number to an IEEE-format number.
        ScoreOut=CVSMBF(Rec.Score)
        ' Display the name and score.
        PRINT Rec.NameField,ScoreOut
    NEXT I

    CLOSE #1


────────────────────────────────────────────────────────────────────────────
CVI, CVS, CVL, CVD Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts strings containing numeric values to numbers

■ Syntax

    CVI(2-byte-string)
    CVS(4-byte-string)
    CVL(4-byte-string)
    CVD(8-byte-string)

■ Remarks

    CVI, CVS, CVL, and CVD are used with a FIELD statement to read real
    numbers from a random-access file. The functions take strings defined in
    the FIELD statement and convert them to a value of the corresponding
    numeric type. The functions are the inverse of MKI$, MKS$, MKL$, and MKD$:

    Function                 Description
    ──────────────────────────────────────────────────────────────────────────
    CVI                      Converts 2-byte-string created with MKI$ back to
                            an integer.

    CVS                      Converts 4-byte-string created with MKS$ back to
                            a single-precision number.

    CVL                      Converts 4-byte-string created with MKL$ back to
                            a long integer.

    CVD                      Converts 8-byte-string created with MKD$ back to
                            a double-precision number.
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    The new BASIC record variables provide a more efficient and convenient way
    of reading and writing random-access files. See Chapter 3, "File and
    Device I/O," in Programming in BASIC for a complete example.
────────────────────────────────────────────────────────────────────────────

■ See Also

    FIELD; LSET; MKD$, MKI$, MKL$, MKS$

■ Example

    The following program illustrates the use of MKS$ and CVS:

    OPEN "ACCOUNT.INF" FOR RANDOM AS #2 LEN = 29
    FIELD #2, 25 AS Name$, 4 AS Check$

    Format$ = "$$#####.##"
    DO
        PRINT
        DO
        INPUT "Enter account # to update: ",Rec%
        GET #2, Rec%   'Get the record
        PRINT "This is the account for "; Name$
        INPUT "Is this the account you wanted"; R$
        LOOP WHILE UCASE$(MID$(R$,1,1)) <> "Y"

        'Convert string to single-precision number.
        Checkamt!  = CVS(Check$)
        PRINT
        PRINT "The opening balance for this account is";
        PRINT USING Format$; Checkamt!
        PRINT "Enter the checks and cash withdrawals for this"
        PRINT "account below. Enter 0 when finished."

        DO
        INPUT Checkout! : Checkamt! = Checkamt! - Checkout!
        LOOP UNTIL Checkout! = 0

        PRINT
        PRINT "Enter the deposits for this account below."
        PRINT "Enter 0 when finished."

        DO
        INPUT Checkin! : Checkamt! = Checkamt! + Checkin!
        LOOP UNTIL Checkin! = 0

        PRINT
        PRINT "The closing balance for this account is";
        PRINT USING Format$; Checkamt!
        'Convert single-precision number to string.
        LSET Check$ = MKS$(Checkamt!)
        PUT #2, Rec%   'Store the record.
        INPUT "Update another"; R$

    LOOP UNTIL UCASE$(MID$(R$,1,1)) <> "Y"
    CLOSE #2
    END


────────────────────────────────────────────────────────────────────────────
DATA Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Stores the numeric and string constants used by a program's READ
    statements

■ Syntax

    DATA constant1 «,constant2»...

■ Remarks

    The constant1, constant2, and so on in a DATA statement can be any valid
    numeric or string constant.

    Names of symbolic constants (defined in a CONST statement) appearing in
    DATA statements are interpreted as strings, rather than names of
    constants. For example, in the following program fragment the second data
    item is a string, "PI", and not the value 3.141593:

    CONST PI=3.141593
    .
    .
    .
    DATA 2.20, PI,45,7
    .
    .
    .

    A DATA statement may contain as many constants as will fit on a line. The
    constants are separated by commas. You may use any number of DATA
    statements.

────────────────────────────────────────────────────────────────────────────
NOTE
    String constants in DATA statements require double quotes only if they
    contain commas, colons, or significant leading or trailing spaces.
────────────────────────────────────────────────────────────────────────────

    Null data items (indicated by a missing value) can appear in a data list:

    DATA 1,2,,4,5

    When a null item is read into a numeric variable, the variable has the
    value 0. When a null item is read into a string variable, the variable has
    the null string value ("").

    When working in the QuickBASIC environment, DATA statements can only be
    entered in the module-level code. QuickBASIC moves all DATA statements not
    in the module-level code to the module-level code when it reads a source
    file. READ statements using the DATA statements can appear anywhere in the
    program.

    DATA statements are used in the order in which they appear in the source
    file. You may think of the items in several DATA statements as one
    continuous list of items, regardless of how many items are in a statement
    or where the statement appears in the program.

    You may reread DATA statements by using the RESTORE statement.

■ See Also

    READ RESTORE

■ Examples

    The following example displays the current date by converting the date
    returned by the DATE$ function:

    ' Get the date.
    C$ = DATE$
    ' Use VAL to split the month off the string returned by
    ' DATE$.
    FOR I% = 1 TO VAL(C$)
        READ Month$
    NEXT
    DATA January, February, March, April, May, June, July
    DATA August, September, October, November, December

    ' Get the day.
    Day$ = MID$(C$,4,2)
    IF LEFT$(Day$,1) = "0" THEN Day$ = RIGHT$(Day$,1)
    ' Get the year.
    Year$ = RIGHT$(C$,4)

    PRINT "Today is " Month$ " " Day$ ", " Year$

■ Output

    Today is September 21, 1988

    The following example shows how null data items are handled:

    DATA abc,,def
    DATA 1,,2
    READ A$, B$, C$         'B$ = ""
    PRINT A$, B$, C$
    PRINT
    READ A, B, C            'B = 0
    PRINT A, B, C

    OUTPUT

    abc                    def
    1            0         2


────────────────────────────────────────────────────────────────────────────
DATE$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string containing the current date

■ Syntax

    DATE$

■ Remarks

    The DATE$ function returns a ten-character string in the form mm-dd-yyyy,
    where mm is the month (01-12), dd is the day (01-31), and yyyy is the year
    (1980-2099).

■ See Also

    DATE$ Statement

■ Example

    Note that the DATE$ function in the following example prints a zero in
    front of the month:

    PRINT DATE$

■ Output

    09-21-88


────────────────────────────────────────────────────────────────────────────
DATE$ Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the current date

■ Syntax

    DATE$ = stringexpression

■ Remarks

    The DATE$ statement is the complement of the DATE$ function.

    The stringexpression must have one of the following forms, where mm
    (01-12) and dd (01-31) are the month and day, and yy and yyyy (1980-2099)
    are the year:

    mm-dd-yy
    mm-dd-yyyy
    mm/dd/yy
    mm/dd/yyyy

■ Example

    The following program sets the current date from an input numeric date:

    PRINT "Enter the date below (default year is 1989)."
    INPUT "    Month:   ",Month$
    INPUT "    Date:    ",Day$
    INPUT "    Year:    ",Year$
    IF Year$ = "" THEN Year$ = "89"
    DATE$ = Month$ + "/" + Day$ + "/" + Year$


────────────────────────────────────────────────────────────────────────────
DECLARE Statement (BASIC Procedures)
────────────────────────────────────────────────────────────────────────────

■ Action

    Declares references to BASIC procedures and invokes argument type checking

■ Syntax

    DECLARE {FUNCTION | SUB } name «(«parameterlist»)»

■ Remarks

    The DECLARE statement uses the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    name                     The procedure's name. The name is limited to 40
                            characters. FUNCTION names can end in one of the
                            type-declaration characters (%, &, !, #, or $) to
                            indicate the type of value returned.

    parameterlist            A list of parameters indicating the number and
                            type of arguments used when calling the
                            procedure. Syntax is shown below. Only the number
                            and the type of the arguments are significant.
    ──────────────────────────────────────────────────────────────────────────

    For calls within BASIC, the DECLARE statement is required only if you call
    SUB procedures without the CALL keyword, or if you invoke a FUNCTION
    defined in another module. See Chapter 2, "SUB and FUNCTION Procedures,"
    in Programming in BASIC, for more information about invoking subprograms
    without CALL.

    A DECLARE statement also causes the compiler to check the number and type
    of arguments used to invoke the procedure. QuickBASIC automatically
    generates DECLARE statements when you save your program while you are
    working in the environment. The DECLARE statement can appear only in
    module-level code (not in a SUB or FUNCTION) and affects the entire
    module.

    The parameterlist serves as a prototype for checking the number and type
    of the arguments in SUB and FUNCTION calls. It has the following syntax:

    variable«AS type» «,variable«AS type»»...

    A variable is any valid BASIC variable name. If the variable is an array,
    it may be followed by the number of dimensions in parentheses:

    DECLARE SUB DisplayText (A(2) AS STRING)
    DIM Text$(100,5)
    .
    .
    .
    CALL DisplayText(Text$())

    The number of dimensions is optional.

    The type is either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a
    user-defined type. Again, only the number and types of arguments are
    significant.

────────────────────────────────────────────────────────────────────────────
NOTE
    You cannot have fixed-length strings in DECLARE statements because only
    variable-length strings can be passed to SUB and FUNCTION procedures.
    Fixed-length strings can appear in an argument list but are converted to
    variable-length strings before being passed.
────────────────────────────────────────────────────────────────────────────

    A variable's type can also be indicated by including an explicit type
    character (%, &, !, #, or $) or by relying on the default type.

    The form of the parameter list determines whether or not argument checking
    is done, as shown in the following list:

    Declaration                          Meaning
    ──────────────────────────────────────────────────────────────────────────
    DECLARE SUB First                    You may only omit the parentheses if
                                        the SUB or FUNCTION is separately
                                        compiled. No argument checking is
                                        done.

    DECLARE SUB First ()                 First has no parameters. Arguments in
                                        a CALL to First are flagged as an
                                        error. An empty parameter list
                                        indicates that the SUB or FUNCTION
                                        has no parameters.

    DECLARE SUB First (X AS LONG)        First has one long-integer parameter.
                                        The number and type of the arguments
                                        in each CALL or invocation are
                                        checked when the parameter list
                                        appears in the DECLARE.
    ──────────────────────────────────────────────────────────────────────────

■ See Also

    CALL, CALLS (Non-BASIC); FUNCTION; SUB

■ Example

    In the following example, the DECLARE statement allows Sort to be invoked
    without the CALL keyword:

    ' Generate 20 random numbers, store them in an array, and sort.
    ' The sort subprogram is called without the CALL keyword.
    DECLARE SUB Sort(A(1) AS SINGLE, N AS INTEGER)
    DIM Array1(1 TO 20)

    ' Generate 20 random numbers.
    RANDOMIZE TIMER
    FOR I=1 TO 20
        Array1(I)=RND
    NEXT I

    ' Sort the array and call Sort without the CALL keyword.
    ' Notice the absence of parentheses around the arguments in
    ' the call to Sort.
    Sort Array1(), 20%

    ' Print the sorted array.
    FOR I=1 TO 20
        PRINT Array1(I)
    NEXT I
    END

    ' Sort subroutine.
    SUB Sort(A(1), N%) STATIC

        FOR I= 1 TO N%-1
        FOR J=I+1 TO N%
            IF A(I)>A(J) THEN SWAP A(I), A(J)
        NEXT J
        NEXT I

    END SUB


────────────────────────────────────────────────────────────────────────────
DECLARE Statement (Non-BASIC Procedures)
────────────────────────────────────────────────────────────────────────────

■ Action

    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»)»

■ Remarks

    The following list describes the parts of the DECLARE statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    FUNCTION                 Indicates that the external procedure returns a
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    FUNCTION                 Indicates that the external procedure returns a
                            value and can be used in an expression.

    SUB                      Indicates that the external procedure is invoked
                            in the same way as a BASIC SUB.

    name                     The name used in the BASIC program to invoke the
                            procedure. Names may have up to 40 characters.
                            FUNCTION names can include an explicit type
                            character (%, &, !, #, or $) indicating the type
                            of value the FUNCTION returns.

    CDECL                    Indicates that the procedure uses the C-language
                            argument order. CDECL passes the arguments from
                            right to left, rather than using the BASIC
                            convention of left to right.

                            CDECL also affects the name used in searches of
                            object files and libraries. If there is no ALIAS
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            object files and libraries. If there is no ALIAS
                            in the DECLARE, the name of the procedure (name)
                            is converted to lowercase, the type-declaration
                            character is removed, and an underscore is added
                            to the beginning. This becomes the name used when
                            searching libraries and external files. If CDECL
                            is used with an ALIAS, the aliasname is used.

    ALIAS                    Indicates that the procedure has another name in
                            the .OBJ or library file.

    aliasname                The name the procedure has in the file or
                            library.
    ──────────────────────────────────────────────────────────────────────────


    A parameterlist has the following syntax:

    «{BYVAL|SEG}» variable «AS type» «,«{BYVAL|SEG}» variable «AS type»»...

    The following list describes the parts of a parameterlist:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    BYVAL                    BYVAL indicates that the parameter is passed by
                            value, rather than by reference. Reference is the
                            default. BYVAL can be used only with INTEGER,
                            LONG, SINGLE, and DOUBLE parameters.

                            When BYVAL appears in front of a parameter, the
                            actual argument is converted to the type
                            indicated in the DECLARE statement before being
                            passed.

    SEG                      Indicates the parameter is passed as a segmented
                            address (far pointer).

    variable                 A valid BASIC variable name. Only the variable's
                            type is significant. If the variable is an array
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            type is significant. If the variable is an array
                            it may be followed by the number of dimensions in
                            parentheses (to maintain compatibility with older
                            versions of BASIC):

                            DECLARE SUB EigenValue (A(2) AS DOUBLE)

                            The number of dimensions is optional.

    AS type                  Indicates the variable's type. The type element
                            may be either INTEGER, LONG, SINGLE, DOUBLE,
                            STRING, ANY, or a user type. You can also
                            indicate the variable's type by including an
                            explicit type character (%, &, !, #, or $) in the
                            variable name or by relying on the default type.

                            When declaring external procedures written in
                            other languages, you can use the ANY keyword in
                            the AS clause. ANY overrides type checking for
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            the AS clause. ANY overrides type checking for
                            that argument. You cannot use ANY with arguments
                            passed by value.
    ──────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────
NOTE
    When neither BYVAL nor SEG is used, arguments are passed as near addresses
    (offsets).
────────────────────────────────────────────────────────────────────────────

    This form of the DECLARE statement lets you reference procedures written
    in other languages. The DECLARE statement also causes the compiler to
    check the number and type of arguments used to invoke the procedure. A
    DECLARE statement can appear only in module-level code and affects the
    entire source file. The form of the parameter list determines whether or
    not argument type checking is done:

    Declaration                          Meaning
    ──────────────────────────────────────────────────────────────────────────
    DECLARE SUB First CDECL              No argument checking is done when
                                        there is no parameter list.

    DECLARE SUB First CDECL ()           First has no parameters. Arguments in
                                        a CALL to First are flagged as an
                                        error. Empty parentheses indicate
                                        that the SUB or FUNCTION has no
                                        parameters.

    DECLARE SUB First CDECL (X AS LONG)  First takes one long integer
                                        argument. When a parameter list
                                        appears, the number and type of the
                                        arguments are checked in each
                                        invocation.
    ──────────────────────────────────────────────────────────────────────────

    A procedure that appears in a DECLARE statement can be invoked without the
    CALL keyword. See the entry for DECLARE (BASIC) for more information.

────────────────────────────────────────────────────────────────────────────
NOTE
    You cannot have fixed-length strings in DECLARE statements because only
    variable-length strings can be passed to SUB and FUNCTION procedures.
    Fixed-length strings can appear in an argument list but are converted to
    variable-length strings before being passed.
────────────────────────────────────────────────────────────────────────────

    Be careful when using the SEG keyword to pass arrays because BASIC may
    move variables in memory before the called routine begins execution.
    Anything in a CALL statement's argument list that causes memory movement
    may create problems. You can safely pass variables using SEG if the CALL
    statement's argument list contains only simple variables, arithmetic
    expressions, or arrays indexed without the use of intrinsic or
    user-defined functions.

    See Section 2.3.3, "Variable Storage Allocation," for a list of things
    that cause variable movement and for information about when to use near or
    far addresses for variables.

■ See Also

    CALL, CALLS (Non-BASIC); DECLARE (BASIC)

■ Example

    The following example shows a BASIC program that calls a short C function.
    The C program would be separately compiled and stored in a Quick library
    or explicitly linked to form the .EXE file.

    DEFINT a-z

    ' The function addone uses C argument passing and takes
    ' a single integer argument passed by value.
    DECLARE FUNCTION addone CDECL (BYVAL n AS INTEGER)

    INPUT x
    y=addone(x)
    PRINT "x and y are ";x;y

    END

    /* C function addone. Returns one more than the value of its
        integer argument. */
    int far addone(n)
    int n;
    {
        return(++n);
    }


────────────────────────────────────────────────────────────────────────────
DEF FN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines and names a function

■ Syntax 1

    DEF FNname«(parameterlist)» = expression

■ Syntax 2

    DEF FNname«(parameterlist)»
    .
    .
    .
    FNname = expression
    .
    .
    .
    END DEF

■ Remarks

    The DEF FN statement takes the following arguments:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    name                     A legal variable name, up to 40 characters long.
                            This name, combined with FN, is the name of the
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            This name, combined with FN, is the name of the
                            function. The name can include an explicit
                            type-declaration character to indicate the type
                            of value returned. Names that are the same except
                            for the type-declaration character are distinct
                            names. For example, the following are names of
                            three different DEF FN functions:

                            FNString$

                            FNString%

                            FNString#

                            To return a value from a DEF FN function, assign
                            the value to the full function name:

                            FNString$ = "No answer."

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────

    parameterlist            A list of variable names, separated by commas.
                            The syntax is explained below. When the function
                            is called, BASIC assigns the value of each
                            argument to its corresponding parameter. Function
                            arguments are passed by value. DEF FN functions
                            do not accept arrays, records, or fixed-length
                            strings as arguments.

    expression               In both syntaxes, expression is evaluated and the
                            result is the function's value. In Syntax 1,
                            expression is the entire body of the function and
                            is limited to one logical line.

                            When no expression is assigned to the name, the
                            default return values are zero for a numeric DEF
                            FN function, and the null string ("") for a
                            string DEF FN function.
    ──────────────────────────────────────────────────────────────────────────
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    ──────────────────────────────────────────────────────────────────────────


    A parameterlist has the following syntax:

    variable «AS type» «, variable «AS type»»...

    A variable is any valid BASIC variable name. The type is INTEGER, LONG,
    SINGLE, DOUBLE, or STRING. You may also indicate a variable's type by
    including a type-declaration character (%, &, !, #, or $) in the name.

────────────────────────────────────────────────────────────────────────────
NOTE
    The FUNCTION procedure offers greater flexibility and control than the DEF
    FN function. See the entry for FUNCTION and Chapter 2, "SUB and FUNCTION
    Procedures," in Programming in BASIC for more information.
────────────────────────────────────────────────────────────────────────────

    You must define a DEF FN function with a DEF FN statement before the
    function is used. Calling a DEF FN function before it is defined produces
    an error message that reads Function not defined. DEF FN function
    definitions cannot appear inside other DEF FN definitions. In addition,
    DEF FN functions cannot be recursive.

    You must use the EXIT DEF statement to leave a multiline DEF FN early. DEF
    FN functions can only be used in the module in which they are defined.
    They cannot be referenced from other modules.

    A DEF FN function may share variables with the module-level code.
    Variables not in the parameterlist are global──their values are shared
    with the calling program. To keep a variable value local to a function
    definition, declare it in a STATIC statement. See Chapter 2, "Data
    Types," for a discussion of local and global variables.

    DEF FN can return either numeric or string values. DEF FN returns a string
    value if name is a string variable name, and a numeric value if name is a
    numeric variable name. Assigning a numeric value to a string function name
    or assigning a string value to a numeric function name produces the error
    message Type mismatch.

    If the function is numeric, DEF FNname returns a value with the precision
    specified by name. For example, if name specifies a double-precision
    variable, then the value returned by DEF FNname is double precision,
    regardless of the precision of expression. Because BASIC may rearrange
    arithmetic expressions for greater efficiency, avoid using DEF FN
    functions that change program variables in expressions that may be
    reordered. The following example may give different results:

    DEF FNShort
        I=10
        FNShort=1
    END DEF
    I=1 : PRINT FNShort + I + I

    If BASIC reorders the expression so FNShort is called after calculating
    (I+I), the result is 3 rather than 21. You can usually avoid this problem
    by isolating the DEF FN function call:

    I = 1 : X = FNShort : PRINT X + I + I

    Doing I/O operations in DEF FN functions used in I/O statements or doing
    graphics operations in DEF FN functions in graphics statements may cause
    similar problems.

■ See Also

    EXIT, FUNCTION, STATIC

■ Example

    The following example uses a DEF FN function to calculate the factorial of
    an input number (the factorial of 3 is 3*2*1):

    DEF FNFactorial#(X)
        STATIC Tmp#, I
        Tmp#=1
        FOR I=2 TO X
        Tmp#=Tmp#*I
        NEXT I
        FNFactorial#=Tmp#
    END DEF

    INPUT "Enter a number: ",Num
    PRINT Num "factorial is" FNFactorial#(Num)

■ Output

    Enter a number: 3
    3 factorial is 6


────────────────────────────────────────────────────────────────────────────
DEF SEG Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the current segment address for a subsequent PEEK function or a
    BLOAD, BSAVE, CALL ABSOLUTE, or POKE statement

■ Syntax

    DEF SEG «=address»

■ Remarks

    For BLOAD, BSAVE, CALL ABSOLUTE, PEEK, and POKE, address is used as the
    segment. The address is a numeric expression returning an unsigned integer
    in the range 0-65,535. A value outside this range produces the error
    message Illegal function call. The previous segment is retained if an
    error occurs. If you omit address, the BASIC data segment is used.

    Be sure to separate DEF and SEG with a space. Otherwise, BASIC interprets
    the statement to mean "assign a value to the variable DEFSEG."

■ Differences From Basica

    In QuickBASIC, the CALL and CALLS statements do not use the segment
    address set by DEF SEG.

■ Example

    The following program uses DEF SEG, PEEK, and POKE statements to turn the
    CAPS LOCK on and off:

────────────────────────────────────────────────────────────────────────────
NOTE
    This program contains hardware-specific instructions. It works correctly
    on IBM PC, PC/XT(R), and PC/AT(R) computers.
────────────────────────────────────────────────────────────────────────────

    DECLARE SUB CapsOn ()
    DECLARE SUB CapsOff ()
    DECLARE SUB PrntMsg (R%,C%,M$)

    CLS

    ' Turn Caps Lock on.
    CapsOn
    PrntMsg 24,1,"<Caps Lock On>"

    ' Prompt for input to show keyboard has changed.
    LOCATE 12,10
    LINE INPUT "Enter a string (all characters are caps): ",S$

    ' Turn Caps Lock off.
    CapsOff
    PrntMsg 24,1,"              "

    PrntMsg 25,1,"Press any key to continue..."
    DO WHILE INKEY$="" : LOOP
    CLS
    END

    ' Turn Caps Lock on.
    SUB CapsOn STATIC
        ' Set segment to low memory.
        DEF SEG = 0
        ' Set Caps Lock on (turn on bit 6 of &H0417).
        POKE &H0417,PEEK(&H0417) OR &H40
        ' Restore segment.
        DEF SEG
    END SUB

    ' Turn Caps Lock off.
    SUB CapsOff STATIC
        DEF SEG=0
        ' Set Caps Lock off (turn off bit 6 of &H0417).
        POKE &H0417,PEEK(&H0417) AND &HBF
        DEF SEG
    END SUB

    ' Print message at Row%, Col% without changing cursor.
    SUB PrntMsg (Row%, Col%, Message$) STATIC
        ' Save current cursor position.
        CurRow%=CSRLIN : CurCol%=POS(0)
        LOCATE Row%,Col% : PRINT Message$;
        ' Restore cursor position.
        LOCATE CurRow%,CurCol%
    END SUB


────────────────────────────────────────────────────────────────────────────
DEFtype Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    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»...

■ Remarks

    The letterrange has the form:

    letter1«-letter2»

    where letter1 and letter2 are any of the uppercase or lowercase letters of
    the alphabet. Names beginning with the letters in letterrange have the
    type specified by the last three letters of the statement: integer (INT),
    long integer (LNG), single precision (SNG), double precision (DBL), or
    string (STR). For example, in the following program fragment, Message is a
    string variable:

    DEFSTR A-Q
    .
    .
    .
    Message="Out of stack space."

    The case of the letters in letterrange is not significant. All of the
    following statements are equivalent:

    DEFINT I-N
    DEFINT i-n
    DEFINT i-N

    A type-declaration character (%, &, !, #, or $) always takes precedence
    over a DEFtype statement. DEFtype statements do not affect record
    elements.

────────────────────────────────────────────────────────────────────────────
NOTE
    I!, I#, I&, I$, and I% are all distinct variables, and each may hold a
    different value.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    BASICA handles DEFtype statements differently. BASICA scans a statement
    each time before executing it. If the statement contains a variable
    without an explicit type (indicated by !, #, &, $, or %), the interpreter
    uses the current default type.

    In the example below, when BASICA interprets line 20, it determines that
    the current default type for variables beginning with I is integer. Line
    30 changes the default type to single precision. When BASICA loops back to
    line 20, it rescans the line and uses IFLAG as a single-precision
    variable.

    10  DEFINT I
    20  PRINT IFLAG
    30  DEFSNG I
    40  GOTO 20

    In contrast, QuickBASIC scans the text only once; once a variable appears
    in a program line, its type cannot be changed.

■ Example

    See the example for the ABS function.


────────────────────────────────────────────────────────────────────────────
DIM Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Declares a variable and allocates storage space

■ Syntax

    DIM «SHARED» variable«(subscripts)»«AS type»«,variable«(subscripts)»«AStype

■ Remarks

    The following list describes the parts of the DIM statement:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    SHARED                   The optional SHARED attribute allows all
                            procedures in a module to share arrays and simple
                            variables. This differs from the SHARED
                            statement, which affects only variables within a
                            single SUB or FUNCTION.

    variable                 A BASIC variable name.

    subscripts               The dimensions of the array. Multiple dimensions
                            can be declared. The subscript syntax is
                            described below.

    AS type                  Declares variable to be an elementary or
                            user-defined type. The elementary types are
                            INTEGER, LONG, SINGLE, DOUBLE, and STRING
                            (variable or fixed).
    ──────────────────────────────────────────────────────────────────────────

    Subscripts in DIM statements have the following form:

    «lower TO» upper «, «lower TO» upper»...

    The TO keyword provides a way to indicate both the lower and the upper
    bounds of an array's subscripts. The following statements are equivalent
    (if there is no OPTION BASE statement):

    DIM A(8,3)
    DIM A(0 TO 8, 0 TO 3)
    DIM A(8,0 TO 3)

    With the TO keyword, you are no longer restricted to positive subscripts.
    You can use TO to specify any range of subscripts from -32,768 to 32,767:

    DIM A(-4 TO 10)
    DIM B(-99 TO -5,-3 TO 0)

    If you use an array in your program without including the array in a DIM
    statement, the maximum value of each subscript of the array is 10. If you
    use a subscript that is greater than the specified maximum, an error
    message appears that says Subscript out of range.

    The DIM statement initializes all elements of numeric arrays to zero and
    all the elements of string arrays to null strings. The fields of record
    variables are initialized to zero, including fixed-string fields. The
    maximum number of dimensions allowed in a DIM statement is 60.

    If you try to dimension an array variable with a DIM statement after you
    have referred to the array, an error message results that reads Array
    already dimensioned. It is good programming practice to put the required
    DIM statements at the beginning of a program, outside of any loops.

    STATIC AND DYNAMIC ARRAYS

    How you declare an array also determines whether it is static (allocated
    when the program is translated) or dynamic (allocated when the program is
    run).

    ■ An array declared first in a COMMON statement is dynamic.

    ■ Implicitly dimensioned arrays are static.

    ■ Arrays dimensioned with numeric constants or CONST statement constants
    are static.

    ■ Arrays dimensioned with variables as subscripts are dynamic.

    The following list shows the different combinations and results:

    Statement                Result
    ──────────────────────────────────────────────────────────────────────────
    DIM A(0 TO 9)            The array A is allocated as a static array if
                            ¢DYNAMIC is not in effect.

    DIM A(MAXDIM)            If MAXDIM is defined in a CONST statement, A is a
                            static array. If MAXDIM is a variable, then the
                            array is a dynamic array and is only allocated
                            when the program reaches the DIM statement.
    ──────────────────────────────────────────────────────────────────────────

    See Appendix F, "Metacommands," in Programming in BASIC and Chapter 2,
    "Data Types," in this manual for more information about static and dynamic
    arrays.

────────────────────────────────────────────────────────────────────────────
NOTE
    If the array size exceeds 64K, if the array is not dynamic, and if the /AH
    option was not used, you may get an error message that reads Subscript out
    of range or one that reads Array too big. Reduce the size of the array or
    make the array dynamic and use the /AH command-line option.
────────────────────────────────────────────────────────────────────────────

    TYPE DECLARATIONS

    In addition to declaring the dimensions of an array, the DIM statement may
    also be used to declare the type of a variable. For example, this
    statement declares the variable to be an integer, even though there is no
    type declaration character or DEFINT statement:

    DIM NumberOfBytes AS INTEGER

    The DIM statement provides a mechanism for declaring specific variables to
    be records. In the following example, the variable TopCard is declared as
    a record variable:

    TYPE Card
        Suit AS STRING*9
        Value AS INTEGER
    END TYPE

    DIM TopCard AS Card

    You may also declare arrays of records:

    TYPE Card
        Suit AS STRING*9
        Value AS INTEGER
    END TYPE

    DIM Deck(1 TO 52) AS Card

    See Appendix F, "Metacommands," in Programming in BASIC and Chapter 2,
    "Data Types," in this manual for more information.

■ Differences From Basica

    BASICA executes a DIM statement when it encounters the statement in the
    program. The array is only allocated when the statement is executed, so
    all arrays in BASICA are dynamic.

■ See Also

    ERASE, OPTION BASE, REDIM, SHARED

■ Example

    The following example finds and prints the maximum and minimum of a set of
    values:

    ' Find the maximum and minimum of up to 20 values.
    '
    ' Dimension an array to hold the values.
    CONST MAXDIM=20
    DIM A(1 TO MAXDIM)
    ' Use DIM to set up two integer variables.
    ' All other variables are SINGLE.
    DIM NumValues AS INTEGER, I AS INTEGER

    ' Get the values.
    NumValues=0
    PRINT "Enter values one per line. Type END to end."

    DO
        INPUT A$
        IF UCASE$(A$)="END" OR NumValues>=MAXDIM THEN EXIT DO
        NumValues=NumValues+1
        A(NumValues)=VAL(A$)
    LOOP

    ' Find the maximum and minimum values.
    IF NumValues>0 THEN
        Max=A(1)
        Min=A(1)
        FOR I=1 TO NumValues
        IF A(I)>Max THEN Max=A(I)
        IF A(I)<Min THEN Min=A(I)
        NEXT I

        PRINT "The maximum is ";Max;" The minimum is ";Min
    ELSE
        PRINT "Too few values."
    END IF

■ Output

    Enter values one per line. Type END to end.
    ? 23.2
    ? 11.3
    ? 1.6
    ? end
    The maximum is  23.2  The minimum is  1.6


────────────────────────────────────────────────────────────────────────────
DO...LOOP Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    The following list describes the arguments of the DO...LOOP statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    statementblock           One or more BASIC statements to be repeated

    booleanexpression        Any expression that evaluates to true (nonzero)
                            or false (zero)
    ──────────────────────────────────────────────────────────────────────────

    You can use a DO...LOOP statement instead of a WHILE...WEND statement. The
    DO...LOOP is more versatile because it can test for a condition at the
    beginning or at the end of a loop.

■ Examples

    The first two examples below show you how placement of the condition
    affects the number of times the block of statements is executed. The third
    example illustrates testing at the end of a loop and presents a sort
    subprogram where an ending test is appropriate.

    In the following example, the test is done at the beginning of the loop.
    Because I is not less than 10, the body of the loop (the statement block)
    is never executed.

    ' DO...LOOP with test at the top of the loop.
    ' Output shows that loop was not executed.
    I = 10
    PRINT "Value of I at beginning of loop is  ";I
    DO WHILE I < 10
        I = I + 1
    LOOP
    PRINT "Value of I at end of loop is  ";I

■ Output

    Value of I at beginning of loop is  10
    Value of I at end of loop is  10

    The following example tests I at the end of the loop, so the statement
    block executes at least once.

    ' DO...LOOP with test at the bottom of the loop.
    ' Output shows loop was executed once.
    I = 10
        DO
        PRINT "Value of I at beginning of loop is  ";I
        I = I + 1
        LOOP WHILE I < 10
        PRINT "Value of I at end of loop is  ";I

■ Output

    Value of I at beginning of loop is  10
    Value of I at end of loop is 11

    The following sort subprogram tests at the end of the loop because the
    entire array must be examined at least once to see if it is in order. In
    general, test at the end of a loop only if you know that you always want
    the statement block executed at least once.

    ' Bubble sort subroutine
    '        Exes is array to sort
    '        N is number of elements in Exes
    '
    '        Note: sort assumes the first element of
    '              Exes is Exes(1).

    ' Set up a special value to indicate no exchanges.
    CONST NOEXCH=-1

    SUB sort(Exes(1),N) STATIC

    Limit=N
    DO

        Exchange=NOEXCH
        FOR I=1 TO Limit-1     ' Make one pass over the array.
        IF Exes(I) > Exes(I+1) THEN
            SWAP Exes(I),Exes(I+1)   'Exchange array elements.
            Exchange=I               'Record location of most
        END IF                      'recent exchange.
        NEXT I
        Limit=Exchange      'Sort on next pass only to where
                            'last exchange was done.
    LOOP UNTIL Exchange=NOEXCH  'Sort until no elements
                                'are exchanged.

    END SUB


────────────────────────────────────────────────────────────────────────────
DRAW Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Draws an object defined by stringexpression

■ Syntax

    DRAW stringexpression

■ Remarks

    The DRAW statement combines many of the capabilities of the other graphics
    statements into a graphics macro language, as described below under
    "Cursor-Movement Commands" and "Angle, Color, and Scale-Factor Commands."
    This macro language defines a set of characteristics that can be used to
    describe an image. These characteristics include motion (up, down, left,
    right), color, rotation angle, and scale factor. The stringexpression
    consists of these macro commands.

    CURSOR-MOVEMENT COMMANDS

    The following prefix commands can precede any of the movement commands:

    Prefix                   Description
    ──────────────────────────────────────────────────────────────────────────
    B                        Move, but do not plot any points.
    N                        Move, but return to original position when done.
    ──────────────────────────────────────────────────────────────────────────

    The following commands specify movement in units. The default unit size is
    one point; this unit size can be modified by the S command, which sets the
    scale factor. (S is described in "Angle, Color, and Scale-Factor
    Commands.") If no argument is supplied, the cursor is moved one unit.

    Each of the movement commands initiates movement from the current graphics
    position, which is usually the coordinate of the last graphics point
    plotted with another graphics macro-language command. The current position
    defaults to the center of the screen when a program is run.

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Movement                 Description
    ──────────────────────────────────────────────────────────────────────────
    U «n»                    Move up n units.

    D «n»                    Move down n units.

    L «n»                    Move left n units.

    R «n»                    Move right n units.

    E «n»                    Move diagonally up and right n units.

    F «n»                    Move diagonally down and right n units.

    Movement                 Description
    ──────────────────────────────────────────────────────────────────────────

    G «n»                    Move diagonally down and left n units.

    H «n»                    Move diagonally up and left n units.

    M x,y                    Move absolute or relative. If x is preceded by a
                            plus (+) or minus (-), the movement is relative
                            to the current point; that is, x and y are added
                            to (or subtracted from) the coordinates of the
                            current graphics position and connected with that
                            position by a line.

                            If no sign precedes x, the movement is absolute;
                            that is, a line is drawn from the current cursor
                            position to the point with coordinates x,y.
    ──────────────────────────────────────────────────────────────────────────


    ANGLE, COLOR, AND SCALE-FACTOR COMMANDS

    The following commands let you change the appearance of a drawing by
    rotating it, changing colors, or scaling it:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Command                  Description
    ──────────────────────────────────────────────────────────────────────────
    A n                      Set angle of rotation n. The value of n may range
                            from 0 to 3, where 0 is 0°, 1 is 90°, 2 is 180°,
                            and 3 is 270°. Figures rotated 90° or 270° are
                            scaled so they appear the same size using 0° or
                            180° on a monitor screen with a standard screen
                            width-to-height ratio of 4/3.

    TA n                     Turn an angle of n degrees; n must be in the
                            range -360 to 360. If n is positive, rotation is
                            counterclockwise; if n is negative, rotation is
                            clockwise. The following example uses TA to draw
                            spokes:

                            SCREEN 1
    Command                  Description
    ──────────────────────────────────────────────────────────────────────────
                            SCREEN 1
                            FOR D=0 TO 360  STEP 10
                                DRAW "TA="+VARPTR$(D)+"NU50"
                            NEXT D

    C n                      Set color to n. See COLOR, PALETTE, and SCREEN
                            statements for discussions of valid colors,
                            numbers, and attributes.

    S n                      Set scale factor n, which may range from 1 to
                            255. The scale factor multiplied by the distances
                            given with U, D, L, R, or relative M commands
                            gives the actual distance traveled.

    P paintcolor,            The paintcolor is the paint color for a figure's
    bordercolor              interior, while bordercolor is the paint color
                            for the figure's border. Tile painting (painting
                            an area with a graphic pattern) is not supported
                            in DRAW.
    Command                  Description
    ──────────────────────────────────────────────────────────────────────────
                            in DRAW.

    X stringexpression       Execute substring. This powerful command allows
                            you to execute a second substring from a string.
                            You may have one string expression execute
                            another, which executes a third, and so on.
                            Numeric arguments can be constants like 123 or
                            variable names.
                            QuickBASIC requires the "X" +
                            VARPTR$(stringexpression) form of this command.
                            (See "Differences from BASICA" below.)
    ──────────────────────────────────────────────────────────────────────────


■ Differences From Basica

    The DRAW statement requires modification of BASICA programs when used with
    QuickBASIC. Specifically, the compiler requires the VARPTR$ form for
    variables. Statements such as the following:

    DRAW "XA$"

    DRAW "TA = ANGLE"

    (where A$ and ANGLE are variables) must be changed as follows:

    DRAW "X" + VARPTR$(A$)

    DRAW "TA =" + VARPTR$(ANGLE)

    when using the compiler.

    The compiler does not support the Xstringexpression command. However, you
    may execute a substring by appending the character form of the address to
    X. For example, the following two statements are equivalent. The first
    statement works when within the environment and when using the compiler;
    the second works only within the environment.

    DRAW "X" + VARPTR$(A$)
    DRAW "XA$"

■ Examples

    The following program draws a triangle's outline in magenta and paints the
    interior cyan:

    SCREEN 1
    DRAW "C2"             'Set color to magenta.
    DRAW "F60 L120 E60"   'Draw a triangle.
    DRAW "BD30"           'Move down into the triangle.
    DRAW "P1,2"           'Paint interior.

    The following example shows different ways of using the M macro command:
    with absolute movement and relative movement; using string-variable
    arguments; and using numeric-variable arguments:

    SCREEN 2
    'Absolute movement
    DRAW "M 50,80"
    DRAW "M 80,50"
    'Relative movement
    DRAW "M+40,-20"
    DRAW "M-40,-20"
    DRAW "M-40,+20"
    DRAW "M+40,+20"
    'Using a string variable.
    X$ = "400" : Y$ = "190"
    DRAW "M" + X$ + "," + Y$
    'Using numeric variables (note the two "=" signs).
    A = 300 : B = 120
    DRAW "M="+VARPTR$(A)+",="+VARPTR$(B)

    The following example draws a clock on the screen using the TIME$
    function:

    ' Declare procedure.
    DECLARE SUB Face (Min$)

    ' Select 640 x 200 pixel high-resolution graphics screen.
    SCREEN 2

    DO

        ' Clear the screen.
        CLS

        ' Get the string containing the minutes value.
        Min$ = MID$(TIME$,4,2)

        ' Draw the clock face.
        Face Min$

        ' Wait until the minute changes or a key is pressed.
        DO

        ' Print the time at the top of the screen.
        LOCATE 2,37
        PRINT TIME$

        ' Test for a key press.
        Test$ = INKEY$
        LOOP WHILE Min$ = MID$(TIME$,4,2) AND Test$ = ""

    ' End the program when a key is pressed.
    LOOP WHILE Test$ = ""
    END
    ' Draw the clock face.
    SUB Face (Min$) STATIC
        LOCATE 23,30
        PRINT "Press any key to end"
        CIRCLE (320,100),175

        ' Convert strings to numbers.
        Hr = VAL(TIME$)
        Min = VAL(Min$)

        ' Convert numbers to angles.
        Little = 360 - (30 * Hr + Min/2)
        Big = 360 - (6*Min)

        ' Draw the hands.
        DRAW "TA=" + VARPTR$(Little) + "NU40"
        DRAW "TA=" + VARPTR$(Big) + "NU70"
    END SUB


────────────────────────────────────────────────────────────────────────────
END Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Ends a BASIC program, procedure, or block

■ Syntax

    END «{DEF | FUNCTION | IF | SELECT | SUB | TYPE}»

■ Remarks

    There are several ways to use the END statement, as described in the
    following list:

    Statement                Description
    ──────────────────────────────────────────────────────────────────────────
    END DEF                  Ends a multiline DEF FN function definition. You
                            must use END DEF with a multiline DEF FN.

    END FUNCTION             Ends a FUNCTION procedure definition. You must
                            use END FUNCTION with FUNCTION.

    END IF                   Ends a block IF...THEN...ELSE statement. You must
                            use END IF with block IF...THEN...ELSE.

    END SELECT               Ends a SELECT CASE block. You must use END SELECT
                            with a SELECT CASE statement.

    END SUB                  Ends a BASIC subprogram. You must use END SUB
                            with SUB.

    END TYPE                 Ends a user-defined type definition. You must use
                            END TYPE with TYPE.
    ──────────────────────────────────────────────────────────────────────────

    By itself, the END statement stops program execution and closes all files.
    In a stand-alone program, END returns control to the operating system.
    When running inside the QuickBASIC environment, END returns you to that
    environment.

    The compiler always assumes an END statement at the conclusion of any
    program, so omitting an END statement at the end of a program still
    produces proper program termination. You may place END statements anywhere
    in the program to end program execution.

■ See Also

    DEF FN; FUNCTION; IF...THEN...ELSE; SELECT CASE; SUB; TYPE

■ Example

    The following example uses a subprogram to query the user about continuing
    some action. If the user enters n or N the subprogram ends the program.

    DO
    .
    .
    .
    CALL ContinueQuery
    LOOP

    SUB ContinueQuery STATIC
        DO
        INPUT "Continue (Y or N)"; Response$
        R$=UCASE$(LEFT$(Response$,1))
        IF R$="N" THEN END
        IF R$="Y" THEN EXIT DO
        BEEP
        LOOP
    END SUB


────────────────────────────────────────────────────────────────────────────
ENVIRON$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Retrieves an environment string from the DOS environment-string table

■ Syntax

    ENVIRON$ (environmentstring)
    ENVIRON$ (n)

■ Remarks

    The environmentstring is a string constant or variable containing the name
    of an environment variable. The argument n is a numeric expression.

    If you specify an environmentstring name, but it cannot be found in the
    environment-string table, or there is no text following it, then ENVIRON$
    returns a null string. Otherwise, ENVIRON$ returns the text following the
    equal sign in the environment-string table.

    If you specify a numeric argument (n), the nth string in the
    environment-string table is returned. In this case, the string includes
    all of the text, including the environmentstring name. If the nth string
    does not exist, ENVIRON$ returns a null string. The n argument can be any
    numeric expression; it is rounded to an integer.

■ Example

    The following example prints the current environment-string table
    settings:

    I = 1
    DO WHILE ENVIRON$(I) <> ""
        PRINT ENVIRON$(I)
        I = I + 1
    LOOP

■ Output

    COMSPEC=C:\COMMAND.COM
    TMP=c:\tmp
    PATH=C:\TOOLS;C:\BIN
    PROMPT=¢ec4$l¢ec7$p¢ec4$g¢ec7¢eb1
    INIT=c:\tools
    LIB=c:\lib
    INCLUDE=c:\include


────────────────────────────────────────────────────────────────────────────
ENVIRON Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Modifies a parameter in the DOS environment-string table

■ Syntax

    ENVIRON stringexpression

■ Remarks

    The stringexpression must be of the form parameterid=text, or the form
    parameterid text. Everything to the left of the equal sign or space is
    assumed to be a parameter, and everything to the right, text.

    If the parameterid has not previously existed in the environment-string
    table, it is appended to the end of the table. If a parameterid exists in
    the table when the ENVIRON statement is executed, it is deleted and the
    new parameterid is appended to the end of the table.

    The text string is the new parameter text. If the text is a null string
    ("") or a semicolon (";"), then the existing parameter is removed from the
    environment-string table and the remaining body of the table is
    compressed.

    DOS discards the environment-string table modified by this function when
    your program ends. The environment-string table is the same as it was
    before your program ran.

    You may use this statement to change the PATH parameter for a "child"
    process (a program or command started by a SHELL statement) or to pass
    parameters to a child by inventing a new environment parameter.

    Errors in environment-string tables include parameters that are not
    strings and lack of free space. An Out of memory error message is printed
    when no more space can be allocated to the environment-string table. The
    amount of free space in the table is usually quite small.

■ See Also

    ENVIRON$, SHELL

■ Example

    The following example changes the value of the PATH environment variable
    to that shown:

    'Change value of PATH environment variable.
    ENVIRON "PATH=A:\SALES;A:\ACCOUNTING"


────────────────────────────────────────────────────────────────────────────
EOF Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Tests for the end-of-file condition

■ Syntax

    EOF(filenumber)

■ Remarks

    The EOF function returns -1 (true) if the end of a sequential file has
    been reached. Use the EOF function to test for end-of-file while inputting
    data. In this way you may avoid the Input past end error message.

    When EOF is used with random-access or binary files, it returns "true" if
    the last executed GET statement was unable to read an entire record. This
    happens because of an attempt to read beyond the end of the file.

    EOF cannot be used with the BASIC devices SCRN:, KYBD:, CONS:, and LPTn:.

    When you use EOF with a communications device, the definition of the
    end-of-file condition is dependent on the mode (ASCII or binary) in which
    you opened the device. In ASCII mode, EOF is false until you receive
    CTRL+Z, after which it remains true until you close the device. In binary
    mode, EOF is true when the input queue is empty (LOC(n)=0). It becomes
    "false" when the input queue is not empty.

■ Example

    The fragment below reads single-precision values from a file until all
    values have been read:

    DIM M(0 TO 2000)

    OPEN "DATA" FOR INPUT AS 1
    C = 0
    DO WHILE NOT EOF(1) AND C <= 2000
        INPUT #1, M(C)
        C = C+1
    LOOP
    .
    .
    .


────────────────────────────────────────────────────────────────────────────
ERASE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Reinitializes the elements of static arrays; deallocates dynamic arrays

■ Syntax

    ERASE arrayname «,arrayname...»

■ Remarks

    The arrayname arguments are the names of arrays to erase. ERASE has
    different effects on static and dynamic arrays.

    The ERASE statement sets the elements of a static array to zeros in the
    case of a numeric array or null strings ("") in the case of a string
    array. If the array is an array of records, the ERASE statement sets all
    elements of each record to zeros, including fixed-string elements.

    However, using ERASE on a dynamic array frees the memory used by the
    array. Before your program can refer to the dynamic array again, it must
    first redimension the array with a DIM or REDIM statement. Redimensioning
    an array with a DIM statement without first erasing it produces a
    duplicate definition run-time error message that reads Array already
    dimensioned. The ERASE statement is not required when arrays are
    redimensioned with REDIM.

    See Chapter 2, "Data Types," in this manual and Appendix F,
    "Metacommands," in Programming in BASIC for more information on declaring
    dynamic and static arrays.

■ See Also

    DIM, REDIM

■ Example

    The following program fragment shows the use of ERASE with the ¢DYNAMIC
    and ¢STATIC metacommands:

    REM ¢DYNAMIC
    DIM A(100,100)
    .
    .
    .

    'This deallocates array A.
    ERASE A
    'Redimension array A.
    REDIM A(5,5)
    REM ¢STATIC
    DIM B(50,50)
    .
    .
    .
    'This sets all elements of B equal to zero.
    'B still has the dimensions assigned by DIM.
    ERASE B


────────────────────────────────────────────────────────────────────────────
ERDEV, ERDEV$ Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Provides device-specific status information after an error

■ Syntax

    ERDEV
    ERDEV$

■ Remarks

    ERDEV is an integer function that returns an error code from the last
    device to declare an error. ERDEV$ is a string function that returns the
    name of the device generating the error. Because ERDEV and ERDEV$ return
    meaningful information only after an error, they are usually used in error
    handlers specified by an ON ERROR statement.

    ERDEV and ERDEV$ cannot be used on the left side of an assignment.

    ERDEV is set by the critical error handler (interrupt 24H) when DOS
    detects an error that prevents continuing.

    The value of ERDEV is a bit-encoded value containing the DOS error
    information. The lower eight bits (first byte) contain the DOS error code,
    a value from 0 to 12. The upper eight bits (second byte) contain bits 15,
    14, 13, XX, 3, 2, 1, and 0, in that order, of the device-attribute word.
    XX indicates the bit is always zero. See the Microsoft MS-DOS Programmer's
    Reference for more information about device-attribute words.

■ See Also

    ERR, ERL; ON ERROR

■ Example

    The following example prints the values of ERDEV and ERDEV$ when an error
    occurs:

    DEFINT A-Z

    ' Indicate first line of error handler.
    ON ERROR GO TO ErrorHandler

    ' Attempt to open the file.
    OPEN "A:JUNK.DAT" FOR INPUT AS #1

    END

    ' Error handling routine.
    ' Prints values of ERDEV and ERDEV$ and dies.

    ErrorHandler:
        PRINT "ERDEV value is ";ERDEV
        PRINT "Device name is ";ERDEV$
        ON ERROR GOTO 0

■ Output

    Running the program with drive A unlatched produces the following output
    (2 is the error code for "Drive not ready"):

    ERDEV value is  2
    Device name is A:


────────────────────────────────────────────────────────────────────────────
ERR, ERL Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Return error status

■ Syntax

    ERR
    ERL

■ Remarks

    After an error, the function ERR returns the code for the error, and the
    ERL function returns the line number where the error occurred. Because ERR
    and ERL return meaningful values only after an error, they are usually
    used in error-handling routines to determine the error and the corrective
    action.

    Because ERL and ERR are functions, you cannot use them on the left-hand
    side of an assignment statement. However, you may indirectly set them with
    the ERROR statement.

■ Differences From Basica

    The ERL function returns only the line number, not line label, located
    before the line producing the error. If your program has no line numbers,
    ERL always returns 0.

■ See Also

    ERDEV, ERROR, ON ERROR, RESUME

■ Example

    See the example for ON ERROR.


────────────────────────────────────────────────────────────────────────────
ERROR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Simulates the occurrence of a BASIC error or allows the user to define
    error codes

■ Syntax

    ERROR integerexpression

■ Remarks

    The integerexpression represents the error code. It must be greater than 0
    and less than or equal to 255. If the integerexpression is an error code
    already used by BASIC, then the ERROR statement simulates the occurrence
    of that error and prints the corresponding error message.

    To define your own error code, use a value that is greater than any used
    by the standard BASIC error codes. (Start at 255 and work down to maintain
    compatibility with future Microsoft BASIC error codes.)

    If an ERROR statement specifies a code for which no error message has been
    defined, the message Unprintable error is printed. Executing an ERROR
    statement for which there is no error-handling routine causes an error
    message to be printed and execution to halt.

■ See Also

    ERR, ERL; ON ERROR; RESUME

■ Example

    The following fragment uses an ERROR statement to trap a user input error:

    ON ERROR GOTO Handler
    OpenFile:
        INPUT "Name of file to update";FileSpec$
        IF FileSpec$ = "" THEN END
        OPEN FileSpec$ FOR INPUT AS #1
        PRINT "The first five lines of ";FILESPEC$;" are:" : PRINT
        FOR I = 1 TO 5
            LINE INPUT #1, Temp$
            PRINT Temp$
        NEXT
        PRINT : INPUT "Is this the correct file";R$
        'Define error 200.
        IF LEFT$(R$,1) <> "y" THEN ERROR 200
        .
        .
        .
        END

    Handler:        'Error-handling routine.
        Number = ERR
        'Run-time error for "file not found."
        IF Number = 53 THEN
            CLOSE #1
            PRINT "File not in this directory"
            PRINT "Enter new file spec ([d:]xxx...xxx) or"
            PRINT "press <RETURN> to end program"
            RESUME OpenFile
        ELSEIF Number = 200 THEN
    'User entered "n"
            CLOSE #1
            RESUME OpenFile
        ELSE
            ERROR Number       'Error other than 53 or 200.
            ON ERROR GOTO 0    'Print message, disable error
        END IF                 'handling, and stop program.

■ Output

    Name of file to update? c:novelallenadv.txt
    File not in this directory
    Enter new file spec ([d:]xxx...xxx) or
    press <RETURN> to end program
    Name of file to update? c:toryallenadv.txt
    The first five lines of c:toryallenadv.txt are:

    Allen gripped the microphone. Small beads
    of perspiration glistened on his forehead
    like cheap pearls. He knew that what he
    said would change his life and the lives
    of those he loved. In a trembling voice,

    Is this the correct file? y


────────────────────────────────────────────────────────────────────────────
EXIT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Exits a DEF FN function, DO...LOOP or FOR...NEXT loop, FUNCTION, or SUB

■ Syntax

    EXIT {DEF | DO | FOR | FUNCTION | SUB }

■ Remarks

    There are several ways to use the EXIT statement as described in the
    following list:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Statement                Description
    ──────────────────────────────────────────────────────────────────────────
    EXIT DEF                 Causes an immediate exit from the executing DEF
                            FN function. Program execution continues where
                            the DEF FN function was invoked.

    EXIT DO                  Provides an alternative exit from a DO...LOOP.
                            Can be used only inside a DO...LOOP statement;
                            EXIT DO transfers control to the statement
                            following the LOOP statement. When used within
                            nested DO...LOOP statements, transfers out of the
                            immediately enclosing loop.

    Statement                Description
    ──────────────────────────────────────────────────────────────────────────

    EXIT FOR                 Provides another way to exit a FOR...NEXT loop.
                            May appear only in a FOR...NEXT loop; transfers
                            control to the statement following the NEXT
                            statement. When used within nested FOR...NEXT
                            loops, transfers out of the immediately enclosing
                            loop.

    EXIT FUNCTION            Causes an immediate exit from a FUNCTION
                            procedure. Program execution continues where the
                            FUNCTION was invoked. Can only be used in a
                            FUNCTION procedure.

    EXIT SUB                 Immediately exits a SUB procedure. Program
                            execution continues with the statement after the
                            CALL statement. Can only be used in a SUB
                            procedure.
    ──────────────────────────────────────────────────────────────────────────

    Statement                Description
    ──────────────────────────────────────────────────────────────────────────


    None of the EXIT statements define the end of the structure in which they
    are used. EXIT statements only provide an alternative exit from the
    structure.

■ See Also

    DEF FN; DO...LOOP; FOR...NEXT; FUNCTION; SUB

■ Examples

    See the third example for STATIC for a use of EXIT SUB.

    The following subprogram is an extended RTRIM$ that removes trailing
    blanks, tabs, carriage returns, and line feeds from a string. The
    subprogram begins looking at the end of the string and uses EXIT FOR to
    jump out of the loop when the first printing character is found.

    ' Rtrim removes trailing blanks, tabs, carriage returns,
    ' and line feeds from a string.
    SUB Rtrim(S$) STATIC

    J=0

    ' Begin at the end of the string and find the first
    ' character that isn't a blank, tab, carriage return, or
    ' line feed.
    FOR I=LEN(S$) TO 1 STEP -1
        C$=MID$(S$,I,1)
        IF C$<>" " AND C$<>CHR$(9) AND C$<>CHR$(10) AND C$<>CHR$(13) THEN
        J=I
        EXIT FOR
        END IF
    NEXT I

    ' Remove the unwanted trailing characters.
    S$=LEFT$(S$,J)

    END SUB


────────────────────────────────────────────────────────────────────────────
EXP Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Calculates the exponential function

■ Syntax

    EXP(x)

■ Remarks

    The EXP function returns e (the base of natural logarithms) to the power
    of x. The exponent x must be less than or equal to 88.02969. A value of x
    greater than 88.02969 produces an Overflow error message.

    The calculation of EXP is performed in single precision by default; if the
    argument x is double precision, EXP is calculated in double precision.

■ See Also

    LOG

■ Example

    The following program uses the EXP function to calculate the growth of a
    bacterial colony over a 15-day period. Since the growth of the population
    is related to its ever-changing size, its growth is exponential.

    INPUT "Initial bacterial population"; Colony0
    INPUT "Growth rate per day as a percentage of population"; Rate
    R = Rate/100 : Form$="##          ###,###"
    PRINT : PRINT "Day        Population"
    FOR T = 0 TO 15 STEP 5
        PRINT USING Form$; T, Colony0 * EXP(R*T)
    NEXT

■ Output

    Initial bacterial population? 10000
    Growth rate per day as a percentage of population? 10

    Day        Population
    0           10,000
    5           16,487
    10           27,183
    15           44,817


────────────────────────────────────────────────────────────────────────────
FIELD Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Allocates space for variables in a random-access file buffer

■ Syntax

    FIELD «#»filenumber, fieldwidth AS stringvariable...

■ Remarks

    The following list describes the FIELD statement's arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filenumber               The number used in the file's OPEN statement

    fieldwidth               The width of the field in the record

    stringvariable           The string variable that contains the date read
                            from a record or data that is used in an
                            assignment when information is written to a
                            record
    ──────────────────────────────────────────────────────────────────────────

    The total number of bytes that you allocate in a FIELD statement must not
    exceed the record length that you had specified when opening the file.
    Otherwise, an error message is generated that reads FIELD overflow. (The
    default record length is 128 bytes.)

    Any number of FIELD statements may be executed for the same file. All
    FIELD statements that have been executed remain in effect at the same
    time.

    All field definitions for a file are removed when the file is closed; that
    is, all strings defined as fields associated with the file are set to
    null.

    Do not use a variable name defined as a field in an INPUT or assignment
    statement if you wish the variable to remain a field. Once a variable name
    is a field, it points to the correct place in the random-access file
    buffer. If a subsequent INPUT or assignment statement with that variable
    name is executed, the variable's pointer no longer refers to the
    random-access record buffer, but to string space.

────────────────────────────────────────────────────────────────────────────
NOTE
    BASIC's record variables and extended OPEN statement syntax provide a more
    convenient way to use random-access files. See Chapter 3, "File and Device
    I/O," in Programming in BASIC for an extended discussion of using record
    variables for file I/O.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    When a random-access file is closed with a CLOSE or RESET statement in a
    compiled program, all variables that are fields associated with that file
    are reset to null strings. When a random-access file is closed in a BASICA
    program, variables that are fields retain the last value assigned to them
    by a GET statement.

■ See Also

    GET, LSET, OPEN, PUT, RSET

■ Example

    This example illustrates a random-access file buffer with multiple
    definitions. In the first FIELD statement, the 67-byte buffer is broken up
    into five separate variables for name, address, city, state, and zip code.
    In the second FIELD statement, the same buffer is assigned entirely to one
    variable, PLIST$. The remainder of this example checks to see if ZIP$,
    which contains the zip code, falls within a certain range; if it does, the
    complete address string is printed.

    ' Define field and record lengths with constants.
    CONST LNAML=25, ADDRL=25, CTYL=10, STL=2, ZIPL=5
    CONST RECLEN=LNAML+ADDRL+CTYL+STL+ZIPL

    OPEN "MAILLIST" FOR RANDOM AS #1 LEN=RECLEN

    FIELD #1, LNAML AS Lnam$, ADDRL AS Addr$, CTYL AS Cty$, STL AS St$,
    ZIPL AS Zip$
    FIELD #1, RECLEN AS Plist$

    GET #1, 1
    ' Read the file, looking for zip codes in the range 85699 to
    ' 85801.
    DO WHILE NOT EOF(1)
        Zcheck$ = Zip$
        IF (Zcheck$ >= "85699" AND Zcheck$ <= "85801") THEN
        Info$ = Plist$
        PRINT LEFT$(Info$,25)
        PRINT MID$(Info$,26,25)
        PRINT RIGHT$(Info$,17)
        END IF
        GET #1
    LOOP


────────────────────────────────────────────────────────────────────────────
FILEATTR Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns information about an open file

■ Syntax

    FILEATTR(filenumber,attribute)

■ Remarks

    The FILEATTR function takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filenumber               The number of an open file. This is the same
                            number used in the OPEN statement. You can use a
                            numeric expression as long as it evaluates to the
                            number of an open file.

    attribute                Indicates the type of information to return. When
                            attribute is 1, FILEATTR returns a code
                            indicating a file's mode (see below). When
                            attribute is 2, FILEATTR returns the file's DOS
                            file handle.
    ──────────────────────────────────────────────────────────────────────────

    Table R.2 lists the return values and corresponding file modes when
    attribute is 1.

    Table R.2   FILEATTR Mode Codes

    Return Value             Mode
    ──────────────────────────────────────────────────────────────────────────
    1                        INPUT

    2                        OUTPUT

    4                        RANDOM

    8                        APPEND

    32                       BINARY
    ──────────────────────────────────────────────────────────────────────────

■ See Also

    OPEN

■ Example

    The following example opens two files and prints out the DOS file handles
    and modes returned by FILEATTR:


    OPEN "tempfile.dat" FOR APPEND AS #1
    OPEN "tempfl2.dat" FOR RANDOM AS #2

    PRINT "Number Handle Mode"
    PRINT TAB(2);1;TAB(10);FILEATTR(1,2);TAB(15);FILEATTR(1,1)
    PRINT TAB(2);2;TAB(10);FILEATTR(2,2);TAB(15);FILEATTR(2,1)
    END

■ Output

    Number Handle Mode
    1       5    8
    2       6    4


────────────────────────────────────────────────────────────────────────────
FILES Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Prints the names of files residing on the specified disk

■ Syntax

    FILES «filespec»

■ Remarks

    The filespec is a string variable or constant that includes either a file
    name or a path name, and an optional device designation.

    If you omit filespec, the FILES statement lists all the files in the
    current directory. You may use the DOS wild card characters──question
    marks (?) or asterisks (*). A question mark matches any single character
    in the file name or extension. An asterisk matches one or more characters
    starting at that position.

    If you use a filespec without an explicit path, the current directory is
    the default.

    Note that, regardless of the path name contained in filespec, the header
    printed by FILES is always the current directory.

■ Examples

    The following statements illustrate the use of FILES:

    FILES              'Shows all files on the current directory.

    FILES "*.BAS"      'Shows all files with the extension .BAS.

    FILES "B:*.*"      'Shows all files on drive B.

    FILES "B:"         'Equivalent to "B:*.*".

    FILES "TEST?.BAS"  'Shows all five-letter files whose names
                        'start with "TEST" and end with the .BAS
                        'extension.

    FILES "\SALES"     'If SALES is a directory, this statement
                        'displays all files in SALES; if SALES is
                        'a file in the current directory, this
                        'statement displays the name SALES.


────────────────────────────────────────────────────────────────────────────
FIX Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the truncated integer part of x

■ Syntax

    FIX(x)

■ Remarks

    The x is a numeric expression. FIX(x) is equivalent to SGN(x)*INT(ABS(x)).
    The difference between FIX and INT is that for negative x, FIX returns the
    first negative integer greater than x, while INT returns the first
    negative integer less than x.

■ See Also

    CINT, INT

■ Example

    The following four statements illustrate the differences between INT and
    FIX:


    PRINT INT(-99.8)
    PRINT FIX(-99.8)
    PRINT INT(-99.2)
    PRINT FIX(-99.2)

■ Output

    -100
    -99
    -100
    -99


────────────────────────────────────────────────────────────────────────────
FOR...NEXT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Repeats a group of instructions a specified number of times

■ Syntax

    FOR counter = start TO end «STEP increment»
    .
    .
    .
    NEXT «counter «,counter...»»

■ Remarks

    The FOR statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    counter                  A numeric variable used as the loop counter. The
                            variable cannot be an array element or a record
                            element.

    start                    The initial value of the counter.

    end                      The final value of the counter.

    increment                The amount the counter is incremented each time
                            through the loop. If you do not specify STEP,
                            increment defaults to one.
    ──────────────────────────────────────────────────────────────────────────

    A FOR...NEXT loop executes only if start and end are consistent with
    increment. If end is greater than start, increment must be positive. If
    end is less than start, increment must be negative. This is checked at
    run-time by comparing the sign of (end - start) with the sign of step. If
    both have the same sign, the FOR...NEXT loop is entered. If not, the
    entire loop is skipped over.

    Within the FOR...NEXT loop, the program lines following the FOR statement
    are executed until the NEXT statement is encountered. Then counter is
    changed by the amount specified by STEP, and compared with the final
    value, end.

    If counter is less than or equal to end, control returns to the statement
    after the FOR statement and the process repeats. If counter is greater
    than end, the loop is exited; execution continues with the statement
    following the NEXT statement. (If STEP is negative, the loop repeats until
    counter is less than end.)

    If start and end have the same value, the loop executes once, regardless
    of the value of STEP. If STEP is zero, the loop repeats indefinitely.

    Avoid changing the value of counter within the loop. Changing the loop
    counter is poor programming practice; it makes the program more difficult
    to read and debug.

    You can nest FOR...NEXT loops; that is, you can place a FOR...NEXT loop
    within another FOR...NEXT loop. To ensure that nested loops work properly,
    give each loop a unique variable name as its counter. The NEXT statement
    for the inside loop must appear before the NEXT statement for the outside
    loop. The following construction is correct:

    FOR I = 1 TO 10
        FOR J = 1 TO 10
        FOR K = 1 TO 10
        .
        .
        .
        NEXT K
        NEXT J
    NEXT I

    A NEXT statement with the form

    NEXT K, J, I

    is equivalent to the following sequence of statements:

    NEXT K
    NEXT J
    NEXT I

    The EXIT FOR statement is a convenient alternative exit from FOR...NEXT
    loops. See the EXIT FOR statement.

────────────────────────────────────────────────────────────────────────────
NOTE
    If you omit the variable in a NEXT statement, the NEXT statement matches
    the most recent FOR statement. If a NEXT statement is encountered before
    its corresponding FOR statement, an error message is generated that reads
    NEXT without FOR.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    Unlike BASICA, QuickBASIC supports double-precision control values (start,
    end, and counter) in its FOR...NEXT loops. However, if the control values
    fall within the range for integers, you should use integer control values
    for maximum speed.

■ Example

    The following example prints the first 11 columns of Pascal's triangle:


    'Print the first MAXCOL columns of Pascal's Triangle, in which
    'each number is the sum of the number immediately above it
    'and the number immediately below it in the preceding column.

    CONST MAXCOL=11
    DIM A(MAXCOL,MAXCOL)
    FOR M = 1 TO MAXCOL
        A(M,1) = 1 : A(M,M) = 1 'Top and bottom of each column is 1.
    NEXT

    FOR M = 3 TO MAXCOL
        FOR N = 2 TO M-1
        A(M,N) = A(M-1,N-1) + A(M-1,N)
        NEXT
    NEXT
    Startrow = 13                'Go to the middle of the screen.
    FOR M = 1 TO MAXCOL
        Col = 6 * M
        Row = Startrow
        FOR N = 1 TO M
        LOCATE Row,Col : PRINT A(M,N)
        Row = Row + 2        'Go down 2 rows to print next number.
        NEXT
        PRINT
        Startrow = Startrow - 1  'Next column starts 1 row above
    NEXT                        'preceding column.

■ Output


                                                    1
                                                1
                                            1         10
                                        1         9
                                1         8         45
                            1         7         36
                        1         6         28        120
                    1         5         21        84
            1         4         15        56        210
        1         3         10        35        126
    1         2         6         20        70        252
        1         3         10        35        126
            1         4         15        56        210
                    1         5         21        84
                        1         6         28        120
                            1         7         36
                                1         8         45
                                        1         9
                                            1         10
                                                1
                                                    1


────────────────────────────────────────────────────────────────────────────
FRE Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the amount of available memory

■ Syntax 1

    FRE(numeric-expression)

■ Syntax 2

    FRE(stringexpression)

■ Remarks

    The FRE function returns the following values when it has a numeric
    argument (numeric-expression):

    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    -1                       The size, in bytes, of the largest nonstring
                            array that could be dimensioned

    -2                       The amount, in bytes, of unused stack space
                            available to the program

    Any other numeric value  The size of the next free block of string storage
    ──────────────────────────────────────────────────────────────────────────

    When the argument is a string expression (stringexpression), FRE returns
    the size, in bytes, of the free string storage. Before FRE returns the
    number of free bytes, it compacts the free string storage into a single
    block.

────────────────────────────────────────────────────────────────────────────
NOTE
    FRE(-2) returns meaningful values only when a program is executing. Values
    returned by FRE(-2) are not accurate when the function is called from the
    Immediate window, during program tracing, or when watching a variable.
────────────────────────────────────────────────────────────────────────────

■ Example

    The following example shows some of the values FRE returns before and
    after dimensioning an array:

    ' ¢DYNAMIC
    PRINT "Before dimensioning arrays:  " FRE(""),FRE(0),FRE(-1)
    DIM LARGE%(150,150), BIG$(5000)
    PRINT "After dimensioning arrays:   " FRE(""),FRE(0),FRE(-1)

■ Output

    The actual values FRE will return on your own computer may be different.

    Before dimensioning arrays:   58420       58420       322120
    After dimensioning arrays:    38404       38404       276496


────────────────────────────────────────────────────────────────────────────
FREEFILE Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the next free BASIC file number

■ Syntax

    FREEFILE

■ Remarks

    The FREEFILE function returns the next valid unused file number.

    You can use this function to avoid having SUB or FUNCTION procedures use
    file numbers that are already in use.

■ Example

    The example below uses FREEFILE to obtain a file number for opening a
    file:

    INPUT "Enter file name ", Filename$
    Filenum = FREEFILE
    OPEN Filename$ for Input as Filenum
    PRINT Filename$;" Opened as File # "; Filenum

■ Output

    Enter file name: Data.dat

    Data.dat Opened as File # 1


────────────────────────────────────────────────────────────────────────────
FUNCTION Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Declares the name, the parameters, and the code that form the body of a
    FUNCTION procedure

■ Syntax

    FUNCTION name «(parameterlist)»«STATIC»
    .
    .
    .
    name = expression
    .
    .
    .
    END FUNCTION

■ Remarks

    The following list describes the parts of the FUNCTION statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    name                     The name of the function. FUNCTION names follow
                            the same rules as BASIC variable names and can
                            include a type-declaration character (%, &, !, #,
                            or $). Note that the type of the name determines
                            the type of value the function returns. For
                            example, to create a function that returns a
                            string, you would include a dollar sign in the
                            name or give it a name defined as a string name
                            by a DEFSTR statement.

    parameterlist            The list of variables, separated by commas,
                            passed to the FUNCTION. The parameters are passed
                            by reference, so any change to a parameter's
                            value inside the function changes its value in
                            the calling program.

    STATIC                   Indicates that the function's local variables are
                            to be saved between calls. Without STATIC, the
                            local variables are allocated each time the
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            local variables are allocated each time the
                            function is invoked, and the variables' values
                            are lost when the function returns to the calling
                            program. The STATIC attribute does not affect
                            variables that are used in a FUNCTION but
                            declared outside the FUNCTION in DIM or COMMON
                            statements by use of the SHARED attribute.

    expression               The return value of the function. A FUNCTION
                            returns a value by assigning a value to the
                            function name. If no value is assigned to the
                            FUNCTION name, the FUNCTION returns a default
                            value: a numeric function returns a value of
                            zero, and a string function returns the null
                            string ("").
    ──────────────────────────────────────────────────────────────────────────


    A parameterlist has the following syntax:
    variable«( )»« AS type»«, variable«( )»« AS type»...»

    A variable is any valid BASIC variable. The optional type can be either
    INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type.

    Earlier versions of BASIC required the number of dimensions in parentheses
    after an array name. The number of dimensions is no longer required. Only
    the parentheses are required to indicate the parameter is an array. For
    example, the following statement indicates that both Keywords$ and
    KeywordTypes are arrays:

    FUNCTION ParseLine(Keywords$(),KeywordTypes())

    A FUNCTION procedure is like a SUB procedure: it can accept parameters,
    perform a series of statements, and change the values of its parameters.
    Unlike a SUB, a FUNCTION is used in an expression in the same manner as a
    BASIC intrinsic function.

    Like SUB procedures, FUNCTION procedures use local variables. Any variable
    not in the parameter list is local to the FUNCTION unless it is declared
    as a shared variable in a SHARED statement, or unless the variable appears
    in a DIM or COMMON statement with the SHARED attribute.

    To return a value from a function, assign the value to the function name.
    For example, in a function named BinarySearch, you might assign the value
    of the constant FALSE to the name to indicate the value was not found:

    FUNCTION BinarySearch(...)
    CONST FALSE=0
    .
    .
    .

    ' Value not found. Return a value of FALSE.

        IF Lower>Upper THEN
        BinarySearch=FALSE
        EXIT FUNCTION
        END IF
    .
    .
    .
    END FUNCTION

    Using the STATIC keyword slightly increases execution speed. STATIC is not
    usually used with recursive FUNCTION procedures. See the examples below.

    The EXIT FUNCTION statement provides an alternative exit from a FUNCTION.
    See the EXIT statement.

    Because BASIC may rearrange arithmetic expressions to attain greater
    efficiency, avoid using FUNCTION procedures that change program variables
    in arithmetic expressions. Also avoid using FUNCTION procedures that
    perform I/O in I/O statements.

    QuickBASIC FUNCTION procedures are recursive──they can call themselves to
    perform a given task. See the second example below and Chapter 4,
    "Programs and Modules."

■ See Also

    DECLARE (BASIC), DEF FN, EXIT, STATIC, SUB

■ Examples

    The following example uses a function to count the number of vowels in a
    string:

    ' Function definition.
    FUNCTION NumVowels (A$) STATIC
        Num = 0
        ' Go through A$ a character at a time.
        FOR I = 1 TO LEN (A$)
        C$ = UCASE$ (MID$(A$,I,1))
        IF INSTR ("AEIOU",C$)<> 0 THEN
            ' Find a vowel--count it.
            Num = Num + 1
        END IF
        NEXT I
        NumVowels = Num
    END FUNCTION

    A$ = "The ultimate answer to the ultimate question is 42"
    PRINT CHR$(34)+A$+CHR$(34)
    PRINT "The number of vowels in the string is :";NumVowels (A$)

■ Output

    "The ultimate answer to the ultimate question is 42"
    The number of vowels in the string is : 18

    The following example uses a recursive function (a function that calls
    itself) to find the length of a string. Notice that the STATIC keyword is
    not used.

    FUNCTION StrLen(X$)
        IF X$ = "" THEN
        ' The length of a null string is zero.
        StrLen=0
        ELSE
        ' Non-null string--make a recursive call.
        ' The length of a non-null string is 1
        ' plus the length of the rest of the string.
        StrLen=1+StrLen(MID$(X$,2))
        END IF
    END FUNCTION

    LINE INPUT "Enter a string: ",InString$
    PRINT "The string length is"; StrLen(InString$)

■ Output

    Enter a string: Once upon a time
    The string length is 16


────────────────────────────────────────────────────────────────────────────
GET Statement──Graphics
────────────────────────────────────────────────────────────────────────────

■ Action

    Stores graphic images from the screen

■ Syntax

    GET «STEP»(x1,y1) - «STEP»(x2,y2),arrayname«(indices)»

■ Remarks

    The list below describes the parts of the GET statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    x1,y1,x2,y2              Coordinates marking a rectangular area on the
                            screen. The placeholders x1, y1, x2, and y2 are
                            numeric expressions that are the coordinates of
                            diagonally opposite corners of the rectangle.

    STEP                     Keyword indicating that coordinates are relative
                            to the most recently plotted point. For example,
                            if the last point plotted were (10,10), then the
                            actual coordinates referred to by STEP (5,10)
                            would be (5+10,10+10) or (15,20). If the second
                            coordinate pair in a GET statement has a STEP
                            argument, it is relative to the first coordinate
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            argument, it is relative to the first coordinate
                            pair in the statement.

    arrayname                Name assigned to the array that holds the image.
                            This array can be of any numeric type; its
                            dimensions must be large enough to hold the
                            entire image.

    indices                  Numeric constants or variables indicating the
                            element of the array where the saved image
                            starts.
    ──────────────────────────────────────────────────────────────────────────


    The GET statement transfers a screen image into the array specified by
    arrayname. The PUT statement, associated with GET, transfers the image
    stored in the array onto the screen.

    The following formula gives the required size of the array in bytes:

    4 + INT(((x2 - x1 + 1) * (bits-per-pixel-per-plane) + 7)/8) * planes *
    ((y2 - y1) + 1)

    The bits-per-pixel-per-plane and planes values depend on the specification
    set in the SCREEN statement. Table R.3 shows the number of bits per pixel
    per plane and the number of planes for each screen mode.

    Table R.3   Values for Bits per Pixel per Plane and for Planes

╓┌─┌────────────────────────┌───────────────────────┌────────────────────────╖
                            Bits per Pixel
    Screen Mode              per Plane               Planes
    ──────────────────────────────────────────────────────────────────────────
    1                        2                       1

    2                        1                       1

    7                        1                       4

    8                        1                       4
                            Bits per Pixel
    Screen Mode              per Plane               Planes
    ──────────────────────────────────────────────────────────────────────────
    8                        1                       4

    9                        1                       2 (if 64K of EGA memory)

                                                    4 (if > 64K EGA memory)

    10                       1                       2

    11                       1                       1

    12                       1                       4

    13                       8                       1
    ──────────────────────────────────────────────────────────────────────────


    The bytes per element of an array are as follows:

    ■ Two bytes for an integer array element

    ■ Four bytes for a long-integer array element

    ■ Four bytes for a single-precision array element

    ■ Eight bytes for a double-precision array element

    For example, suppose you wanted to use the GET statement to store an image
    in high resolution (SCREEN 2). If the coordinates of the upper-left corner
    of the image are (0,0), and the coordinates of the lower- right corner are
    (32,32), then the required size of the array in bytes is 4 + INT((33 * 1 +
    7)/8) * 1 * (33), or 169. This means an integer array with 85 elements
    would be large enough to hold the image.

    Unless the array type is integer or long, the contents of an array after a
    GET appear meaningless when inspected directly. Examining or manipulating
    noninteger arrays containing graphics images may cause run-time errors.

    One of the most useful things that can be done with GET and PUT is
    animation. See Chapter 5, "Graphics," in Programming in BASIC for a
    discussion of animation.

■ See Also

    PUT (Graphics)

■ Example

    See the example for BSAVE.


────────────────────────────────────────────────────────────────────────────
GET Statement──File I/O
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads from a disk file into a random-access buffer or variable

■ Syntax

    GET «#»filenumber«,«recordnumber»«,variable»»

■ Remarks

    The following list describes the GET statement's arguments:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filenumber               The number used in the OPEN statement to open the
                            file.

    recordnumber             For random-access files, the number of the record
                            to be read. For binary-mode files, the byte
                            position in the file where reading starts. The
                            first record or byte position in a file is 1. If
                            you omit recordnumber, the next record or byte
                            (the one after the last GET or PUT, or the one
                            pointed to by the last SEEK) is read into the
                            buffer. The largest possible record number is
                            2^31-1, or 2,147,483,647.
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            2^31-1, or 2,147,483,647.

    variable                 The variable used to receive input from the file.
                            If you use a variable, you do not need to use
                            CVD, CVL, CVI, or CVS to convert record fields to
                            numbers. You may not use a FIELD statement with
                            the file if you use the variable argument.

                            For random-access files, you can use any variable
                            as long as the length of the variable is less
                            than or equal to the length of the record.
                            Usually, a record variable defined to match the
                            fields in a data record is used. For binary-mode
                            files, you can use any variable. The GET
                            statement reads as many bytes as there are in the
                            variable.

                            When you use a variable-length string variable,
                            the statement reads as many bytes as there are
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            the statement reads as many bytes as there are
                            characters in the string's value. For example,
                            the following two statements read 10 bytes from
                            file number 1:

                            VarStrings$=STRING$ (10, " ")

                            GET #1,,VarString$

                            See the examples and Chapter 3, "File and Device
                            I/O," in Programming in BASIC for more
                            information about using variables rather than
                            FIELD statements for random-access files. A
                            record cannot be longer than 32,767 bytes.
    ──────────────────────────────────────────────────────────────────────────


    You may omit the recordnumber, the variable, or both. If you omit the
    recordnumber but include the variable, you must still include the commas:

    GET #4,,FileBuffer

    If you omit both arguments, you do not include the commas:

    GET #4

    The GET and PUT statements allow fixed-length input and output for BASIC
    communications files. Use GET carefully because if there is a
    communications failure, GET waits indefinitely for recordnumber
    characters.

────────────────────────────────────────────────────────────────────────────
NOTE
    When you use GET with the FIELD statement, you can use either INPUT # or
    LINE INPUT # after a GET statement to read characters from the
    random-access file buffer. You may use the EOF function after GET to see
    if the GET went beyond the end of the file.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CVI, CVS, CVL, CVD; FIELD; INPUT #;
    LINE INPUT #; LSET; MKD$, MKI$, MKL$, MKS$;
    PUT (File I/O); RSET; TYPE

■ Example

    The following program opens the file TESTDAT.DAT for random access and
    displays the contents on the screen:

    '  Read and display the contents of a file containing a
    '  name of up to 20 characters and a test score.

    '  Define record fields.
    TYPE TestRecord
        NameField  AS STRING*20
        ScoreField AS SINGLE
    END TYPE

    '  Open the test data file.
    DIM FileBuffer AS TestRecord
    OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(FileBuffer)

    '  Calculate number of records in the file.
    Max=LOF(1)/LEN(FileBuffer)

    '  Read and print contents of each record.
    FOR I=1 TO Max
        GET #1,I,FileBuffer
        PRINT FileBuffer.NameField,FileBuffer.ScoreField
    NEXT I

    CLOSE #1


────────────────────────────────────────────────────────────────────────────
GOSUB...RETURN Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Branches to, and returns from, a subroutine

■ Syntax

    GOSUB {linelabel1 | linenumber1 }
    .
    .
    .
    RETURN «linelabel2 | linenumber2 »

■ Remarks

    The GOSUB...RETURN statements take the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    linelabel1, linenumber1  The line number or line label that is the first
                            line of the subroutine.

    linelabel2, linenumber2  The line label or line number where the
                            subroutine returns.
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    BASIC's SUB and FUNCTION procedures provide a more well-structured
    alternative to GOSUB... RETURN subroutines.
────────────────────────────────────────────────────────────────────────────

    In addition to RETURN with no argument, BASIC supports RETURN with a line
    label or line number allowing a return from a subroutine to the statement
    having the specified line number or label, instead of returning to the
    statement after the GOSUB statement. Use this line-specific type of return
    with care.

    You may call a subroutine any number of times in a program. You may also
    call a subroutine from within another subroutine. How deeply you can nest
    subroutines is limited only by the available stack space (you may increase
    the stack space with the CLEAR statement). Subroutines that call
    themselves (recursive subroutines) can easily run out of stack space.
    RETURN with a line label or line number can only return control to a
    statement in the module-level code, not procedure-level code. See the
    example program.

    A subroutine may contain more than one RETURN statement. Simple RETURN
    statements (without the linelabel2, linenumber2 option) in a subroutine
    make BASIC branch back to the statement following the most recent GOSUB
    statement.

    Subroutines may appear anywhere in the program, but it is good programming
    practice to make them readily distinguishable from the main program. To
    prevent inadvertent entry into a subroutine, precede it with a STOP, END,
    or GOTO statement that directs program control around the subroutine.

────────────────────────────────────────────────────────────────────────────
IMPORTANT
    The preceding discussion of subroutines applies only to the targets of
    GOSUB statements, not subprograms delimited by SUB statements. Entering
    and exiting SUB blocks with GOSUB...RETURN statements is not supported.
────────────────────────────────────────────────────────────────────────────

■ See Also

    RETURN, SUB

■ Example

    The following example shows the use of RETURN linelabel statements in
    module-level code:

    PRINT "in module-level code"
    GOSUB Sub1
    PRINT "this line in main routine should be skipped"
    Label1:
        PRINT "back in module-level code"
        END

    Sub1:
        PRINT "in subroutine one"
        GOSUB Sub2
        PRINT "this line in subroutine one should be skipped"
    Label2:
        PRINT "back in subroutine one"
        RETURN Label1

    Sub2:
        PRINT "in subroutine two"
        RETURN Label2

■ Output

    in module-level code
    in subroutine one
    in subroutine two
    back in subroutine one
    back in module-level code


────────────────────────────────────────────────────────────────────────────
GOTO Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Branches unconditionally to the specified line

■ Syntax

    GOTO {linelabel | linenumber}

■ Remarks

    The GOTO statement provides a way to branch unconditionally to another
    line (linelabel or linenumber). A GOTO statement can branch only to
    another statement at the same level of a program. You cannot use GOTO to
    enter or exit a SUB, FUNCTION, or multiline DEF FN function. You can,
    however, use GOTO to control program flow within any of these program
    structures.

    It is good programming practice to use structured control statements
    (DO...LOOP, FOR, IF..THEN...ELSE, SELECT CASE) instead of GOTO statements
    because a program with many GOTO statements is difficult to read and
    debug.

■ Example

    The following program prints the area of the circle with the input radius:

    PRINT "Input 0 to end."
    Start:
        INPUT R
        IF R = 0 THEN
        END
        ELSE
        A = 3.14 * R^2
        PRINT "Area =";A
        END IF
    GOTO Start

■ Output

    Input 0 to end.
    ? 5
    Area = 78.5
    ? 0


────────────────────────────────────────────────────────────────────────────
HEX$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string that represents the hexadecimal value of the decimal
    argument expression

■ Syntax

    HEX$(expression)

■ Remarks

    The argument expression is rounded to an integer or, if the expression is
    outside the integer range, a long integer before the HEX$ function
    evaluates it.

■ See Also

    OCT$

■ Example

    The following example prints the hexadecimal representation of an input
    value:

    INPUT X
    A$ = HEX$(X)
    PRINT X "decimal is " A$ " hexadecimal"

■ Output

    ? 32
    32 decimal is 20 hexadecimal









────────────────────────────────────────────────────────────────────────────
IF...THEN...ELSE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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
        «statementblock-n»»
    END IF

■ Remarks

    The single-line form of the statement is best used for short,
    straightforward tests where only one action is taken.

    The block form provides several advantages:

    ■ The block form provides more structure and flexibility than the
    single-line form by allowing conditional branches across several lines.

    ■ With the block form, more complex conditions can be tested.

    ■ The block form lets you use longer statements and structures within the
    THEN...ELSE portion of the statement.

    ■ The block form allows your program's structure to be guided by logic
    rather than by how many statements fit on a line.

    Programs that use block-form IF...THEN...ELSE are usually easier to read,
    maintain, and debug.

    The single-line form is never required. Any program using single-line
    IF...THEN...ELSE statements can be written using block form.

    SINGLE-LINE IF...THEN...ELSE

    The following list describes the parts of the single-line form:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    booleanexpression        Any expression that evaluates to true (nonzero)
                            or false (zero).

    thenpart, elsepart       The statements or branches performed when
                            booleanexpression is true (thenpart) or false
                            (elsepart). Both parts have the same syntax,
                            which is described below.
    ──────────────────────────────────────────────────────────────────────────

    The thenpart and the elsepart both have the following syntax:

    {statements | «GOTO» linenumber | GOTO linelabel }

    The following list describes the parts of the thenpart and elsepart
    syntax:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    statements               One or more BASIC statements, separated by colons

    linenumber               A valid BASIC program line number

    linelabel                A valid BASIC line label
    ──────────────────────────────────────────────────────────────────────────

    Note that GOTO is optional with a line number but is required with a line
    label.

    The thenpart is executed if the booleanexpression is true; if the
    booleanexpression is false, the elsepart is executed. If the ELSE clause
    is not present, control passes to the next statement in the program.

    You can have multiple statements with a condition, but they must be on the
    same line and separated by colons:

    IF A > 10 THEN A=A+1:B=B+A:LOCATE 10,22:PRINT B,A

    BLOCK IF...THEN...ELSE

    The following list describes the parts of the block IF...THEN...ELSE:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    booleanexpression1,      Any expression that evaluates to true (nonzero)
    booleanexpression2       or false (zero)

    statementblock-1,        One or more BASIC statements on one or more lines
    statementblock-2,
    statementblock-n
    ──────────────────────────────────────────────────────────────────────────

    In executing a block-form IF, QuickBASIC tests booleanexpression1, the
    first Boolean expression. If the Boolean expression is true (nonzero), the
    statements following THEN are executed. If the first Boolean expression is
    false (zero), QuickBASIC begins evaluating each ELSEIF condition in turn.
    When QuickBASIC finds a true condition, the statements following the
    associated THEN are executed. If none of the ELSEIF conditions are true,
    the statements following the ELSE are executed. After the statements
    following a THEN or ELSE are executed, the program continues with the
    statement following the END IF.

    The ELSE and ELSEIF blocks are both optional. You can have as many ELSEIF
    clauses as you would like in a block IF. Any of the statement blocks can
    contain nested block IF statements.

    QuickBASIC looks at what appears after the THEN keyword to determine
    whether or not an IF statement is a block IF. If anything other than a
    comment appears after THEN, the statement is treated as a single-line IF
    statement.

    A block IF statement must be the first statement on a line. The ELSE,
    ELSEIF, and END IF parts of the statement can only have a line number or
    line label in front of them. The block must end with an END IF statement.

    For more information, see Chapter 1, "Control-Flow Structures," in
    Programming in BASIC.

■ See Also

    SELECT CASE

■ Examples

    The following program fragments demonstrate the use of single-line and
    block IF...THEN...ELSE and illustrate the differences. The first example
    demonstrates the single-line IF...THEN...ELSE form:

    DO
    INPUT "Enter a number greater than 0 and less than 10,000:",X
    IF X>=0 AND X<10000 THEN EXIT DO ELSE PRINT X;"out of range"
    LOOP
    IF X<10 THEN Y=1 ELSE IF X<100 THEN Y=2 ELSE IF X<1000 THEN Y=3 ELSE
    Y=4
    PRINT "The number has";Y;"digits"

    In the second example the block IF...THEN...ELSE makes the code more
    readable and more powerful:

    DO
        INPUT "Enter a number greater than 0 and less than 100,000:",X
        IF X>0 AND X<100000 THEN
        EXIT DO
        ELSE
        PRINT X;"out of range"
        END IF
    LOOP
    IF X<10 THEN
        Y=1
    ELSEIF X<100 THEN
        Y=2
    ELSEIF X<1000 THEN
        Y=3
    ELSEIF X<10000 THEN
        Y=4
    ELSE
        Y=5
    END IF
    PRINT "The number has";Y;"digits"


────────────────────────────────────────────────────────────────────────────
INKEY$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads a character from the keyboard

■ Syntax

    INKEY$

■ Remarks

    The INKEY$ function returns a one- or two-byte string containing a
    character read from the standard input device. A null string is returned
    if no character is waiting there. A one-character string contains the
    actual character read from the keyboard, while a two-character string
    indicates an extended code, the first character of which is hexadecimal
    00. For a complete list of these codes, see Appendix A, "Keyboard Scan
    Codes and ASCII Character Codes."

    The standard input device is usually the keyboard. INKEY$ does not echo
    characters to the screen; instead, all characters are passed through to
    the program except for these:

    ■ CTRL+BREAK, which halts program execution

    ■ CTRL+ALT+DEL, which does a system reboot

    ■ CTRL+NUMLOCK, which causes program execution to pause

    ■ PRTSC, which prints the screen

■ Example

    The following program fragment shows a common use of INKEY$──pausing until
    the user presses a key:

    PRINT "Press any key to continue..."
    DO
    LOOP WHILE INKEY$=""


────────────────────────────────────────────────────────────────────────────
INP Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the byte read from an I/O port

■ Syntax

    INP(port)

■ Remarks

    The port must be an integer in the range 0-65,535. The INP function
    complements the OUT statement.

    The INP and OUT statements give a BASIC program direct control over the
    hardware in a system through the I/O ports. These statements must be used
    carefully because they directly manipulate the system hardware.

■ See Also

    OUT, WAIT

■ Example

    See the example for the OUT statement.


────────────────────────────────────────────────────────────────────────────
INPUT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Allows input from the keyboard during program execution

■ Syntax

    INPUT«;»«"promptstring"{; | ,}» variablelist

■ Remarks

    The following list describes the parts of the INPUT statement:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    ;                        A semicolon immediately after INPUT keeps the
                            cursor on the same line after the user presses
                            ENTER.

    promptstring             A string constant printed before the prompt
                            character.

    ;                        Prints a question mark at the end of the
                            promptstring.

    ,                        Prints the promptstring without a question mark.

    variablelist             A list of variables, separated by commas, to
                            accept the input values. See the discussion
                            below.
    ──────────────────────────────────────────────────────────────────────────

    The INPUT statement causes the program to pause and wait for data. You can
    then enter the required data at the keyboard.

    The data that you enter is assigned to the variables in variablelist. The
    number of data items that you supply must be the same as the number of
    variables in the list. The first character encountered after a comma that
    is not a space, carriage return, or line feed is assumed to be the start
    of a new item.

    The variable names in the list may be numeric- or string-variable names
    (including subscripted variables), array elements, or elements of records.
    The type of each data item that you input must agree with the type of the
    variable. (Strings input to an INPUT statement need not be surrounded by
    quotation marks.) If this first character is a quotation mark ("), the
    string item will consist of all characters read between the first
    quotation mark and the second. This means a quoted string may not contain
    a quotation mark as a character. If the first character of the string is
    not a quotation mark, the string is an unquoted string and terminates on a
    comma, carriage return, or line feed.

    Input stored in elements of a record must be input as single elements:

    TYPE Demograph
        FullName AS STRING*25
        Age  AS INTEGER
    END TYPE

    DIM Person AS Demograph
    INPUT "Enter name and age: ";Person.FullName,Person.Age

    Responding to an INPUT statement with too many or too few items, or with
    the wrong type of value (for example, numeric instead of string), produces
    this error message:

    Redo from start

    No assignment of input values is made until you give an acceptable
    response.

    It is possible to edit a line of input before you press ENTER. The
    following list describes the key combinations that allow you to move the
    cursor, delete text, and insert text on the input line:


╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Keys                     Action
    ──────────────────────────────────────────────────────────────────────────
    CTRL+\ or RIGHT          Moves cursor one character to the right.

    Keys                     Action
    ──────────────────────────────────────────────────────────────────────────

    CTRL+] or LEFT           Moves cursor one character to the left.

    CTRL+F or CTRL+RIGHT     Moves cursor one word to the right.

    CTRL+B or CTRL+LEFT      Moves cursor one word to the left.

    CTRL+K or HOME           Moves cursor to the beginning of the input line.

    CTRL+N or END            Moves cursor to the end of the input line.

    CTRL+R or INS            Toggles insert mode on and off. When insert mode
                            is on, character above and those to the right of
                            the cursor are shifted to the right as new
                            characters are entered.

    CTRL+I or TAB            Tabs right and inserts (insert mode on), or
                            overwrites (insert mode off).

    Keys                     Action
    ──────────────────────────────────────────────────────────────────────────

    DEL                      Deletes the character at the cursor.

    CTRL+H or BACKSPACE      Deletes the character to the left of the cursor,
                            unless the cursor is at the beginning of the
                            input, in which case it deletes the character at
                            the cursor.

    CTRL+E or CTRL+END       Deletes to the end of the line.

    CTRL+U or ESC            Deletes entire line, regardless of cursor
                            position.

    CTRL+M or RETURN         Stores input line.

    CTRL+T                   Toggles function key label display on and off at
                            bottom of screen.

    CTRL+BREAK or CTRL+C     Terminates input (exits compiled program).
    Keys                     Action
    ──────────────────────────────────────────────────────────────────────────
    CTRL+BREAK or CTRL+C     Terminates input (exits compiled program).
    ──────────────────────────────────────────────────────────────────────────


■ Example

    The following example calculates the area of a circle from an input
    radius:

    PI = 3.141593 : R = -1
    PRINT "Enter radius (0 to end)."
    DO WHILE R
        PRINT
        INPUT;"If radius = ", R
        IF R > 0 THEN
            A = PI*R^2
            PRINT ", the area of the circle =" A
        END IF
    LOOP

■ Output

    Enter radius (0 to end).

    If radius = 3, the area of the circle = 28.27434

    If radius = 4, the area of the circle = 50.26549

    If radius = 0


────────────────────────────────────────────────────────────────────────────
INPUT # Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads data items from a sequential device or file and assigns them to
    variables

■ Syntax

    INPUT #filenumber, variablelist

■ Remarks

    The filenumber is the number used when the file was opened for input. The
    variablelist contains the names of the variables that are assigned values
    read from the file. (The variable type must match the type specified by
    the variable name.)

    The data items in the file should appear just as they would if you were
    entering data in response to an INPUT statement. Separate numbers with a
    space, carriage return, line feed, or comma. Separate strings with a
    carriage return or linefeed (leading spaces are ignored). The end-of-file
    character will end either a numeric or string entry.

    If BASIC is scanning the sequential data file for a string item, it will
    also ignore leading spaces, carriage returns, and line feeds. If
    end-of-file is reached when a numeric or string item is being INPUT, the
    item is terminated.

■ See Also

    INPUT, INPUT$

■ Example

    The following program reads a series of test scores from a sequential file
    and calculates the average score:

    DEFINT A-Z

    OPEN "class.dat" FOR INPUT AS #1

    DO WHILE NOT EOF(1)
        Count=Count+1
        INPUT #1,Score
        Total=Total+Score
        PRINT Count;Score
    LOOP
    PRINT
    PRINT "Total students:";Count;" Average score:";Total/Count

    END

■ Output

    1  97
    2  84
    3  63
    4  89
    5  100

    Total students: 5  Average score: 86.6


────────────────────────────────────────────────────────────────────────────
INPUT$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string of characters read from the specified file

■ Syntax

    INPUT$(n«,«#»filenumber»)

■ Remarks

    The n is the number of characters (bytes) to read from the file. The
    filenumber is the number that was used in opening the file.

    If the file is opened for random access, the argument n must be less than
    or equal to the record length set by the LEN clause in the OPEN statement
    (or less than or equal to 128 if the record length is not set). If the
    given file is opened for binary or sequential access, then n must be less
    than or equal to 32,767.

    If the filenumber is not specified, the characters are read from the
    standard input device. (If input has not been redirected, the keyboard is
    the standard input device).

    You can use the DOS redirection symbols (<, >, or >>) or the pipe symbol
    (|) to redefine the standard input or standard output for an executable
    file created with BASIC. (See your operating system manual for a complete
    discussion of redirection and pipes.)

    No characters are echoed on the screen. All control characters are passed
    through except CTRL+BREAK, which interrupts execution of the function.

■ Example

    The following program prints a file on the screen. It uses INPUT$ to read
    one character at a time, then converts the character, as necessary, and
    displays it.

    'ASCII codes for tab, and line feed.
    CONST HTAB = 9, LFEED = 10

    INPUT "Display which file"; Filename$
    OPEN Filename$ FOR INPUT AS #1
    CLS
    DO WHILE NOT EOF(1)

        ' Input a single character from the file.
        S$=INPUT$(1,#1)
        ' Convert the character to an integer and
        ' turn off the high bit so WordStar(R) files
        ' can be displayed.
        C=ASC(S$) AND &H7F
        ' Is it a printable character?
        IF (C >= 32 AND C <= 126) OR C = HTAB OR C = LFEED THEN
            PRINT CHR$(C);
        END IF

    LOOP
    END


────────────────────────────────────────────────────────────────────────────
INSTR Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the character position of the first occurrence of a string in
    another string

■ Syntax

    INSTR(«start,»stringexpression1,stringexpression2)

■ Remarks

    The following list describes the INSTR function arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    start                    An optional offset that sets the position for
                            starting the search; start must be in the range
                            1-32,767. If start is not given, the INSTR
                            function begins the search at the first character
                            of stringexpression1.

    stringexpression1        The string being searched.

    stringexpression2        The string to look for.
    ──────────────────────────────────────────────────────────────────────────

    The arguments stringexpression1 and stringexpression2 can be string
    variables, string expressions, or string literals. The value returned by
    INSTR depends on these conditions:

    Condition                            Value Returned
    ──────────────────────────────────────────────────────────────────────────
    stringexpression2 found in           The position at which the match is
    stringexpression1                    found

    start greater than length of         0
    stringexpression1
    stringexpression1 is null string     0

    stringexpression2 cannot be found    0

    stringexpression2 is null string     start (if given); otherwise, 1
    ──────────────────────────────────────────────────────────────────────────

    Use the LEN function to find the length of stringexpression1.

■ Example

    The following fragment uses INSTR and UCASE$ to look for Mr., Mrs., or Ms.
    in a name in order to deduce the person's sex:

    ' Get a name.
    DO
        INPUT "Enter name: ", Nm$
    LOOP UNTIL LEN(Nm$)>=3

    ' Convert lowercase letters to uppercase.
    Nm$ = UCASE$(Nm$)

    ' Look for MS., MRS., or MR. to set Sex$.
    IF INSTR(Nm$,"MS.") > 0 OR INSTR(Nm$,"MRS.") > 0 THEN
        Sex$ = "F"
    ELSEIF INSTR(Nm$,"MR.") > 0 THEN
        Sex$ = "M"
    ELSE
        ' Can't deduce sex, so query user.
        DO
            INPUT "Enter sex (M/F): ", Sex$
            Sex$ = UCASE$(Sex$)
        LOOP WHILE Sex$ <> "M" AND Sex$ <> "F"
    END IF

■ Output

    Enter name: Elspeth Brandtkeep
    Enter sex (M/F): x
    Enter sex (M/F): F


────────────────────────────────────────────────────────────────────────────
INT Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the largest integer less than or equal to numeric-expression

■ Syntax

    INT(numeric-expression)

■ Remarks

    The INT function removes the fractional part of its argument.

■ See Also

    CINT, FIX

■ Example

    The following example compares the output from the three functions that
    convert numeric data to integers:

    PRINT "  N","INT(N)","CINT(N)","FIX(N)" : PRINT
    FOR I% = 1 TO 6
        READ N
        PRINT N, INT(N), CINT(N), FIX(N)
    NEXT
    DATA  99.3, 99.5, 99.7, -99.3, -99.5, -99.7

■ Output

    N           INT(N)        CINT(N)       FIX(N)

    99.3          99            99            99
    99.5          99            100           99
    99.7          99            100           99
    -99.3         -100          -99           -99
    -99.5         -100          -100          -99
    -99.7         -100          -100          -99


────────────────────────────────────────────────────────────────────────────
IOCTL$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Receives a control data string from a device driver

■ Syntax

    IOCTL$ («#» filenumber)

■ Remarks

    The filenumber is the BASIC file number used to open the device. The
    IOCTL$ function is most frequently used to test whether an IOCTL statement
    succeeded or failed or to obtain current status information.

    You could use IOCTL$ to ask a communications device to return the current
    baud rate, information on the last error, logical line width, and so on.
    The exact information returned would depend on the specific device driver.

    The IOCTL$ function works only if all three of the following conditions
    are met:

    1. The device driver is installed.

    2. The device driver states that it processes IOCTL strings. See the
        documentation for the driver. You can also test for IOCTL support
        through DOS function &H44 by using interrupt &H21 and the CALL
        INTERRUPT routine. See the CALL INTERRUPT statement for more
        information.

    3. BASIC performs an OPEN statement on a file on that device.

────────────────────────────────────────────────────────────────────────────
NOTE
    BASIC devices (LPT1:, COM1:, COM2:, SCRN:, CONS:) and DOS block devices
    (A: through Z:) do not support IOCTL.
────────────────────────────────────────────────────────────────────────────

■ See Also

    IOCTL

■ Example

    The following example opens the device driver ENGINE and uses the IOCTL$
    function to test for raw data mode being set:

    OPEN "\DEV\ENGINE" FOR OUTPUT AS #1
    IOCTL #1, "RAW"     'Tells the device that the data is raw.
    ' If the character driver "ENGINE" responds "false" from
    ' the raw data mode in the IOCTL statement, then the file
    ' is closed.
    IF IOCTL$(1) = "0" THEN CLOSE 1


────────────────────────────────────────────────────────────────────────────
IOCTL Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Transmits a control data string to a device driver

■ Syntax

    IOCTL «#»filenumber, string

■ Remarks

    The filenumber is the BASIC file number used to open the device. The
    string is the command sent to the device. Commands are specific to the
    device driver. See the documentation for the device driver to find out
    what the valid IOCTL commands are. An IOCTL control data string can be up
    to 32,767 bytes long.

    The IOCTL statement works only if all three of the following conditions
    are met:

    1. The device driver is installed.

    2. The device driver states that it processes IOCTL strings. See the
        documentation for the driver. You can also test for IOCTL support
        through DOS function &H44 by using interrupt &H21 and the CALL
        INTERRUPT routine. See the Microsoft MS-DOS Programmer's Reference and
        the CALL INTERRUPT statement for more information.

    3. BASIC performs an OPEN on a file on that device, and the file is still
        open.

    Most standard DOS device drivers do not process IOCTL strings, and you
    must determine if the specific driver accepts the command.

■ See Also

    IOCTL$

■ Example

    If you wanted to set the page length to 66 lines per page on LPT1, your
    statement might look like this:

    OPEN "\DEV\LPT1" FOR OUTPUT AS 1
    IOCTL #1, "PL66"


────────────────────────────────────────────────────────────────────────────
KEY Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    The placeholder n is a number representing the FUNCTION key. The values
    for n are 1 to 10 for the FUNCTION keys, and 30 and 31 for FUNCTION keys
    F11 and F12 on 101-key keyboards. The stringexpression is a string of up
    to 15 characters that is returned when the FUNCTION key is pressed. If the
    stringexpression is longer than 15 characters, the extra characters are
    ignored.

    The KEY statement allows you to designate special "soft-key"
    functions──strings that are returned when FUNCTION keys are pressed.

    Assigning a null string to a soft key disables the FUNCTION key as a soft
    key.

    If the FUNCTION key number is not in the correct range, an error message
    is displayed that reads Illegal function call, and the previous key string
    expression is retained.

    You may display soft keys with the KEY ON, KEY OFF, and KEY LIST
    statements:

    Statement                Action
    ──────────────────────────────────────────────────────────────────────────
    KEY ON                   Displays the first six characters of the soft-key
                            string values on the bottom line of the screen.

    KEY OFF                  Erases the soft-key display from the bottom line,
                            making that line available for program use. It
                            does not disable the FUNCTION keys.

    KEY LIST                 Displays all soft-key values on the screen, with
                            all 15 characters of each key displayed.
    ──────────────────────────────────────────────────────────────────────────

    If a soft key is pressed, the effect is the same as if the user typed the
    string associated with the soft key. INPUT$, INPUT, and INKEY$ can all be
    used to read the string produced by pressing the soft key.

■ Examples

    The following examples show how to assign a string to a soft key and how
    to disable a soft key:

    KEY 1,"MENU"+CHR$(13)  'Assigns to soft key 1 the string
                            '"MENU" followed by a carriage return.

    KEY 1,""
    'Disables soft key 1.

    The following program uses KEY statements to set up one-key equivalents of
    menu selections. For example, pressing F1 is the same as entering the
    string Add:

    DIM KeyText$(3)
    DATA Add, Delete, Quit
    ' Assign soft-key strings to F1 to F3.
    FOR I=1 TO 3
        READ KeyText$(I)
        KEY I, KeyText$(I)+CHR$(13)
    NEXT I
    ' Print menu.
    PRINT "                 Main Menu" : PRINT
    PRINT "           Add to list (F1)"
    PRINT "           Delete from list (F2)"
    PRINT "           Quit (F3)" : PRINT
    ' Get input and respond.
    DO
        LOCATE 7,1 : PRINT SPACE$(50);
        LOCATE 7,1 : INPUT "             Enter your choice:",R$
        SELECT CASE R$
        CASE "Add", "Delete"
            LOCATE 10,1 : PRINT SPACE$(15);
            LOCATE 10,1 : PRINT R$;
        CASE "Quit"
            EXIT DO
        CASE ELSE
            LOCATE 10,1 : PRINT "Enter first word or press key."
        END SELECT
    LOOP


────────────────────────────────────────────────────────────────────────────
KEY (n) Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Start or stop trapping of specified keys

■ Syntax

    KEY(n) ON
    KEY(n) OFF
    KEY(n) STOP

■ Remarks

    The argument n is the number of a FUNCTION key, a cursor-direction key, or
    a user-defined key. (See the KEY statement for information on assigning
    soft-key values to FUNCTION keys.) The values of n are as follows:

    Value                    Key
    ──────────────────────────────────────────────────────────────────────────
    1-10                     The FUNCTION keys F1-F10
    11                       UP
    12                       LEFT
    13                       RIGHT
    14                       DOWN
    15-25                    User-defined keys
    30-31                    The FUNCTION keys F11-F12 on 101-key keyboards
    ──────────────────────────────────────────────────────────────────────────

    LEFT, RIGHT, UP, and DOWN refer to the direction keys.

    You can enable trapping of combination keys by using a variation of the
    KEY statement:

    KEY n, CHR$(keyboardflag) + CHR$(scancode)

    The argument n is in the range 15-25 to indicate a user-defined key. The
    keyboardflag can be any combination of the following hexadecimal values:

    Value                    Key
    ──────────────────────────────────────────────────────────────────────────
    &H00                     No keyboard flag
    &H01-&H03                Either SHIFT key
    &H04                     CTRL
    &H08                     ALT
    &H20                     NUMLOCK
    &H40                     CAPSLOCK
    &H80                     101-key keyboard extended keys
    ──────────────────────────────────────────────────────────────────────────

    You can add the values together to test for multiple shift states. A
    keyboardflag value of &H12 would test for both CTRL and ALT being pressed,
    for example.

    Because key trapping assumes the left and right SHIFT keys are the same,
    you can use either &H01, &H02, or &H03 to indicate a SHIFT key. The
    scancode argument is a number identifying one of the 83 keys to trap, as
    shown in Table R.4.

    Table R.4   Keyboard Scan Codes


╓┌─┌───────────┌────────────┌───────────┌───────────┌────────────┌───────────╖
                Code                     Code                     Code
    Key         in Hex       Key         in Hex      Key          in Hex
    ──────────────────────────────────────────────────────────────────────────
    ESC         01           CTRL        1D          SPACEBAR     39
    ! or 1      02           A           1E          CAPS LOCK    3A
    # or 3      04           D           20          F2           3C
                Code                     Code                     Code
    Key         in Hex       Key         in Hex      Key          in Hex
    ──────────────────────────────────────────────────────────────────────────
    # or 3      04           D           20          F2           3C
    $ or 4      05           F           21          F3           3D
    % or 5      06           G           22          F4           3E
    ^ or 6      07           H           23          F5           3F
    & or 7      08           J           24          F6           40
    * or 8      09           K           25          F7           41
    ( or 9      0A           L           26          F8           42
    ) or 0      0B           : or ;      27          F9           43
    _ or -      0C           " or '      28          F10          44
    + or =      0D           ~ or `      29          NUM LOCK     45
    LEFT        0E           LEFT SHIFT  2A          SCROLL LOCK  46
    TAB         0F           | or \      2B          HOME or 7    47
    Q           10           Z           2C          UP or 8      48
    W           11           X           2D          PGUP or 9    49
    E           12           C           2E          -            4A
    R           13           V           2F          LEFT or 4    4B
    T           14           B           30          5            4C
    Y           15           N           31          RIGHT or 6   4D
                Code                     Code                     Code
    Key         in Hex       Key         in Hex      Key          in Hex
    ──────────────────────────────────────────────────────────────────────────
    Y           15           N           31          RIGHT or 6   4D
    U           16           M           32          +            4E
    I           17           < or ,      33          END or 1     4F
    O           18           > or .      34          DOWN or 2    50
    P           19           ? or /      35          PGDN or 3    51
    { or [      1A           RIGHT SHIFT 36          INS or 0     52
    } or ]      1B           PRTSC or *  37          DEL or .     53
    RETURN      1C           ALT         38
    ──────────────────────────────────────────────────────────────────────────


────────────────────────────────────────────────────────────────────────────
NOTE
    The scan codes in Table R.4 are equivalent to the first column of the
    scan code table in Appendix A, "Keyboard Scan Codes and ASCII Character
    Codes." The codes in the other columns of the table in the appendix should
    not be used for key trapping.
────────────────────────────────────────────────────────────────────────────

    The KEY(n) ON statement enables soft-key or cursor-direction-key event
    trapping by an ON KEY statement. If you specify a nonzero line number in
    the ON KEY statement while trapping is enabled, BASIC checks to see if you
    have pressed KEY(n). If you have, BASIC executes the GOSUB clause in the
    ON KEY statement. The text that would normally be associated with a
    FUNCTION key is not input.

    When you are working in the environment, QuickBASIC tests between
    statements for key presses. In stand-alone programs, you can specify
    checking between lines.

    KEY(n) OFF disables the event trap; even if an event takes place, it is
    not remembered. KEY(n) STOP inhibits the event trap; that is, if you press
    the specified key your action is remembered and an ON KEY event trap is
    executed as soon as a KEY(n) ON statement is executed.

■ See Also

    ON event

■ Example

    This example traps the DOWN direction key and CTRL+S (control key and
    lowercase "s"). To trap the combination of the CTRL key and uppercase "s,"
    you need to trap CTRL+SHIFT and CTRL+CAPS LOCK+S.

    I = 0
    PRINT "Press DOWN direction key to end."
    KEY 15,CHR$(&H04)+CHR$(&H1f)
    KEY(15) ON              'Trap CTRL+s.
    KEY(14) ON              'Trap DOWN direction key.
    ON KEY(15) GOSUB Keytrap
    ON KEY(14) GOSUB Endprog
    Idle: GOTO Idle        'Endless loop

    Keytrap:   'Counts the number of times CTRL+s pressed.
        I = I + 1
    RETURN

    Endprog:
        PRINT "CTRL+s trapped"; I; "times"
        END
    RETURN


────────────────────────────────────────────────────────────────────────────
KILL Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Deletes a file from disk

■ Syntax

    KILL filespec

■ Remarks

    The KILL statement is similar to the DOS ERASE or DEL commands.

    KILL is used for all types of disk files: program files, random data
    files, and sequential data files. The filespec may contain question marks
    (?) or asterisks (*) used as wild cards. A question mark matches any
    single character in the file name or extension. An asterisk matches one or
    more characters starting at its position.

    You can use KILL only to delete files. To delete directories, use the
    RMDIR command. Using KILL to delete a file that is currently open produces
    an error message that reads File already open.

────────────────────────────────────────────────────────────────────────────
WARNING
    Be extremely careful when using wild cards with KILL. You can delete files
    unintentionally with the wild card characters.
────────────────────────────────────────────────────────────────────────────

■ Examples

    The following examples show the effect of wild-card characters when used
    with KILL:

    KILL "DATA1?.DAT"           'Kills any file with a six-character
                                'base name starting with DATA1 and
                                'also with the extension .DAT.

    KILL "DATA1.*"              'Kills any file with the base name
                                'DATA1 and any extension.

    KILL "\GREG\*.DAT"        'Kills any file with the extension
                                '.DAT in a subdirectory called GREG.

    The following program deletes the file specified in the command line:

    DEFINT A-Z
    ON ERROR GOTO Errorhandle 'Set up error handling.
    FileName$ = COMMAND$      'Get file name.
    KILL FileName$
    END

    Errorhandle:
        Number = ERR
        IF Number = 53 THEN
            PRINT "Couldn't delete " FileName$ ;
            PRINT "; file does not exist in current directory"
        ELSE
            PRINT "Unrecoverable error:";Number
            ON ERROR GOTO 0   'ON ERROR GOTO zero aborts program.
        END IF
    RESUME NEXT


────────────────────────────────────────────────────────────────────────────
LBOUND Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the lower bound (smallest available subscript) for the indicated
    dimension of an array

■ Syntax

    LBOUND(array«,dimension»)

■ Remarks

    The LBOUND function is used with the UBOUND function to determine the size
    of an array. LBOUND takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    array                    The name of the array being dimensioned

    dimension                An integer ranging from 1 to the number of
                            dimensions in array: indicates which dimension's
                            lower bound is returned
    ──────────────────────────────────────────────────────────────────────────

    For an array dimensioned as follows, LBOUND returns the values listed
    below:

    DIM A(1 TO 100, 0 TO 50, -3 TO 4)

    Invocation               Value Returned
    ──────────────────────────────────────────────────────────────────────────
    LBOUND(A,1)              1
    LBOUND(A,2)              0
    LBOUND(A,3)              -3
    ──────────────────────────────────────────────────────────────────────────

    The default lower bound for any dimension is either 0 or 1, depending on
    the setting of the OPTION BASE statement. If OPTION BASE is 0, the default
    lower bound is 0, and if OPTION BASE is 1, the default lower bound is 1.

    Arrays dimensioned using the TO clause in the DIM statement may have any
    integer value as a lower bound.

    You may use the shortened syntax LBOUND(array) for one-dimensional arrays,
    since the default value for dimension is 1. Use the UBOUND function to
    find the upper limit of an array dimension.

■ See Also

    UBOUND

■ Example

    The LBOUND and UBOUND functions may be used to determine the size of an
    array passed to a subprogram, as in the following program fragment:

    CALL Prntmat(Array())
    .
    .
    .
    ' Print a matrix (two-dimensional array).
    SUB Prntmat(A(2)) STATIC
        ' Outer loop controls row (dimension 1).
        FOR I% = LBOUND(A,1) TO UBOUND(A,1)
        ' Inner loop controls column (dimension 2).
        FOR J% = LBOUND(A,2) TO UBOUND(A,2)
            PRINT A(I%,J%);" ";
        NEXT J%
        PRINT:PRINT
        NEXT I%
    END SUB


────────────────────────────────────────────────────────────────────────────
LCASE$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string expression with all letters in lowercase

■ Syntax

    LCASE$ (stringexpression)

■ Remarks

    The LCASE$ function takes a string variable, string constant, or string
    expression as its single argument. LCASE$ works with both variable- and
    fixed-length strings.

    LCASE$ and UCASE$ are helpful in string comparison operations where tests
    need to be case insensitive.

■ See Also

    UCASE$

■ Example

    The following example converts uppercase characters in a string to
    lowercase characters:

    ' Program to convert to lowercase.
        READ Word$
        PRINT LCASE$(Word$);
        DATA "THIS IS THE STRING in lowercase."

■ Output

    this is the string in lowercase.


────────────────────────────────────────────────────────────────────────────
LEFT$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string consisting of the leftmost n characters of a string

■ Syntax

    LEFT$(stringexpression,n)

■ Remarks

    The argument stringexpression can be any string variable, any string
    constant, or any string expression.

    The argument n is a numeric expression in the range 0-32,767 indicating
    how many characters are to be returned.

    If n is greater than the number of characters in stringexpression, the
    entire string is returned. To find the number of characters in
    stringexpression, use LEN(stringexpression).

    If n is zero, the null string (length zero) is returned.

■ See Also

    MID$, RIGHT$

■ Example

    The following example prints the leftmost five characters of A$:

    A$="BASIC LANGUAGE"
    B$=LEFT$(A$,5)
    PRINT B$

■ Output

    BASIC


────────────────────────────────────────────────────────────────────────────
LEN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the number of characters in a string or the number of bytes
    required by a variable

■ Syntax

    LEN(stringexpression)
    LEN(variable)

■ Remarks

    In the first form, LEN returns the number of characters in the argument
    stringexpression. The second syntax returns the number of bytes required
    by a BASIC variable. This syntax is particularly useful for determining
    the correct record size of a random-access file.

■ Example

    The following example prints the sizes of BASIC variables of several
    different types and also prints the length of a string:

    TYPE EmpRec
        EmpName AS STRING*20
        EmpNum AS INTEGER
    END TYPE
    DIM A AS INTEGER, B AS LONG, C AS SINGLE, D AS DOUBLE
    DIM E AS EmpRec

    PRINT "Integer:" LEN(A)
    PRINT "Long:" LEN(B)
    PRINT "Single:" LEN(C)
    PRINT "Double:" LEN(D)
    PRINT "EmpRec:" LEN(E)
    PRINT "A string:" LEN("A string.")
    END

■ Output

    Integer: 2
    Long: 4
    Single: 4
    Double: 8
    EmpRec: 22
    A string: 9


────────────────────────────────────────────────────────────────────────────
LET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Assigns the value of an expression to a variable

■ Syntax

    «LET»variable=expression

■ Remarks

    Notice that the word LET is optional. The equal sign in the statement is
    enough to inform QuickBASIC that the statement is an assignment statement.

    LET statements can be used with record variables only when both variables
    are the same user-defined type. Use the LSET statement for assigning
    record variables of different user-defined types.

■ See Also

    LSET

■ Examples

    Corresponding lines perform the same function in these two examples:

    LET D=12
    LET E=12-2
    LET F=12-4
    LET SUM=D+E+F
    .
    .
    .

    or

    D=12
    E=12-2
    F=12-4
    SUM=D+E+F
    .
    .
    .


────────────────────────────────────────────────────────────────────────────
LINE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Draws a line or box on the screen

■ Syntax

    LINE ««STEP» (x1,y1)»-«STEP» (x2,y2) «,«color»«,«B«F»»«,style»»»

■ Remarks

    The coordinates (x1,y1) and (x2,y2) specify the endpoints of the line;
    note that the order in which these endpoints appear is unimportant, since
    a line from (10,20) to (120,130) is the same as a line from (120,130) to
    (10,20).

    The STEP option makes the specified coordinates relative to the most
    recent point, instead of absolute, mapped coordinates. For example, if the
    most recent point referred to by the program is (10,10), then

    LINE -STEP (10,5)

    draws a line from (10,10) to the point with x-coordinate equal to 10 + 10
    and y-coordinate equal to 10 + 5, or (20,15).

    You may establish a new most recent point by initializing the screen with
    the CLS and SCREEN statements. Using the PSET, PRESET, CIRCLE, and DRAW
    statements will also establish a new most recent point.

    Variations of the STEP argument are shown below. For the following
    examples, assume that the last point plotted was (10,10):

╓┌─┌────────────────────────────────────────────────┌────────────────────────╖
    Statement                                        Description
    ──────────────────────────────────────────────────────────────────────────
    LINE -(50,50)                                    Draws from (10,10) to
                                                    (50,50)

    LINE -STEP(50,50)                                Draws from (10,10) to
                                                    (60,60); that is, to 10
                                                    plus offset 50

    LINE (25,25)-STEP(50,50)                         Draws from (25,25) to
                                                    (75,75); that is, to 25
                                                    plus offset 50

    Statement                                        Description
    ──────────────────────────────────────────────────────────────────────────

    LINE STEP(25,25)-STEP(50,50)                     Draws from (35,35) to
                                                    (85,85); that is, from 10
                                                    plus offset 25 to that
                                                    point plus offset 50

    LINE STEP(25,25)-(50,50)                         Draws from (35,35) to
                                                    (50,50); that is, from 10
                                                    plus offset 25 to
                                                    absolute 50
    ──────────────────────────────────────────────────────────────────────────


    The color is the number of the color in which the line is drawn. (If the B
    or BF options are used, the box is drawn in this color.) See the SCREEN
    statement for information on valid colors.

    The B option draws a box with the points (x1,y1) and (x2,y2) specifying
    diagonally opposite corners.

    The BF option draws a filled box. This option is similar to the B option;
    BF also paints the interior of the box with the selected color.

    The style is a 16-bit integer mask used to put pixels on the screen. Using
    the style argument is called "line styling." With line styling, LINE reads
    the bits in style from left to right. If a bit is 0, then no point is
    plotted; if the bit is 1, a point is plotted. After plotting a point, LINE
    selects the next bit position in style.

    Because a 0 bit in style does not change the point on the screen, you may
    want to draw a background line before using styling so you can have a
    known background. Style is used for normal lines and boxes, but has no
    effect on filled boxes.

    When coordinates specify a point that is not in the current viewport, the
    line segment is clipped to the viewport.

    See Chapter 5, "Graphics," in Programming in BASIC for more information on
    the LINE statement.

■ See Also

    SCREEN

■ Examples

    The following examples are different LINE statements that assume a screen
    320 pixels wide by 200 pixels high:

    SCREEN 1                          'Sets up the screen mode.

    LINE -(X2,Y2)                     'Draws a line (in the
                                    'foreground color) from
                                    'the most recent point
                                    'to  X2,Y2.

    LINE(0,0)-(319,199)               'Draws a diagonal line across
                                    'the screen (downward).


    LINE(0,100)-(319,100)             'Draws a horizontal line
                                    'across the screen.

    LINE(10,10)-(20,20),2             'Draws a line in color 2.

    FOR X=0 to 319                    'Draws an alternating pattern
        LINE(X,0)-(X,199),X AND 1     '(line on/line off) on mono-
    NEXT                              'chrome display.

    LINE (0,0)-(100,100),,B           'Draws a box in the fore-
                                    'ground color (note that the
                                    'color is not included).

    LINE STEP(0,0)-STEP(200,200),2,BF 'Draws a filled box in color
                                    '2 (coordinates are given as
                                    'offsets with the STEP option).

    LINE(0,0)-(160,100),3,,&HFF00     'Draws a dashed line from
                                    'the upper lefthand corner to
                                    'the center of the screen in
                                    'color 3.


────────────────────────────────────────────────────────────────────────────
LINE INPUT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Inputs an entire line (up to 255 characters) to a string variable, without
    the use of delimiters

■ Syntax

    LINE INPUT«;» «"promptstring";» stringvariable

■ Remarks

    The promptstring is a string constant displayed on the screen before input
    is accepted. A question mark is not printed unless it is part of the
    promptstring. All input from the end of promptstring to the carriage
    return is assigned to stringvariable.

    A semicolon immediately after the LINE INPUT statement keeps the cursor on
    the same line after the user presses ENTER.

    LINE INPUT uses the same editing characters as INPUT.

■ See Also

    INPUT

■ Example

    The following program enables the user to enter text in a notes file. The
    LINE INPUT statement allows you to enter any characters, including those
    (such as a comma) that are delimiters in a regular INPUT statement.

    'Opens and writes lines to a notes file until you
    'enter a blank line.
    DO
        CLS
        PRINT "Enter text. To stop, press <RETURN> without ";
        PRINT "entering any new text." : PRINT
        OPEN "NOTES.TXT" FOR OUTPUT AS #1

        ' Take lines until a blank line is entered.
        DO
            LINE INPUT "->";Inline$
            IF Inline$ <> "" THEN PRINT #1, Inline$
        LOOP WHILE Inline$ <> ""
        CLS : CLOSE #1

    ' Echo the notes back and see if they are correct.
        OPEN "NOTES.TXT" FOR INPUT AS #1
        PRINT "You entered: " : PRINT
        DO WHILE NOT EOF(1)
            LINE INPUT #1, Inline$
            PRINT Inline$
        LOOP
        CLOSE #1
        PRINT : INPUT "Is this correct (Y/N)"; R$

    LOOP WHILE UCASE$(R$)="N"
    END


────────────────────────────────────────────────────────────────────────────
LINE INPUT # Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads an entire line without delimiters from a sequential file to a string
    variable

■ Syntax

    LINE INPUT #filenumber,stringvariable

■ Remarks

    The filenumber is the number used to open the file. The stringvariable is
    the variable the line is assigned to.

    The LINE INPUT # statement reads all characters in the sequential file up
    to a carriage return. It then skips over the carriage-return and line-feed
    sequence. The next LINE INPUT # reads all characters up to the next
    carriage return.

    LINE INPUT # is especially useful if each line of a data file has been
    broken into fields or a text file is being read a line at a time.

■ See Also

    INPUT$, LINE INPUT

■ Example

    The following uses LINE INPUT # to echo data input to a file:

    OPEN "LIST" FOR OUTPUT AS #1
    PRINT "CUSTOMER INFORMATION:"
    ' Get customer information.
    DO
        PRINT
        INPUT "   LAST NAME:  ", LName$
        INPUT "   FIRST NAME: ", FrName$
        INPUT "   AGE:        ", Age$
        INPUT "   SEX:        ", Sex$
        Sex$=UCASE$(Sex$)
        WRITE #1, LName$, FrName$, Age$, Sex$
        INPUT "Add another"; R$
    LOOP WHILE UCASE$(R$)="Y"
    CLOSE #1


    ' Echo the file back.
    OPEN "LIST" FOR INPUT AS #1
    CLS
    PRINT "Records in file:" : PRINT
    DO WHILE NOT EOF(1)
        LINE INPUT #1, REC$
    'Read records from file with
        PRINT REC$          'LINE INPUT #. Print the
                            'records on the screen.
    LOOP

■ Output

    CUSTOMER INFORMATION:


        LAST NAME:  Saintsbury
        FIRST NAME: Aloysius
        AGE:        35
        SEX:        m
    Add another? y

        LAST NAME:  Frangio
        FIRST NAME: Louisa
        AGE:        27
        SEX:        f
    Add another? n

    Records in file:

    "Saintsbury","Aloysius","35","M"
    "Frangio","Louisa","27","F"


────────────────────────────────────────────────────────────────────────────
LOC Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current position within the file

■ Syntax

    LOC(filenumber)

■ Remarks

    The filenumber is the number used in the OPEN statement to open the file.
    With random-access files, the LOC function returns the number of the last
    record read from or written to the file. With sequential files, LOC
    returns the current byte position in the file, divided by 128. With binary
    mode files, LOC returns the position of the last byte read or written.

    For a COM device, LOC(filenumber) returns the number of characters in the
    input queue waiting to be read. The value returned depends on whether the
    device was opened in ASCII or binary mode. In ASCII mode, the low-level
    routines stop queuing characters as soon as end-of-file is received. The
    end-of-file itself is not queued and cannot be read. An attempt to read
    the end-of-file produces an error message that reads Input past end of
    file. In binary mode, the end-of-file character is ignored and the entire
    file can therefore be read.

    The LOC function cannot be used on the SCRN:, KYBD:, or LPTn: devices.

■ See Also

    OPEN COM

■ Example

    The following line stops the program if the current file position is
    beyond 50:

    IF LOC(1) > 50 THEN STOP


────────────────────────────────────────────────────────────────────────────
LOCATE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Moves the cursor to the specified position

■ Syntax

    LOCATE«row»«,«column»«,«cursor»«,«start»«,stop»»»»

■ Remarks

    The following list describes the LOCATE statement's arguments:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    row                      The number of a row on the screen; row is a
                            numeric expression returning an integer. If row
                            is not specified, then the line (row) does not
                            change.

    column                   The number of a column on the screen; column is a
                            numeric expression returning an integer. If
                            column is not specified, then the column location
                            does not change.

    cursor                   A Boolean value indicating whether the cursor is
                            visible or not. A value of 0 (zero) indicates
                            cursor off; a value of 1 indicates cursor on.

    start                    The starting scan line of cursor on the screen.
                            It must be a numeric expression returning an
                            integer.

    stop                     The ending scan line of cursor on the screen. It
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    stop                     The ending scan line of cursor on the screen. It
                            must be a numeric expression returning an
                            integer.
    ──────────────────────────────────────────────────────────────────────────


    You may omit any argument from the statement except that if stop is
    specified, start must also be specified. When you omit the row or column,
    LOCATE leaves the cursor at the row or column where it was moved by a
    previous LOCATE or a previous input or output statement, whichever
    occurred most recently. When you omit other arguments, QuickBASIC assumes
    the previous value for the argument.

    Note that the start and stop lines are the CRT scan lines that specify
    which pixels on the screen are lit. A wider range between the start and
    stop lines produces a taller cursor, such as one that occupies an entire
    character block. When start is greater than stop, LOCATE produces a
    two-part cursor. If the start line is given but the stop line is omitted,
    stop assumes the same value as start.

    The last line on the screen is reserved for the soft-key display and is
    not accessible to the cursor unless the soft-key display is off (KEY OFF)
    and LOCATE is used with PRINT to write on the line.

■ See Also

    CSRLIN, POS

■ Examples

    The following statements show the effects on the cursor of different
    LOCATE statements:

    LOCATE 1,1    'Moves cursor to upper-left corner of the screen.

    LOCATE,,1     'Makes the cursor visible; position remains
                'unchanged.

    LOCATE,,,7    'Position and cursor visibility remain unchanged;
                'sets the cursor to display at the bottom of
                'the character box starting and ending on
                'scan line 7.

    LOCATE 5,1,1,0,7     'Moves the cursor to line 5, column 1;
                        'turns cursor on; cursor covers entire
                        'character cell starting at scan line
                        '0 and ending on scan line 7.

    The following example prints a menu on the screen, then waits for input in
    the allowable range (1-4). If a number outside that range is entered, the
    program continues to prompt for a selection.

    CONST FALSE=0, TRUE=NOT FALSE
    DO
        CLS
        PRINT "MAIN MENU" : PRINT
        PRINT "1)  Add Records"
        PRINT "2)  Display/Update/Delete a Record"
        PRINT "3)  Print Out List of People Staying at Hotel"
        PRINT "4)  End Program"
        ' Change cursor to a block.
        LOCATE ,,1,1,12
        LOCATE 12,1
        PRINT "What is your selection?";
        DO
            CH$ = INPUT$(1)
        LOOP WHILE (CH$ < "1" OR CH$ > "4")
        PRINT CH$

    ' Call the appropriate subprogram.
        SELECT CASE VAL(CH$)
            CASE 1
            CALL Add
            CASE 2
            CALL Search
            CASE 3
            CALL Hotel
            CASE 4
            CALL Quit
        END SELECT
    LOOP WHILE NOT ENDPROG
    .
    .
    .
    END


────────────────────────────────────────────────────────────────────────────
LOCK...UNLOCK Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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}»

■ Remarks

    These statements are used in networked environments where several
    processes might need access to the same file. The LOCK and UNLOCK
    statements take the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filenumber               The number with which the file was opened.

    record                   The number of the record or byte to be locked;
                            record can be any number from 1 to 2,147,483,647
                            (equivalent to 2^31-1). A record may be up to
                            32,767 bytes in length.

    start                    The number of the first record or byte to be
                            locked.

    end                      The number of the last record or byte to be
                            locked.
    ──────────────────────────────────────────────────────────────────────────

    For binary-mode files, the arguments record, start, and end represent the
    number of a byte relative to the beginning of the file. The first byte in
    a file is byte 1. For random-access files, the arguments record, start,
    and end are the number of a record relative to the beginning of the file.
    The first record is record 1.

    The LOCK and UNLOCK statements are always used in pairs. The arguments to
    LOCK and UNLOCK must match exactly when you use them. See the second
    example below.

    If you specify just one record, then only that record is locked or
    unlocked. If you specify a range of records and omit a starting record
    (start), then all records from the first record to the end of the range
    (end) are locked or unlocked. LOCK with no record arguments locks the
    entire file, while UNLOCK with no record arguments unlocks the entire
    file.

    If the file has been opened for sequential input or output, LOCK and
    UNLOCK affect the entire file, regardless of the range specified by start
    and end. LOCK and UNLOCK only function at run time if you are using
    versions of DOS that support networking (version 3.1 or later). In
    addition, each terminal (or the network setup programs) must run the DOS
    SHARE.EXE program to enable locking operations. Earlier versions of DOS
    return an error message that reads Advanced feature unavailable if LOCK
    and UNLOCK are executed.

────────────────────────────────────────────────────────────────────────────
NOTE
    Be sure to remove all locks with an UNLOCK statement before closing a file
    or terminating your program. Failing to remove locks produces
    unpredictable results. The arguments to LOCK and UNLOCK must match
    exactly.
────────────────────────────────────────────────────────────────────────────

    If you attempt to access a file that is locked, the following error
    messages may appear:

    Bad record number
    Permission denied

■ Examples

    These examples assume a random-access file. The following statement locks
    the entire file opened as number 2:

    LOCK #2

    The following statement locks only record 32 in file number 2:

    LOCK #2, 32

    The following statement locks records 1-32 in file number 2:

    LOCK #2, TO 32

    The two UNLOCK statements below unlock the records locked by the preceding
    LOCK statements:

    LOCK #1, 1 TO 4
    LOCK #1, 5 TO 8
    UNLOCK #1, 1 TO 4
    UNLOCK #1, 5 TO 8

    The following UNLOCK statement is illegal because the range in an UNLOCK
    statement must exactly match the range in the corresponding LOCK
    statements (no error is reported, but the statements produce unpredictable
    results):

    LOCK #1, 1 TO 4
    LOCK #1, 5 TO 8
    UNLOCK #1, 1 TO 8

    The following program fragment opens a file and allows a user to lock an
    individual record before updating the information in that record. When the
    user is done, the program unlocks the locked record. (Unlocking the locked
    records allows other processes to use the data in the file.)

    TYPE AccountRec
        Payer AS STRING*15
        Address AS STRING*20
        Place AS STRING*20
        Owe AS SINGLE
    END TYPE
    DIM CustRec AS AccountRec

    OPEN "MONITOR" SHARED AS #1 LEN = LEN(CustRec)

    DO
        CLS:LOCATE 10,10
        INPUT "Customer Number?   #"; Number%
        ' Lock the current record so another process
        ' doesn't change it while you're using it.
        LOCK #1, Number%
        GET #1, Number%
        LOCATE 11,10: PRINT "Customer: ";CustRec.Payer
        LOCATE 12,10: PRINT "Address:  ";CustRec.Address
        LOCATE 13,10: PRINT "Currently owes: $";CustRec.Owe
        LOCATE 15,10: INPUT "Change (+ or -)", Change!
        CustRec.Owe=CustRec.Owe+Change!
        PUT #1, Number%
        ' Unlock the record.
        UNLOCK #1, Number%
        LOCATE 17,10: INPUT "Update another? ", Continue$
        Update$ = UCASE$(LEFT$(Continue$,1))
    LOOP WHILE Update$="Y"


────────────────────────────────────────────────────────────────────────────
LOF Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the length of the named file in bytes

■ Syntax

    LOF(filenumber)

■ Remarks

    The argument filenumber is the number used in the OPEN statement. When a
    file is opened in any mode, the LOF function returns the size of the file
    in bytes.

    LOF cannot be used with the BASIC devices SCRN:, KYBD:, CONS:, and LPTn:.
    When used on a device opened as a file with the statement OPEN COM, the
    LOF function returns the number of bytes free in the output buffer.

■ Example

    See the example for the GET statement.


────────────────────────────────────────────────────────────────────────────
LOG Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the natural logarithm of a numeric expression

■ Syntax

    LOG(n)

■ Remarks

    The numeric expression, n, must be greater than zero. The natural
    logarithm is the logarithm to the base e. The constant e is approximately
    equal to 2.718282.

    The LOG function calculates the natural logarithm with single-precision
    accuracy, unless the argument n is a double-precision value. In this case
    LOG is calculated with double-precision accuracy.

    You may calculate base-10 logarithms by dividing the natural logarithm of
    the number by the logarithm of 10. The following FUNCTION calculates
    base-10 logarithms:

    FUNCTION Log10(X) STATIC
        Log10=LOG(X)/LOG(10.#)
    END FUNCTION

■ Example

    The following example first prints the value of e and then prints the
    natural logarithms of e taken to the first, second, and third powers:

    PRINT EXP(1),
    FOR I = 1 TO 3
        PRINT LOG(EXP(1)^I),
    NEXT

■ Output

    2.718282       1       2       3


────────────────────────────────────────────────────────────────────────────
LPOS Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current position of the line printer's print head within the
    printer buffer

■ Syntax

    LPOS(n)

■ Remarks

    The argument n is the index of the printer being tested. For example,
    LPT1: would be tested with LPOS(1), while LPT2: would be tested with
    LPOS(2), and so on.

    The LPOS function does not necessarily give the physical position of the
    print head because it does not expand tab characters. In addition, some
    printers may buffer characters.

■ Example

    The following program prompts the user for team names and the names of
    players on each team. It then prints the players and their teams on the
    printer.

    LPRINT"Team Members"; TAB(76); "TEAM" : LPRINT
    INPUT "How many teams"; TEAMS
    INPUT "How many players per team";PPT
    PRINT
    FOR T = 1 TO TEAMS
        INPUT "Team name: ", TEAM$
        FOR P = 1 TO PPT
            INPUT "   Enter player name: ", PLAYER$
            LPRINT PLAYER$;
            IF P < PPT THEN
                IF LPOS(0) > 55 THEN     'Print a new line if print
                                        'head past column 55.
                    LPRINT : LPRINT "     ";
                ELSE
                    LPRINT ", ";           'Otherwise, print a comma.
                END IF
            END IF
        NEXT P
        LPRINT STRING$(80-LPOS(0)-LEN(TEAM$),"."); TEAM$
    NEXT T


────────────────────────────────────────────────────────────────────────────
LPRINT, LPRINT USING Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Prints data on the printer LPT1:

■ Syntax 1

    LPRINT «expressionlist» «{;|,}»

■ Syntax 2

    LPRINT USING formatstring; expressionlist «{;|,}»

■ Remarks

    These statements function in the same way as the PRINT and PRINT USING
    statements except that output goes to the line printer and the filenumber
    option is not permitted.

    The LPRINT statement assumes an 80-character-wide printer. This width can
    be changed with a WIDTH LPRINT statement.

────────────────────────────────────────────────────────────────────────────
WARNING
    Since the LPRINT statement uses the LPT1 printer device, you should not
    use LPRINT in a program that also contains an OPEN LPT1 statement. Using
    these two statements together produces unpredictable results.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    An LPRINT CHR$(13) statement actually outputs both CHR$(13) and CHR$(10).
    This feature was created to provide compatibility with BASICA.

■ See Also

    PRINT, PRINT USING, WIDTH

■ Example

    See examples for PRINT, PRINT USING.


────────────────────────────────────────────────────────────────────────────
LSET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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=
    stringexpression2}

■ Remarks

    The stringvariable is usually a random-access file field defined in a
    FIELD statement, although it can be any string variable. The
    stringexpression is the value assigned to the variable.

    If stringexpression requires fewer bytes than were defined for
    stringvariable in the FIELD statement, the LSET function left-justifies
    the string in the field (RSET will right-justify the string). Spaces are
    used to pad the extra positions. If the string is too long for the field,
    both LSET and RSET truncate characters from the right. Numeric values must
    be converted to strings before they are justified with the LSET or RSET
    statements.

────────────────────────────────────────────────────────────────────────────
NOTE
    You may also use LSET or RSET with a string variable not defined in a
    FIELD statement to left-justify or right-justify a string in a given
    field. For example, the program lines

    A$=SPACE$(20)
    RSET A$=N$

    will right-justify the string N$ in a 20-character field. This can be
    useful for formatting printed output.

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

    You can use LSET to assign one record variable to another. The following
    example copies the contents of RecTwo to RecOne:

    TYPE TwoString
        StrFld AS STRING * 2
    END TYPE

    TYPE ThreeString
        StrFld AS STRING * 3
    END TYPE
    DIM RecOne AS TwoString, RecTwo AS ThreeString
    .
    .
    .
    LSET RecOne = RecTwo

    Notice that LSET is used to assign record variables of differing types.
    Record variables of the same type can be assigned using LET. Also, because
    RecOne is only two bytes long, only two bytes are copied from RecTwo. LSET
    copies only the number of bytes in the shorter of the two record
    variables.

■ See Also

    LET; MKD$, MKI$, MKL$, MKS$; PUT (File I/O); RSET

■ Example

    The first line of the following example converts the single-precision
    numeric variable AMT to a 4-byte string and stores that string in A$,
    left-justified. The second line converts the integer numeric variable
    COUNT% to a 2-byte string and stores that string in D$, right-justified.

    LSET A$ = MKS$(AMT)
    RSET D$ = MKI$(COUNT%)


────────────────────────────────────────────────────────────────────────────
LTRIM$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a copy of a string with leading spaces removed

■ Syntax

    LTRIM$(stringexpression)

■ Remarks

    The stringexpression can be any string expression.

■ See Also

    RTRIM$

■ Example

    This program copies a file to a new file, removing all leading and
    trailing spaces:

    CLS
    ' Get the file names.
    INPUT "Enter input file name:",InFile$
    INPUT "Enter output file name:",OutFile$

    OPEN InFile$ FOR INPUT AS #1
    OPEN OutFile$ FOR OUTPUT AS #2

    ' Read, trim, and write each line.
    DO WHILE NOT EOF(1)
        LINE INPUT #1,LineIn$
        ' Remove leading and trailing blanks.
        LineIn$=LTRIM$(RTRIM$(LineIn$))
        PRINT #2, LineIn$
    LOOP

    CLOSE #1,#2

    END


────────────────────────────────────────────────────────────────────────────
MID$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a substring of a string

■ Syntax

    MID$(stringexpression,start«,length»)

■ Remarks

    The MID$ function takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    stringexpression         The string expression that the substring is
                            extracted from. This can be any string
                            expression.

    start                    The character position in stringexpression where
                            the substring starts.

    length                   The number of characters to extract.
    ──────────────────────────────────────────────────────────────────────────

    The arguments start and length must be in the range 1 to 32,767. If length
    is omitted or if there are fewer than length characters to the right of
    the start character, the MID$ function returns all characters to the right
    of the start character.

    If start is greater than the number of characters in stringexpression,
    MID$ returns a null string.

    Use the LEN function to find the number of characters in stringexpression.

■ See Also

    LEFT$, LEN, MID$ Statement, RIGHT$

■ Example

    The following program converts a binary number to a decimal number. Digits
    are extracted from the binary number (input as a string) using MID$.

    INPUT "Binary number = ",Binary$   'Input binary number as
                                        'string.
    Length = LEN(Binary$)              'Get length of string.
    Decimal = 0

    FOR K = 1 TO Length
        'Get individual digits from string, from left to right.
        Digit$ = MID$(Binary$,K,1)
        'Test for valid binary digit.
        IF Digit$="0" OR Digit$="1" THEN
        'Convert digit characters to numbers.
        Decimal = 2*Decimal + VAL(Digit$)
        ELSE
        PRINT "Error--invalid binary digit: ";Digit$
        EXIT FOR
        END IF
    NEXT
    PRINT "Decimal number =" Decimal

■ Output

    Binary number = 10110
    Decimal number = 22


────────────────────────────────────────────────────────────────────────────
MID$ Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Replaces a portion of a string variable with another string

■ Syntax

    MID$(stringvariable,start«,length»)=stringexpression

■ Remarks

    The MID$ statement has the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    stringvariable           The string variable being modified.

    start                    A numeric expression giving the position in
                            stringvariable where the replacement starts.

    length                   The length of the string being replaced. The
                            length is a numeric expression.

    stringexpression         The string expression that replaces part of the
                            stringvariable.
    ──────────────────────────────────────────────────────────────────────────

    The arguments start and length are integer expressions. The argument
    stringvariable is a string variable, but stringexpression can be a string
    variable, a string constant, or a string expression.

    The optional length refers to the number of characters from the argument
    stringexpression that are used in the replacement. If length is omitted,
    all of stringexpression is used. However, regardless of whether length is
    omitted or included, the replacement of characters never goes beyond the
    original length of stringvariable.

■ See Also

    MID$ Function

■ Example

    The following example uses the MID$ statement to get characters from a
    string:

    Test$ = "Paris, France"
    PRINT Test$
    MID$(Test$,8)="Texas "
    PRINT Test$

■ Output

    Paris, France
    Paris, Texas


────────────────────────────────────────────────────────────────────────────
MKDIR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Creates a new directory

■ Syntax

    MKDIR pathname

■ Remarks

    The pathname is a string expression specifying the name of the directory
    to be created. The pathname must be a string of less than 128 characters.

    The MKDIR statement works like the DOS command MKDIR; the syntax in BASIC
    cannot, however, be shortened to MD, as in DOS.

■ See Also

    CHDIR, RMDIR

■ Example

    The following fragment creates a new directory (if the directory does not
    exist) and copies files into that directory:

    ON ERROR GOTO Errorhandler
    PRINT "This program creates a new directory named MONTHS"
    PRINT "in this directory, then creates files in that directory"
    MKDIR "MONTHS"
    DO
        INPUT "Filename"; File$
        IF File$ = "" THEN END
        OPEN "MONTHS\" + File$ FOR OUTPUT AS #1
        .
        .
        .
        CLOSE #1
    LOOP

    Errorhandler:
        'Error 75 means MONTHS directory already exists
        IF ERR = 75 THEN RESUME NEXT
        ON ERROR GOTO 0


────────────────────────────────────────────────────────────────────────────
MKSMBF$, MKDMBF$ Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts an IEEE-format number to a string containing a Microsoft Binary
    format number.

■ Syntax

    MKSMBF$(single-precision-expression)
    MKDMBF$(double-precision-expression)

■ Remarks

    These functions are used to write real numbers to random-access files
    using Microsoft Binary format. They are particularly useful for
    maintaining data files created with older versions of BASIC.

    The MKSMBF$ and MKDMBF$ functions convert real numbers in IEEE-format to
    strings so they can be written to the random-access file.

    To write a real number to a random-access file in Microsoft Binary format,
    convert the number to a string using MKSMBF$ (for a single-precision
    number) or MKDMBF$ (for a double-precision number). Then store the result
    in the corresponding field (defined in the FIELD statement) and write the
    record to the file using the PUT statement.

■ Example

    The following example uses MKSMBF$ to store real values in a file as
    Microsoft Binary format numbers:

    ' Read a name and a test score from the console.
    ' Store as a record in a random-access file.
    ' Scores are written out as
    ' Microsoft Binary format single-precision values.

    TYPE Buffer
        NameField AS STRING * 20
        ScoreField AS STRING * 4
    END TYPE

    DIM RecBuffer AS Buffer
    OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(RecBuffer)

    PRINT "Enter names and scores, one name and score per line."
    PRINT "Enter END, 0 to end input."

    INPUT NameIn$, Score

    I=0

    ' Read pairs of names and scores from the console
    ' until the name is END.

    DO WHILE UCASE$(NameIn$) <> "END"
        I=I+1
        RecBuffer.NameField=NameIn$

    ' Convert the score to a string.
        RecBuffer.ScoreField=MKSMBF$(Score)
        PUT #1,I,RecBuffer
        INPUT NameIn$, Score
    LOOP

    PRINT I;" records written."

    CLOSE #1


────────────────────────────────────────────────────────────────────────────
MKD$, MKI$, MKL$, MKS$ Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Converts numeric values to string values

■ Syntax

    MKI$(integerexpression)
    MKS$(single-precision-expression)
    MKL$(long-integer-expression)
    MKD$(double-precision-expression)

■ Remarks

    The MKI$, MKS$, MKL$, and MKD$ functions are used with FIELD and PUT
    statements to write real numbers to a random-access file. The functions
    take numeric expressions and convert them to strings that can be stored in
    the strings defined in the FIELD statement. The functions are the inverse
    of CVI, CVS, CVL, and CVD.

    Function                 Description
    ──────────────────────────────────────────────────────────────────────────
    MKI$                     Converts an integer to a two-byte string

    MKS$                     Converts a single-precision value to a four-byte
                            string

    MKL$                     Converts a long-integer value to a four-byte
                            string

    MKD$                     Converts a double-precision value to an
                            eight-byte string
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    BASIC record variables provide a more efficient and convenient way of
    reading and writing random-access files. See Chapter 3, "File and Device
    I/O," in Programming in BASIC for a discussion of the new method.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CVI, CVS, CVL, CVD; FIELD; PUT

■ Example

    See the example for the CVI, CVS, CVL, CVD statements.


────────────────────────────────────────────────────────────────────────────
NAME Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Changes the name of a disk file or directory

■ Syntax

    NAME oldfilename AS newfilename

■ Remarks

    The NAME statement is similar to the DOS RENAME command. NAME can move a
    file from one directory to another but cannot move a directory.

    The arguments oldfilename and newfilename are string expressions each of
    which contains a file or directory name and an optional path. If the path
    in newfilename is different from the path in oldfilename, the NAME
    statement changes the pathname as well as renames the file as indicated.

    A file named oldfilename must exist and the newfilename must not be in
    use. Both files must be on the same drive. Using NAME with different drive
    designations in the old and new file names produces an error message that
    reads Rename across disks.

    After a NAME statement, the file or directory exists on the same disk, in
    the same disk space, but with the new name.

    Using NAME on an open file causes a run-time error message reading File
    already open. You must close an open file before renaming it.

■ Examples

    The following statements show NAME used with and without a path
    specification:

    'Changes the name of file ACCTS to LEDGER.
    NAME "ACCTS" AS "LEDGER"

    'Moves file CLIENTS from directory X to directory \XYZ\P.
    NAME "\X\CLIENTS" AS "\XYZ\P\CLIENTS"


────────────────────────────────────────────────────────────────────────────
OCT$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string representing the octal value of the numeric argument

■ Syntax

    OCT$(numeric-expression)

■ Remarks

    The numeric-expression may be of any type. The numeric-expression is
    rounded to an integer or long integer before the OCT$ function evaluates
    it.

■ See Also

    HEX$

■ Example

    The following line prints the octal representation of 24:

    PRINT OCT$(24)

■ Output

    30


────────────────────────────────────────────────────────────────────────────
ON event Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Indicates the first line of an event-trapping subroutine

■ Syntax

    ON event GOSUB {linenumber | linelabel }

■ Remarks

    The ON event statement lets you specify a subroutine that is executed
    whenever an event occurs on a specified device. The following list
    describes the parts of the statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    event                    Specifies the event that causes a branch to the
                            event-trapping subroutine. An event is a
                            condition on a specific device. See below for
                            more information about specific devices.

    linenumber linelabel     The number or label of the first line in the
                            event-trapping subroutine. This line must be in
                            the module-level code.
    ──────────────────────────────────────────────────────────────────────────

    A linenumber of 0 disables event trapping and does not specify line 0 as
    the start of the subroutine.

    The following list describes the events that can be trapped:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Event                    Description
    ──────────────────────────────────────────────────────────────────────────
    COM(n)                   Branches to the subroutine when characters are
                            received at a communications port. The integer
                            expression n indicates one of the serial ports,
                            either 1 or 2.

    KEY(n)                   Branches to the subroutine when a specified key
                            is pressed. The integer expression n is the
                            number of a function key, direction key, or
                            user-defined key. See Appendix A, "Keyboard Scan
                            Codes and ASCII Character Codes," and the KEY
                            statement for more information about these
                            values.

    PEN                      Branches to the subroutine when a lightpen is
                            activated.
    Event                    Description
    ──────────────────────────────────────────────────────────────────────────
                            activated.

    PLAY(queuelimit)         Branches when the number of notes in the music
                            buffer goes from queuelimit to queuelimit-1. The
                            value of queuelimit is an integer expression from
                            1 to 32.

                            A PLAY event-trapping subroutine can be used with
                            a PLAY statement to play music in the background
                            while a program is running.

    STRIG(n)                 Branches to the event-trapping subroutine when a
                            joystick trigger is pressed. The integer
                            expression n is the joystick trigger number: 0
                            for the lower button and 4 for the upper button
                            on the first joystick; 2 for the lower button and
                            6 for the upper button on the second joystick.

    TIMER(n)                 Branches to the subroutine when n seconds have
    Event                    Description
    ──────────────────────────────────────────────────────────────────────────
    TIMER(n)                 Branches to the subroutine when n seconds have
                            passed. The integer expression n is in the range
                            1 to 86,400 (1 second to 24 hours).
    ──────────────────────────────────────────────────────────────────────────


    The ON event statement only specifies the start of an event-trapping
    subroutine. Another set of statements determines whether or not the
    subroutine is called. This set of statements turns event trapping on or
    off and determines how events are handled when trapping is off. The
    following list describes these statements in a general way. See the
    entries for particular statements for more specific information.

    Event                    Description
    ──────────────────────────────────────────────────────────────────────────
    event ON                 Enables event trapping. Event trapping occurs
                            only after an event ON statement is executed.

    event OFF                Disables event trapping. No trapping takes place
                            until the execution of another event ON
                            statement. Events occurring while trapping is off
                            are ignored.

    event STOP               Inhibits event trapping so no trapping takes
                            place until an event ON statement is executed.
                            Events occurring while trapping is inhibited are
                            remembered and processed when an event ON
                            statement is executed.
    ──────────────────────────────────────────────────────────────────────────

    When an event trap occurs (the subroutine is called), BASIC performs an
    automatic event STOP that prevents recursive traps. The RETURN from the
    trapping subroutine automatically performs an event ON statement unless an
    explicit event OFF is performed inside the subroutine.

────────────────────────────────────────────────────────────────────────────
NOTE
    Because of the implicit event STOP and event ON statements, the events
    during execution of the trapping subroutine are remembered and processed
    when the trapping subroutine ends.
────────────────────────────────────────────────────────────────────────────

    The RETURN linenumber or RETURN linelabel forms of RETURN can be used to
    return to a specific line number from the trapping subroutine. Use this
    type of return with care, however, because any other GOSUB, WHILE, or FOR
    statements active at the time of the trap remain active. This may produce
    error messages such as NEXT without FOR. In addition, if an event occurs
    in a procedure, a RETURN linenumber or RETURN linelabel statement cannot
    get back into the procedure──the line number or label must be in the
    module-level code.

    The next three sections contain additional information about the ON COM,
    ON KEY, and ON PLAY statements.

    USING ON COM

    If your program receives data using an asynchronous communications
    adapter, the BASIC command-line option /C can be used to set the size of
    the data buffer.

    USING ON KEY

    Keys are processed in the following order:

    1. The line printer's echo-toggle key is processed first. Making this key
        a user-defined key trap does not prevent characters from being echoed
        to the line printer when pressed.

    2. Function keys and the cursor-direction keys are examined next. Defining
        a FUNCTION key or DIRECTION key as a user-defined key trap has no
        effect because these keys are predefined.

    3. Finally, the user-defined keys are examined.

    The ON KEY statement can trap any key, including BREAK or system reset.
    This makes it possible to prevent accidentally breaking out of a program
    or rebooting the machine.

────────────────────────────────────────────────────────────────────────────
NOTE
    When a key is trapped, the key event is destroyed. You cannot subsequently
    use INPUT or INKEY$ statements to find out which key caused the trap.
    Because there is no way to know which key press caused the branch to the
    trap, you must set up a subroutine for each key if you want to assign
    different functions to particular keys.
────────────────────────────────────────────────────────────────────────────

    USING ON PLAY

    The following three rules apply to the use of ON PLAY:

    1. A play event trap occurs only when music is playing in the background.
        Play event traps do not occur when music is running in the foreground.

    2. A play event trap does not occur if the background music queue has
        already gone from having queuelimit to queuelimit-1 notes when a PLAY
        ON is executed.

    3. If queuelimit is a large number, event traps may occur often enough to
        slow down the program.

■ Differences From Basica

    If you use BC from the DOS prompt, you must use /V or /W if a program
    contains ON event statements to allow the compiler to function correctly
    when event-trapping subroutines are included in a program. BASICA does not
    require additional options.

■ See Also

    COM, KEY (n), PEN ON, PLAY ON, RETURN, STRIG ON, TIMER ON

■ Examples

    The following example plays continuous music by calling an event-handling
    subroutine whenever the music buffer goes from three to two notes:

    '  Call subroutine Background when the music buffer goes from
    '  3 to 2 notes.
    ON PLAY(3) GOSUB Background
    '  Turn on event trapping for PLAY.
    PLAY ON

    '  Define a string containing the melody.
    Lizzie$="o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A"
    '  Play the melody for the first time.
    PLAY "MB X" + VARPTR$(Lizzie$)

    '  Continue until a key is pressed.
    LOCATE 2,1 : PRINT "Press any key to stop.";
    DO WHILE INKEY$=""
    LOOP

    END

    ' PLAY event-handling subroutine.
    Background:
        ' Increment and print a counter each time.
        Count% = Count% + 1
        LOCATE 1,1 : PRINT "Background called ";Count%;"time(s)";
        ' Execute another PLAY to fill the buffer.
        PLAY "MB X" + VARPTR$(Lizzie$)
        RETURN

    The following example draws a polygon every three seconds with a random
    shape (three to seven sides), size, and location:

    SCREEN 1
    DEFINT A-Z
    DIM X(6), Y(6)
    TIMER ON            'Enable timer event trapping.
    ON TIMER(3) GOSUB Drawpoly    'Draw a new polygon every
                                'three seconds.
    PRINT "Press any key to end program"
    INPUT "Press <RETURN> to start",Test$

    DO
    LOOP WHILE INKEY$=""     'End program if any key pressed.

    END

    Drawpoly:
        CLS            'Erase old polygon.
        N = INT(5*RND + 2)      'N is random number from 2 to 6.
        FOR I = 0 TO N
        X(I) = INT(RND*319)   'Get coordinates of vertices of
        Y(I) = INT(RND*199)   'polygon.
        NEXT
        PSET (X(N),Y(N))
        FOR I = 0 TO N
        LINE -(X(I),Y(I)),2   'Draw new polygon.
        NEXT
        RETURN


────────────────────────────────────────────────────────────────────────────
ON ERROR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables error handling and specifies the first line of the error-handling
    routine

■ Syntax

    ON ERROR GOTO line

■ Remarks

    The line argument is the line number or line label of the first line in
    the error-handling routine. This line must appear in module-level code.

    If line cannot be found in the module where the error occurred, or if
    there is no ON ERROR GOTO statement, a backward search is made through the
    modules that invoked the module with the error. If an active error handler
    is found, it is used. If no active error handler is found, an error
    message is printed and program execution halts. The specific error message
    depends on the type of error.

    Only modules in the invocation path are searched. Modules outside the path
    are not searched, even if there is no active error handler in the search
    path.

    A line number of 0 disables error handling. It does not specify line 0 as
    the start of the error-handling code, even if the program contains a line
    numbered 0. Subsequent errors print an error message and halt the program.
    Once error handling is enabled, any error that can be trapped causes a
    jump to the specified error-handling routine.

    Inside an error handler, executing an ON ERROR statement with a line
    number of 0 halts program execution and prints the error message for the
    error that caused the trap. This is a convenient way to halt a program in
    response to errors that cannot be processed by the error-handling routine.

    Note that an error-handling routine is not a SUB or FUNCTION procedure or
    a DEF FN function. An error-handling routine is a module-level block of
    code marked by a line label or line number.

────────────────────────────────────────────────────────────────────────────
NOTE
    Errors occurring within an error-handling routine are not trapped. These
    errors halt program execution after printing an error message.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    Compiling from the BC command line requires additional options when you
    use ON ERROR GOTO. BASICA does not require any additional options. If a
    program contains ON ERROR GOTO or RESUME linenumber statements, you must
    use the On Error /E compile option when compiling from the BC command
    line. If a program contains the statements RESUME, RESUME NEXT, or RESUME
    0, you must also use the Resume Next /X compile option when compiling from
    the command line. No compile options are required when compiling within
    the QuickBASIC environment.

■ See Also

    ERR, ERL; ERROR; RESUME

■ Example

    The following program gets a file name from the user and displays the file
    on the screen. If the file cannot be opened, an error-handling routine
    traps the error and starts the program again at the prompt for the file
    name.

    DEFINT A-Z

    ' Establish the error-handling routine.
    ON ERROR GOTO ErrorHandler

    CLS

    ' Get a file name.
    INPUT "Enter the file to display: ",filename$
    ' Open the file.
    OPEN filename$ FOR INPUT AS #1

    ' Display the file on the screen.
    DO WHILE NOT EOF(1)
        LINE INPUT #1, aline$
        PRINT aline$
    LOOP

    END

    ' Error handling routine handles only "Bad file name,"
    ' aborts on any other error.

    CONST BADFILENAME=64

    ErrorHandler:
        IF ERR=BADFILENAME THEN
        ' Get another file name.
        PRINT "File "; UCASE$(filename$); " not found."
        INPUT "Enter the file to display: ",filename$
        RESUME
        ELSE
        ' Some other error, so print message and abort.
        PRINT "Unrecoverable error--";ERR
        ON ERROR GOTO 0
        END IF


────────────────────────────────────────────────────────────────────────────
ON...GOSUB, ON...GOTO Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    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 }

■ Remarks

    The expression argument can be any numeric expression (expression is
    rounded to an integer before the ON...GOSUB or ON...GOTO is evaluated).
    The line-number-list or line-label-list consists of a list of line numbers
    or line labels, separated by commas. The value of expression determines
    which line the program branches to. For example, if the value is 3, the
    third line specified in the list is the destination of the branch.

    The value of expression should be greater than or equal to 1 and less than
    or equal to the number of items in the list. If the value falls outside
    this range, one of the following results occurs:

    Value                                            Result
    ──────────────────────────────────────────────────────────────────────────
    Number equal to 0 or greater than number of      Control drops to the next
    items in list                                    BASIC statement.

    Negative number or a number greater than 255     An error message appears
                                                    that reads Illegal
                                                    function call.
    ──────────────────────────────────────────────────────────────────────────

    You may mix line numbers and labels in the same list.

────────────────────────────────────────────────────────────────────────────
NOTE
    The ON...GOTO statement accepts a maximum of 60 line labels or line
    numbers. The SELECT CASE statement provides a more powerful, convenient,
    and flexible way to do multiple branches.
────────────────────────────────────────────────────────────────────────────

■ See Also

    GOSUB, RETURN, SELECT CASE

■ Example

    The following program fragment causes program control to branch to one of
    the four subroutines listed, depending on the value of Chval:

    DO
        CLS
        PRINT "1) Display attendance at workshops."
        PRINT "2) Calculate total registration fees paid."
        PRINT "3) Print mailing list."
        PRINT "4) End program."
        PRINT : PRINT "What is your choice?"
        DO
            Ch$=INKEY$
        LOOP WHILE Ch$=""
        Chval = VAL(Ch$)
        IF Chval > 0 AND Chval < 5 THEN
            ON Chval GOSUB Shop, Fees, Mailer, Progend
        END IF
    LOOP
    END
    .
    .
    .


────────────────────────────────────────────────────────────────────────────
ON UEVENT GOSUB Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines the event-handler for a user-defined event

■ Syntax

    ON UEVENT GOSUB { linenumber | linelabel }

■ Remarks

    The linenumber or linelabel argument is the number or label of the first
    line in the event-handling routine. ON UEVENT GOSUB lets your program
    branch to an event-handling routine when a user-defined event occurs. The
    event is usually a hardware interrupt.

    This gives user-defined events one of the features enjoyed by the COM,
    KEY, and other events in BASIC. Once these events have been defined with
    an ON event statement, they act like interrupts. The program does not need
    to poll for the event.

    Likewise, once ON UEVENT GOSUB and UEVENT ON have been executed, the
    user-defined event automatically triggers execution of the BASIC routine
    to handle it. The program does not have to poll.

    At least two (and sometimes three) pieces of code are needed to set up a
    user-defined event. The first is the interrupt service routine. The second
    is an initialization routine to insert the address of the service routine
    into the interrupt vector table. The third is the routine your BASIC
    program calls to retrieve the data (if any) collected by the interrupt
    service routine.

    If the initialization routine "steals" an interrupt used by another
    service routine, the original address must be restored before your program
    terminates.

    These routines are usually written in assembly language. However, any
    language whose compiler can generate interrupt service routines and whose
    object code can be linked with BASIC may be used.

    There are four steps in creating a user-defined event:

    1. Write an event-handling routine and add it to your BASIC program.

    2. Execute the ON UEVENT GOSUB statement to specify the user-event
        handling routine.

    3. Execute the UEVENT ON statement to enable user-event trapping.

    4. Call the interrupt-initialization routine to insert the address of the
        interrupt service routine into the interrupt vector table.

    You're now ready for the interrupt when it occurs. The interrupt transfers
    execution to the interrupt service routine. The service routine collects
    and stores the data the user wants. It then calls SetUEvent.

    SetUEvent sets a flag checked by QuickBASIC before going to the next BASIC
    statement (or label if executing compiled code using /W instead of /V).
    When the flag is set, control transfers to the event-handling routine
    designated in ON UEVENT GOSUB.

    The SetUEvent procedure is a part of BASIC, and is automatically included
    in compiled applications or when running QuickBASIC with the /L
    command-line option. Your interrupt service routine must call SetUEvent;
    it is the only way to alert your program that the event has occurred. You
    can call SetUEvent from any language, not just from assembly language.

    SetUEvent is not a function; it cannot return a value to BASIC. If you
    wish to return a value, you must write a function for your BASIC program
    to call. (It would usually be called by your event-handling routine.) This
    function must be described in a DECLARE statement so your BASIC program
    can find and use it.

    Although ON UEVENT GOSUB ties an event-handling routine to a user-defined
    event, it does not enable the event trap. The UEVENT statement is used to
    enable, disable, and suspend user-defined event trapping.

■ See Also

    UEVENT

■ Example

    The following example illustrates the use of ON UEVENT GOSUB:

    DECLARE SUB test (a)
    ON UEVENT GOSUB Event1
    UEVENT ON
    INPUT "Enter a number";a
    CALL test(a)
    END
    Event1:
    PRINT "Got to the event handler"
    RETURN
    SUB test(a)
    IF a=5 THEN CALL SetUEvent
    END SUB


────────────────────────────────────────────────────────────────────────────
OPEN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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»

■ Remarks

    The file is a string expression that specifies an optional device,
    followed by a file name or path name conforming to the DOS file-naming
    conventions.

    You must open a file before any I/O operation can be performed on it. OPEN
    allocates a buffer for I/O to the file or device and determines the mode
    of access used with the buffer.

    SYNTAX 1

    In the first syntax, mode1 is one of the following:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Mode                     Description
    ──────────────────────────────────────────────────────────────────────────
    OUTPUT                   Specifies sequential output mode.

    Mode                     Description
    ──────────────────────────────────────────────────────────────────────────

    INPUT                    Specifies sequential input mode.

    APPEND                   Specifies sequential output mode and sets the
                            file pointer to the end of file and the record
                            number to the last record of the file. A PRINT #
                            or WRITE # statement then extends (appends to)
                            the file.

    RANDOM                   Specifies random-access file mode, the default
                            mode. In RANDOM mode, if no ACCESS clause is
                            present, three attempts are made to open the file
                            when the OPEN statement is executed. Access is
                            attempted in the following order:

                            1. Read/write

                            2. Write-only

    Mode                     Description
    ──────────────────────────────────────────────────────────────────────────

                            3. Read-only

    BINARY                   Specifies binary file mode. In binary mode, you
                            may read or write information to any byte
                            position in the file using GET and PUT.
                            In binary mode, if no ACCESS clause is present,
                            three attempts are made to open the file. The
                            attempts follow the same order as those for
                            RANDOM files.
    ──────────────────────────────────────────────────────────────────────────


    If mode1 is omitted, the default random-access mode is assumed.

    The access expression specifies the operation performed on the opened
    file. If the file is already opened by another process and the specified
    type of access is not allowed, the OPEN fails and an error message is
    generated that reads Permission denied. The ACCESS clause works in an OPEN
    statement only if you are using a version of DOS that supports networking
    (DOS Versions 3.0 or later). In addition, you must run the SHARE.EXE
    program (or the network startup program must run it) to perform any
    locking operation. If ACCESS is used with OPEN, earlier versions of DOS
    return an error message that reads Advanced feature unavailable.

    The access argument can be one of the following:

    Access Type              Description
    ──────────────────────────────────────────────────────────────────────────
    READ                     Opens the file for reading only.

    WRITE                    Opens the file for writing only.

    READ WRITE               Opens the file for both reading and writing. This
                            mode is valid only for RANDOM and BINARY files
                            and files opened for APPEND.
    ──────────────────────────────────────────────────────────────────────────

    The lock clause works in a multiprocessing environment to restrict access
    by other processes to an open file. The lock types are as follows:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Lock Type                Description
    ──────────────────────────────────────────────────────────────────────────
    Default                  If locktype is not specified, the file may be
                            opened for reading and writing any number of
                            times by this process, but other processes are
                            denied access to the file while it is opened.

    SHARED                   Any process on any machine may read from or write
                            to this file. Do not confuse the SHARED lock type
                            with the SHARED statement or the SHARED attribute
                            appearing in other statements.

    LOCK READ                No other process is granted read access to this
                            file. This access is granted only if no other
                            process has a previous READ access to the file.

    LOCK WRITE               No other process is granted write access to this
                            file. This lock is granted only if no other
                            process has a previous WRITE access to the file.
    Lock Type                Description
    ──────────────────────────────────────────────────────────────────────────
                            process has a previous WRITE access to the file.

    LOCK READ WRITE          No other process is granted either read or write
                            access to this file. This access is granted only
                            if READ or WRITE access has not already been
                            granted to another process, or if a LOCK READ or
                            LOCK WRITE is not already in place.
    ──────────────────────────────────────────────────────────────────────────


    When the OPEN is restricted by a previous process, it generates error 70,
    Permission denied, under DOS.

    The filenum (file number) argument is an integer expression whose value is
    between 1 and 255. When an OPEN is executed, the file number is associated
    with the file as long as it is open. Other I/O statements may use the
    number to refer to the file.

    The reclen (record length) argument is an integer expression that, if
    included, sets the record length (number of characters in one record) for
    random-access files. For sequential files, the default length for records
    is 512 bytes; for random-access files, the default is 128 bytes. The value
    of reclen cannot exceed 32,767 bytes. If the file mode is binary, then the
    LEN clause is ignored.

    For sequential files, reclen need not correspond to an individual record
    size, since a sequential file may have records of different sizes. When
    used to open a sequential file, reclen specifies the number of characters
    to be loaded into the buffer before the buffer is written to, or read
    from, the disk. A larger buffer means more room taken from BASIC, but
    faster file I/O. A smaller buffer means more room in memory for BASIC, but
    slower I/O. The default buffer size is 512 bytes.

    SYNTAX 2

    In the second form of the OPEN syntax, mode2 is a string expression the
    first character of which must be one of the following:

    Mode                     Description
    ──────────────────────────────────────────────────────────────────────────
    O                        Specifies sequential output mode.

    I                        Specifies sequential input mode.

    R                        Specifies random-access file input/output mode.

    B                        Specifies binary file mode.

    A                        Specifies sequential output mode and sets the
                            file pointer to the end of the file and the
                            record number to the last record of the file. A
                            PRINT # or WRITE # statement extends (appends to)
                            the file.
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    The second form of the OPEN syntax does not support any of the access and
    file-sharing options found in the first syntax and is supported for
    compatibility with programs written in earlier versions of BASIC.
────────────────────────────────────────────────────────────────────────────

    The following devices are supported by BASIC and can be named and opened
    with the file argument: KYBD:, SCRN:, COMn:, LPTn:, CONS:.

    The BASIC file I/O system allows you to take advantage of user-installed
    devices. (See your DOS manual for information on character devices.)

    Character devices are opened and used in the same manner as disk files.
    However, characters are not buffered by BASIC as they are for disk files.
    The record length for the device files is set to one.

    BASIC only sends a carriage return at the end of a line. If the device
    requires a line feed, the driver must provide it. When writing device
    drivers, keep in mind that other BASIC users will want to read and write
    control information. The writing and reading of device-control data is
    handled by the IOCTL statement and IOCTL$ function.

    None of the BASIC devices directly supports binary mode. However, the line
    printer devices (LPT1:, LPT2:) can be opened in binary mode by adding the
    BIN keyword:

    OPEN "LPT1:BIN" FOR OUTPUT AS #1

    Opening a printer in BIN mode eliminates printing a carriage return at the
    end of a line.

────────────────────────────────────────────────────────────────────────────
NOTE
    In INPUT, RANDOM, and BINARY modes you can open a file under a different
    file number without first closing the file. In OUTPUT or APPEND mode you
    must close a file before opening it with a different file number.
────────────────────────────────────────────────────────────────────────────

■ See Also

    FREEFILE

■ Examples

    The following statement opens MAILING.DAT as file number 1 and allows data
    to be added without destroying what is already in MAILING.DAT:

    OPEN "MAILING.DAT" FOR APPEND AS #1

    If you wrote and installed a device driver named ROBOT, then the OPEN
    statement might appear as

    OPEN "\DEV\ROBOT" FOR OUTPUT AS #1

    To open the printer for output, you could use either of the following two
    lines. (The first line uses the BASIC device LPT1: while the second line
    uses the DOS device LPT1.)

    OPEN "LPT1:" FOR OUTPUT AS #1

    OPEN "LPT1" FOR OUTPUT AS #1

    The following statement opens the file RECORDS in random-access mode, for
    reading only. The statement locks the file for writing, but allows reading
    by other processes while the OPEN is in effect.

    OPEN "RECORDS" FOR RANDOM ACCESS READ LOCK WRITE AS #1

    The following example opens the file named INVEN for input as file number
    2:

    OPEN "I",2,"INVEN"


────────────────────────────────────────────────────────────────────────────
OPEN COM Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Opens and initializes a communications channel for I/O

■ Syntax

    OPEN "COMn: optlist1 optlist2" «FOR mode» AS «#»filenum «LEN=reclen»

■ Remarks

    COMn: is the name of the device to be opened. The n argument is the number
    of a legal communications device, such as COM1: or COM2:. The first list
    of options, optlist1, has the following form:

    «speed»«,«parity» «,«data»«,«stop»»»»

    The following list describes the possible options:

    Option                   Description
    ──────────────────────────────────────────────────────────────────────────
    speed                    The "baud" rate (baud means "bits per second") of
                            the device to be opened. Valid speeds are 75,
                            110, 150, 300, 600, 1200, 1800, 2400, 4800, and
                            9600. The default is 300 bps.

    parity                   The parity of the device to be opened. Valid
                            entries for parity are: N (none), E (even), O
                            (odd), S (space), or M (mark).

    data                     The number of data bits per byte. Valid entries
                            are 5, 6, 7, or 8.

    stop                     The number of stop bits. Valid entries are 1,
                            1.5, or 2.
    ──────────────────────────────────────────────────────────────────────────

    Options from this list must be entered in the order shown; moreover, if
    any options from optlist2 are chosen, comma placeholders must still be
    used even if none of the options from optlist1 are chosen. For example:

    OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1

    If you set the data bits per byte to eight, you must specify no parity
    (N). Because QuickBASIC uses complete bytes (eight bits) for numbers, you
    must specify eight data bits when transmitting or receiving numeric data.

    The choices for optlist2 are described in the following list. The argument
    m is given in milliseconds; the default value for m is 1000.

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Option                   Description
    ──────────────────────────────────────────────────────────────────────────
    ASC                      Opens the device in ASCII mode. In ASCII mode,
    Option                   Description
    ──────────────────────────────────────────────────────────────────────────
    ASC                      Opens the device in ASCII mode. In ASCII mode,
                            tabs are expanded to spaces, carriage returns are
                            forced at end-of-line, and CTRL+Z is treated as
                            end-of-file. When the channel is closed, CTRL+Z
                            is sent over the RS-232 line.

    BIN                      Opens the device in binary mode. This option
                            supersedes the LF option. BIN is selected by
                            default unless ASC is specified.
                            In the BIN mode, tabs are not expanded to spaces,
                            a carriage return is not forced at the
                            end-of-line, and CTRL+Z is not treated as
                            end-of-file. When the channel is closed, CTRL+Z
                            will not be sent over the RS-232 line.

    CD«m»                    Controls the timeout on the Data Carrier Detect
                            line (DCD). If DCD is low for more than m
                            milliseconds, a device timeout occurs.

    Option                   Description
    ──────────────────────────────────────────────────────────────────────────

    CS«m»                    Controls the timeout on the Clear To Send line
                            (CTS). If CTS is low (there is no signal) for
                            more than m milliseconds, a device timeout
                            occurs.

    DS«m»                    Controls the timeout on the Data Set Ready line
                            (DSR). If DSR is low for more than m
                            milliseconds, a device timeout occurs.

    LF                       Allows communication files to be printed on a
                            serial line printer. When LF is specified, a
                            line-feed character (0AH) is automatically sent
                            after each carriage-return character (0DH). This
                            includes the carriage return sent as a result of
                            the width setting. Note that INPUT and LINE
                            INPUT, when used to read from a COM file that was
                            opened with the LF option, stop when they see a
                            carriage return, ignoring the line feed.
    Option                   Description
    ──────────────────────────────────────────────────────────────────────────
                            carriage return, ignoring the line feed.

    OP«m»                    Controls how long the statement waits for the
                            open to be successful. The parameter m is a value
                            in the range 0 to 65,535 representing the number
                            of milliseconds to wait for the communications
                            lines to become active. If OP is specified
                            without a value, the statement waits
                            indefinitely. If OP is omitted, OPEN COM waits
                            for ten times the maximum value of the CD or DS
                            timeout values.

    RB«n»                    Sets the size of the receive buffer to n bytes.
                            If n is omitted, or the option is omitted, the
                            current value is used. The current value can be
                            set by the /C option on the QuickBASIC or BC
                            command line. The default is 512 bytes. The
                            maximum size is 32,767 bytes.

    Option                   Description
    ──────────────────────────────────────────────────────────────────────────

    RS                       Suppresses detection of Request To Send (RTS).

    TB«n»                    Sets the size of the transmit buffer to n bytes.
                            If n is omitted, or the option is omitted, the
                            current value is used. The default size is 512
                            bytes.
    ──────────────────────────────────────────────────────────────────────────


    The options from the list above can be entered in any order, but they must
    be separated from one another by commas. For CS«m», DS«m», and CD«m», if
    there is no signal within m milliseconds, a timeout occurs. The value for
    m may range from 0 to 65,535, with 1000 as the default value. (The CD
    default is 0.) If m is equal to 0 for any of these options the option is
    ignored. The CTS line is checked whenever there is data in the transmit
    buffer if the CS option is specified. The DSR and DCD lines are
    continuously checked for timeouts if the corresponding options (DS, CD)
    are specified.

    The mode argument is one of the following string expressions:

    Mode                     Description
    ──────────────────────────────────────────────────────────────────────────
    OUTPUT                   Specifies sequential output mode
    INPUT                    Specifies sequential input mode
    RANDOM                   Specifies random-access mode
    ──────────────────────────────────────────────────────────────────────────

    If the mode expression is omitted, it is assumed to be random-access
    input/output. The filenum is the number used to open the file. The OPEN
    COM statement must be executed before a device can be used for
    communication using an RS-232 interface.

    If the device is opened in RANDOM mode, the LEN option specifies the
    length of an associated random-access buffer. The default value for length
    is 128. You can use any of the random-access I/O statements, such as GET
    and PUT, to treat the device as if it were a random-access file. The OPEN
    COM statement performs the following steps in opening a communications
    device:

    1. The communications buffers are allocated and interrupts are enabled.

    2. The Data Terminal Ready line (DTR) is set high.

    3. If either of the OP or DS options is nonzero, the statement waits up to
        the indicated time for the Data Set Ready line (DSR) to be high. If a
        timeout occurs, the process goes to step 6.

    4. The Request To Send line (RTS) is set high if the RS option is not
        specified.

    5. If either of the OP or CD options is nonzero, OPEN COM waits up to the
        indicated time for the Data Carrier Detect line (DCD) to be high. If a
        timeout occurs, the process goes to step 6. Otherwise, OPEN COM has
        succeeded.

    6. The open has failed due to a timeout. The process deallocates the
        buffers, disables interrupts, and clears all of the control lines.

────────────────────────────────────────────────────────────────────────────
NOTE
    Use a relatively large value for the OP option compared to the CS, DS, or
    CD options. If two programs are attempting to establish a communications
    link, they both need to attempt an OPEN during at least half of the time
    they are executing.
────────────────────────────────────────────────────────────────────────────

    Any syntax errors in the OPEN COM statement produce an error message that
    reads Bad file name.

■ Example

    The following program fragment opens communications channel 1 in
    random-access mode at a speed of 9600 baud, no parity bit, eight data
    bits, and one stop bit. Input/output will be in the binary mode. Other
    lines in the program can now access channel 1 as file number 2.

    OPEN "COM1:9600,N,8,1,BIN" AS 2


────────────────────────────────────────────────────────────────────────────
OPTION BASE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Declares the default lower bound for array subscripts

■ Syntax

    OPTION BASE n

■ Remarks

    The OPTION BASE statement is never required. It is used to change the
    default lower bound for array subscripts.

    The value of n must be either 0 or 1. The default base is 0. If the
    following statement

    OPTION BASE 1

    is executed, the lowest value an array subscript can have is 1.

────────────────────────────────────────────────────────────────────────────
NOTE
    The TO clause in the DIM statement provides an easier, more flexible way
    to control the range of an array's subscripts. If the lower bound of an
    array subscript is not explicitly set, then OPTION BASE can be used to
    change the default lower bound to 1.
────────────────────────────────────────────────────────────────────────────

    The OPTION BASE statement can be used only once in a module (source file)
    and can only appear in the module-level code. An OPTION BASE statement
    must be used before any arrays are dimensioned.

    Chained programs may have an OPTION BASE statement if no arrays are passed
    in COMMON between them or if the specified base is identical in the
    chained programs. The chained-to program inherits the OPTION BASE value of
    the chaining program if OPTION BASE is omitted in the latter.

■ See Also

    DIM, LBOUND, REDIM

■ Example

    The following statement overrides the default value of zero, so the lowest
    value a subscript in an array can have in this program is 1:


    OPTION BASE 1
    DIM A(20)
    PRINT LBOUND(A), UBOUND(A)

■ Output

    1               20


────────────────────────────────────────────────────────────────────────────
OUT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sends a byte to a machine I/O port

■ Syntax

    OUT port, data

■ Remarks

    The following list describes the arguments of the OUT statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    port                     The number of the port. The number must be an
                            integer expression in the range 0-65,535.

    data                     The data to be sent to the port. It must be an
                            integer expression in the range 0-255.
    ──────────────────────────────────────────────────────────────────────────

    The OUT and INP statements give a BASIC program direct control over the
    hardware in a system through the I/O ports. These statements must be used
    carefully because they directly manipulate the hardware.

■ See Also

    INP, WAIT

■ Example

    The following example uses OUT and INP to control the timer and speaker to
    produce a note. (This example is specific to the IBM PC and close
    compatibles and produces unpredictable results on other machines.)

    ' Play a scale using the speaker and timer.
    CONST WHOLE=5000!, QRTR=WHOLE/4.
    CONST C=523.0, D=587.33, E=659.26, F=698.46, G=783.99, A=880.00
    CONST B=987.77, C1=1046.50
    CALL Sounds(C,QRTR) : CALL Sounds(D,QRTR)
    CALL Sounds(E,QRTR) : CALL Sounds(F,QRTR)
    CALL Sounds(G,QRTR) : CALL Sounds(A,QRTR)
    CALL Sounds(B,QRTR) : CALL Sounds(C1,WHOLE)

    ' Use ports 66, 67, and 97 to control the timer and speaker
    ' to produce a sound.
    SUB Sounds (Freq!,Length!) STATIC

    ' Divide the clock frequency by the sound frequency to
    ' get the number of "clicks" the clock must produce.
        Clicks%=CINT(1193280!/Freq!)
        LoByte%=Clicks% AND &H00FF
        HiByte%=Clicks%\256
    ' Tell timer that data is coming.
        OUT 67,182
    ' Send the low byte followed by the high byte of the count.
        OUT 66,LoByte%
        OUT 66,HiByte%
    ' Turn the speaker on by setting bits 0 and 1 of the PPI chip.
    ' Get the current value, and turn the bits on.
        SpkrOn%=INP(97) OR &H03
        OUT 97,SpkrOn%
    ' Leave the speaker on for a while.
        FOR I!=1 TO Length! : NEXT I!
    ' Turn the speaker off.
        SpkrOff%=INP(97) AND &HFC
        OUT 97,SpkrOff%

    END SUB


────────────────────────────────────────────────────────────────────────────
PAINT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Fills a graphics area with the color or pattern specified

■ Syntax

    PAINT «STEP» (x,y)«,«paint» «,«bordercolor» «,background»»»

■ Remarks

    The following list describes the parts of the PAINT statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    STEP                     Defines coordinates to be relative to the most
                            recently plotted point. For example, if the last
                            point plotted were (10,10), then the coordinates
                            referred to by STEP (4,5) would be (4+10, 5+10)
                            or (14,15).

    (x,y)                    The coordinates where painting begins. The point
                            must be inside or outside a figure, not on the
                            border itself. If this point is inside, the
                            figure's interior is painted; if the point is on
                            the outside, the background is painted.

    paint                    A numeric or string expression. If paint is a
                            numeric expression, then the number must be a
                            valid color attribute. The corresponding color is
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            valid color attribute. The corresponding color is
                            used to paint the area. If you do not specify
                            paint, the foreground color attribute is used.
                            (See the COLOR, PALETTE, and SCREEN statements
                            for discussions of valid colors, numbers, and
                            attributes.)

                            If the paint argument is a string expression,
                            then PAINT does "tiling," a process that paints a
                            pattern rather than a solid color. Tiling is
                            similar to "line styling," which creates dashed
                            lines rather than solid lines.

    bordercolor              A numeric expression identifying the color
                            attribute to use to paint the border of the
                            figure. When the border color is encountered,
                            painting of the current line stops. If the border
                            color is not specified, the paint argument is
                            used.
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            used.

    background               A string value giving the "background tile slice"
                            to skip when checking for termination of the
                            boundary. Painting is terminated when adjacent
                            points display the paint color. Specifying a
                            background tile slice allows you to paint over an
                            already painted area. When you omit background
                            the default is CHR$ (0).
    ──────────────────────────────────────────────────────────────────────────


    Painting is complete when a line is painted without changing the color of
    any pixel, in other words, when the entire line is equal to the paint
    color. The PAINT command permits coordinates outside the screen or
    viewport.

    Tiling

    "Tiling" is the design of a PAINT pattern that is eight bits wide and up
    to 64 bytes long. In the tile string, each byte masks eight bits along the
    x-axis when putting down points. The syntax for constructing this tile
    mask is

    PAINT (x,y), CHR$(arg1)+CHR$(arg2)+...+CHR$(argn)

    The arguments to CHR$ are numbers between 0 and 255, represented in binary
    form across the x axis of the tile. There can be up to 64 of these CHR$
    elements; each generates an image not of the assigned character, but of
    the bit arrangement of the code for that character. For example, the
    decimal number 85 is binary 01010101; the graphic image line on a
    black-and-white screen generated by CHR$(85) is an eight-pixel line, with
    even-numbered points white and odd-numbered points black. That is, each
    bit equal to 1 turns the associated pixel on and each bit equal to 0 turns
    the associated bit off in a black-and-white system. The ASCII character
    CHR$(85), which is U, is not displayed in this case.

    When supplied, background defines the "background tile slice" to skip when
    checking for boundary termination. You cannot specify more than two
    consecutive bytes that match the tile string in the tile background slice.
    Specifying more than two consecutive bytes produces an error message that
    reads Illegal function call.

    Tiling can also be done to produce various patterns of different colors.
    See Chapter 5, "Graphics," in Programming in BASIC for a complete
    description of how to do tiling.

■ See Also

    CHR$, CIRCLE, DRAW, LINE, SCREEN

■ Example

    The following program draws a magenta fish with a cyan tail:

    CONST PI=3.1415926536
    CLS
    SCREEN 1

    CIRCLE (190,100),100,1,,,.3   'Outline fish body in cyan.
    CIRCLE (265,92),5,1,,,.7      'Outline fish eye in cyan.
    PAINT (190,100),2,1           'Fill in fish body with magenta.

    LINE (40,120)-STEP (0,-40),2  'Outline
    LINE -STEP (60,+20),2         '   tail in
    LINE -STEP (-60,+20),2        '      magenta.
    PAINT (50,100),1,2            'Paint tail cyan.

    CIRCLE (250,100),30,0,PI*3/4,PI* 5/4,1.5  'Draw
    gills in black.
    FOR Y = 90 TO 110 STEP 4
        LINE (40,Y)-(52,Y),0       'Draw comb in tail.
    NEXT


────────────────────────────────────────────────────────────────────────────
PALETTE, PALETTE USING Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Changes one or more of the colors in the palette

■ Syntax

    PALETTE «attribute,color»
    PALETTE USING array-name «(array-index)»

■ Remarks

    The PALETTE statement takes the following arguments:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    attribute                The palette attribute to be changed.

    color                    The display color number to be assigned to the
                            attribute. The color must be a long integer
                            expression for the IBM Video Graphics Array
                            adapter (VGA) and IBM Multicolor Graphics Array
                            adapter (MCGA) in screen modes 11 to 13. Integer
                            or long-integer expressions may be used with the
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            or long-integer expressions may be used with the
                            IBM Enhanced Graphics Adapter (EGA).

    array-name               An array containing the color numbers to be
                            assigned to the attributes available in the
                            current screen mode. The VGA and MCGA adapters
                            require a long integer array in screen modes 11
                            to 13. With the EGA this can be either an integer
                            or long-integer array.

    array-index              The index of the first array element to use in
                            setting the palette.
    ──────────────────────────────────────────────────────────────────────────


    The PALETTE statement works only on systems equipped with the EGA, VGA, or
    MCGA adapters.

    The statement provides a way of mapping display colors (the actual binary
    values used by the adapter) to color attributes (a smaller set of values).
    All BASIC graphics statements such as CIRCLE, COLOR, DRAW, or LINE use
    color attributes rather than display-color values.

    When a program enters a screen mode, the attributes are set to a series of
    default color values. (See the SCREEN statement for a list of the default
    colors.) In the EGA, VGA, and MCGA adapters these default values have been
    selected so the display shows the same colors, even though the EGA uses
    different color values.

    With the palette statement you can assign different colors to the
    attributes, giving you greater control over the colors on the display. A
    PALETTE statement with no arguments sets the palette back to the default
    color values.

    When you execute a PALETTE statement with arguments, the adapter
    subsequently uses the display color (indicated by color) whenever the
    value attribute appears in a statement like DRAW or LINE that specifies a
    color. Changing the display color assigned to an attribute changes the
    color on the screen immediately.

    For example, assume that the current palette contains colors 0, 1, 2, and
    3 in the four attributes numbered 0, 1, 2, and 3. The DRAW statement

    DRAW "C3L100"

    selects attribute 3, and draws a line of 100 pixels using the display
    color associated with attribute 3, in this case also 3. If the statement

    PALETTE 3,2

    is executed, then the color associated with attribute 3 is changed to
    color 2. All text or graphics currently on the screen displayed using
    attribute 3 are instantaneously changed to color 2. Text or graphics
    subsequently displayed with attribute 3 are also displayed in color 2. The
    new palette of colors contains 0, 1, 2, and 2.

    With the USING option, all entries in the palette can be modified in one
    PALETTE statement. The array-name argument is the name of an integer or
    long-integer array and the array-index specifies the index of the first
    array element in the array-name to use in setting the palette. Each
    attribute in the palette is assigned a corresponding color from this
    array. The array must be dimensioned large enough to set all the palette
    entries after array-index. For example, if you are assigning colors to all
    16 attributes, and the index of the first array element that is given in
    your PALETTE USING statement is 5, then the array must be dimensioned to
    hold at least 20 elements (since the number of elements from 5-20,
    inclusive, is 16):

    DIM PAL%(20)
    .
    .
    .
    PALETTE USING PAL%(5)

    A color argument of -1 in the array leaves the attribute unchanged. All
    other negative numbers are invalid values for color.

    You can use the COLOR statement to set the default foreground color and
    the background display color. The foreground color argument specifies the
    way text characters appear on the display screen. Under a common initial
    palette setting, points colored with the attribute 0 appear black on the
    display screen. Using the PALETTE statement, you could, for example,
    change the mapping of attribute 0 from black to white. Table R.5 lists
    attribute and color ranges for various adapter types and screen modes.

    Table R.5   Screen Color and Attribute Ranges

╓┌─┌───────────┌────────────────────────┌───────────┌────────────┌───────────╖
    Screen      Monitor                              Attribute    Color
    Mode        Attached                 Adapter     Range        Range
    ──────────────────────────────────────────────────────────────────────────
    0           Monochrome               MDPA        0-15         N/A☼
                Monochrome               EGA         0-15         0-2
                Color                    CGA         0-15         N/A
                Color/Enhanced☼          EGA         0-15         0-63
                N/A                      VGA         0-15         0-63
                N/A                      MCGA        0-15         N/A
    1           Color                    CGA         0-3          N/A
                Color/Enhanced☼          EGA         0-3          0-15
                N/A                      VGA         0-3          0-15
                N/A                      MCGA        0-3          N/A
    2           Color                    CGA         0-1          N/A
                Color/Enhanced☼          EGA         0-1          0-15
    Screen      Monitor                              Attribute    Color
    Mode        Attached                 Adapter     Range        Range
    ──────────────────────────────────────────────────────────────────────────
                Color/Enhanced☼          EGA         0-1          0-15
                N/A                      VGA         0-1          0-15
                N/A                      MCGA        0-1          N/A
    7           Color/Enhanced☼          EGA         0-15         0-15
                N/A                      VGA         0-15         0-15
    8           Color/Enhanced☼          EGA         0-15         0-15
                N/A                      VGA         0-15         0-15
    9           Enhanced☼                EGA☼        0-3          0-63
                Enhanced☼                EGA☼        0-15         0-63
                N/A                      VGA         0-16         0-63
    10          Monochrome               EGA         0-3          0-8
                N/A                      VGA         0-3          0-8
    11          N/A                      VGA         0-1          0-262,143☼
                N/A                      MCGA        0-1          0-262,143☼
    12          N/A                      VGA         0-15         0-262,143☼
    13          N/A                      VGA         0-255        0-262,143☼
                N/A                      MCGA        0-255        0-262,143☼
    ──────────────────────────────────────────────────────────────────────────
    Screen      Monitor                              Attribute    Color
    Mode        Attached                 Adapter     Range        Range
    ──────────────────────────────────────────────────────────────────────────
    ──────────────────────────────────────────────────────────────────────────


    The VGA uses a different way of calculating color values from the EGA. To
    calculate a color value, select the intensities of red, green, and blue.
    The intensity of a color is a number from 0 (low intensity) to 63 (high
    intensity). Then use the following formula to calculate the actual color
    number:

    color number = 65536 * blue + 256 * green + red

    Because there are gaps in the range of color numbers, you should use the
    formula rather than just select a number.

    When used with the IBM Analog Monochrome Monitor, the VGA color values are
    converted to a gray-scale value by taking a weighted sum of the red, blue,
    and green intensities as follows:

    gray value = 11% blue + 59% green + 30% red

    For example if the blue, green, and red intensities are 45, 20, and 20,
    the gray value would be .11*45+.59*20+.30*20 or 22 (the fraction in the
    result is dropped).

    See the SCREEN statement for the list of colors available for various
    screen-mode, monitor, and graphics-adapter combinations.

────────────────────────────────────────────────────────────────────────────
NOTE
    Because of their wide range of colors, the VGA and MCGA adapters require a
    long-integer array in the PALETTE USING statement in screen modes 11 to
    13.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CIRCLE, COLOR, DRAW, LINE, SCREEN

■ Examples

    The following lines show the different forms of the PALETTE and PALETTE
    USING statements:

    PALETTE 0,2          'Changes all points colored with attribute 0 to
                        'color 2.

    PALETTE USING A%(0)  'Changes each palette entry. Since the
                        'array is initialized to zero when it
                        'is first declared, all attributes are
                        'now mapped to display color zero. The
                        'screen will now appear as one single
                        'color. However, it will still be
                        'possible to execute BASIC statements.

    PALETTE              'Sets each palette entry to its appropriate
                        'initial display color. Actual initial colors
                        'depend on your screen-hardware configuration.


────────────────────────────────────────────────────────────────────────────
PCOPY Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Copies one screen page to another

■ Syntax

    PCOPY sourcepage, destinationpage

■ Remarks

    The sourcepage is an integer expression in the range 0 to n, where n is
    the maximum number of pages determined by the current video-memory size
    and the size per page for the current screen mode.

    The destinationpage has the same requirements as the sourcepage.

    See the SCREEN statement for more information about the number of pages
    available in different modes.

■ See Also

    CLEAR, SCREEN

■ Example

    The following example copies the contents of page 1 to page 2:

    PCOPY 1,2


────────────────────────────────────────────────────────────────────────────
PEEK Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the byte stored at a specified memory location

■ Syntax

    PEEK(address)

■ Remarks

    The returned value is an integer in the range 0-255. The argument address
    is a value in the range 0-65,535. The argument address is treated as the
    offset from the current default segment (as set by the DEF SEG statement).

    If the argument is a single- or double-precision floating-point value or a
    long integer, it is converted to a two-byte integer.

    The PEEK function complements the POKE statement.

■ See Also

    DEF SEG, POKE, VARPTR

■ Example

    See the example for DEF SEG.


────────────────────────────────────────────────────────────────────────────
PEN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads the lightpen coordinates

■ Syntax

    PEN(n)

■ Remarks

    The argument n indicates what value is to be returned. It is a numeric
    expression in the range 0-9.

────────────────────────────────────────────────────────────────────────────
NOTE
    The PEN function does not work when the mouse driver is enabled because
    the mouse driver uses the PEN function's BIOS calls. Use mouse function 14
    to disable the driver's lightpen emulation. Mouse function 13 turns
    emulation back on. See your mouse manual for more information.
────────────────────────────────────────────────────────────────────────────

    The following list describes the values for n and the corresponding values
    returned by PEN:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    0                        The most recent pen use: -1 if pen was down since
                            last poll, 0 if not

    1                        The x pixel coordinate where pen was last pressed

    2                        The y pixel coordinate where pen was last pressed

    3                        The current pen-switch value: -1 if down, 0 if up

    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────

    4                        The last known valid x pixel coordinate

    5                        The last known valid y pixel coordinate

    6                        The character row position where pen was last
                            pressed

    7                        The character column position where pen was last
                            pressed

    8                        The last known character row where the pen was
                            positioned

    9                        The last known character column where the pen was
                            positioned
    ──────────────────────────────────────────────────────────────────────────


■ Example

    The following example produces an endless loop to print the current
    pen-switch status (UP/DOWN):

    CLS
    PEN ON
    DO
        P = PEN(3)
        LOCATE 1,1 : PRINT "PEN IS ";
        IF P THEN PRINT "DOWN" ELSE PRINT "UP"
        X = PEN(4) : Y = PEN(5)
        PRINT "X =" X, "Y =" Y
    LOOP


────────────────────────────────────────────────────────────────────────────
PEN ON, OFF, and STOP Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables, disables, or suspends lightpen-event trapping

■ Syntax

    PEN ON
    PEN OFF
    PEN STOP

■ Remarks

    The PEN ON statement enables lightpen-event trapping by using an ON PEN
    statement. The pen is initially off. A lightpen event occurs whenever the
    lightpen is activated by pressing the tip to the screen or pressing the
    touch ring. A PEN ON statement must be executed before any read-pen
    function calls. If a read-pen function is called when the pen is off, an
    error message results that reads Illegal function call.

    The PEN OFF statement disables lightpen event trapping. The PEN STOP
    statement suspends lightpen event trapping; a pen event is remembered and
    trapped as soon as event trapping is enabled.

    To speed program execution, the pen should be turned off by using a PEN
    OFF statement when pen trapping is not needed.

────────────────────────────────────────────────────────────────────────────
NOTE
    The lightpen requires an IBM Color Graphics Adapter.
────────────────────────────────────────────────────────────────────────────

■ See Also

    ON event, PEN Function

■ Example

    See the example for the PEN function.


────────────────────────────────────────────────────────────────────────────
PLAY Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Plays music as specified by a string

■ Syntax

    PLAY commandstring

■ Remarks

    The commandstring is a string expression containing one or more of the
    commands listed below.

    The PLAY statement uses a concept similar to DRAW in that it embeds a
    music macro language (described below) in one statement. A set of
    commands, used as part of the PLAY statement, specifies a particular
    action.

    In compiled programs, you should use the VARPTR$(variable) form for
    variables. For example, the BASICA statements

    PLAY "XA$"
    PLAY "O=I"

    should be written for the compiler like this:

    PLAY "X" + VARPTR$(A$)
    PLAY "O=" + VARPTR$(I)

    The commandstring music macros are described as follows:

    Octave Commands          Action
    ──────────────────────────────────────────────────────────────────────────
    o n                      Sets the current octave. There are seven octaves,
                            numbered 0-6.

    >                        Increases octave by 1. Octave cannot go beyond 6.

    <                        Decreases octave by 1. Octave cannot drop below
                            0.

    Tone Commands            Action
    ──────────────────────────────────────────────────────────────────────────
    A-G                      Plays a note in the range A-G. The "#" symbol or
                            the "+" symbol after a note specifies sharp; a
                            "-" specifies flat.

    N n                      Plays note n. The range for n is 0-84 (in the
                            seven possible octaves, there are 84 notes); n =
                            0 means a rest.

    Duration Commands        Action
    ──────────────────────────────────────────────────────────────────────────
    L n                      Sets the length of each note. L4 is a quarter
                            note, L1 is a whole note, etc. The range for n is
                            1-64.
                            The length may also follow the note when a change
                            of length only is desired for a particular note.
                            In this case, A16 is equivalent to L16A.

    MN                       Sets "music normal" so that each note will play
                            7/8 of the time determined by the length (L).

    ML                       Sets "music legato" so that each note will play
                            the full period set by length (L).

    MS                       Sets "music staccato" so that each note will play
                            3/4 of the time determined by the length (L).

    Tempo Commands           Action
    ──────────────────────────────────────────────────────────────────────────
    P n                      Specifies a pause, ranging from 1-64. This option
                            corresponds to the length of each note, set with
                            L n.

    T n                      Sets the "tempo," or the number of L4 quarter
                            notes in one minute. The range for n is 32-255.
                            The default for n is 120.

    Operation Commands       Action
    ──────────────────────────────────────────────────────────────────────────
    MF                       Sets music (PLAY statement) and SOUND to run in
                            the foreground. That is, each subsequent note or
                            sound will not start until the previous note or
                            sound has finished. This is the default setting.

    MB                       Music (PLAY statement) and SOUND are set to run
                            in the background. That is, each note or sound is
                            placed in a buffer, allowing the BASIC program to
                            continue executing while the note or sound plays
                            in the background. The maximum number of notes
                            that can be played in the background at one time
                            is 32.

    Suffixes                 Action
    ──────────────────────────────────────────────────────────────────────────
    # or +                   Follows a specified note and turns it into a
                            sharp.

    -                        Follows a specified note and turns it into a
                            flat.

    .                        A period after a note causes the note to play 3/2
                            times the length determined by L (length) times T
                            (tempo). The period has the same meaning as in a
                            musical score. Multiple periods can appear after
                            a note. Each period adds a length equal to one
                            half the length of the previous period. The
                            command A. plays 1 + 1/2 or 3/2 times the length;
                            A.. plays 1 + 1/2 + 1/4 or 7/4 times the length;
                            and so on. Periods can appear after a pause (P).
                            In this case, the pause length is scaled in the
                            same way notes are scaled.

    Substring Command        Action
    ──────────────────────────────────────────────────────────────────────────
    "X" + VARPTR$(string)    Executes a substring.
    ──────────────────────────────────────────────────────────────────────────

    Because of the slow clock-interrupt rate, some notes will not play at
    higher tempos (L64 at T255, for example).

■ Examples

    The following example uses ">" to play the scales from octave 0 to octave
    6, then reverses with "<" to play the scales from octave 6 to octave 0:

    SCALE$ = "CDEFGAB"
    PLAY "o0 X" + VARPTR$(SCALE$)
    FOR I = 1 TO 6
        PLAY ">X" + VARPTR$(SCALE$)
    NEXT
    PLAY "o6 X" + VARPTR$(SCALE$)
    FOR I = 1 TO 6
        PLAY "<X" + VARPTR$(SCALE$)
    NEXT

    The following example plays the beginning of the first movement of
    Beethoven's Fifth Symphony:

    LISTEN$ = "T180 o2 P2 P8 L8 GGG L2 E-"
    FATE$ = "P24 P8 L8 FFF L2 D"
    PLAY LISTEN$ + FATE$


────────────────────────────────────────────────────────────────────────────
PLAY Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the number of notes currently in the background-music queue

■ Syntax

    PLAY (n)

■ Remarks

    The argument n is a dummy argument and may be any numeric value.

    PLAY(n) will return 0 when the user is in music-foreground mode.

■ See Also

    ON event; PLAY Statement; PLAY ON, OFF, and STOP

■ Example

    See the examples for the ON event statements.


────────────────────────────────────────────────────────────────────────────
PLAY ON, OFF, and STOP Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    These statements are used with the ON PLAY statement to trap play events.
    When a PLAY OFF statement is executed, the event-trapping subroutine is
    not performed and the event is not remembered.

    A PLAY STOP statement does not perform the event-trapping subroutine, but
    the subroutine is performed as soon as a PLAY ON statement is executed.

    When a play event trap occurs (that is, the GOSUB is performed), an
    automatic PLAY STOP is executed so that recursive traps cannot take place.
    The RETURN from the trapping subroutine automatically performs a PLAY ON
    statement unless an explicit PLAY OFF was performed inside the subroutine.

■ Example

    See the entry for the ON event statements for an example of play event
    trapping.


────────────────────────────────────────────────────────────────────────────
PMAP Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Maps view-coordinate expressions to physical locations or maps physical
    expressions to a view-coordinate location

■ Syntax

    PMAP (expression, function)

■ Remarks

    The argument expression indicates the coordinate of the point to be
    mapped. The argument function can have one of the four following values:

    Value                    Description
    ──────────────────────────────────────────────────────────────────────────
    0                        Maps view-coordinate expression to physical
                            x-coordinate

    1                        Maps view-coordinate expression to physical
                            y-coordinate

    2                        Maps physical expression to view x-coordinate

    3                        Maps physical expression to view y-coordinate
    ──────────────────────────────────────────────────────────────────────────

    The four PMAP functions allow the user to find equivalent point locations
    between the view coordinates created with the WINDOW statement and the
    physical coordinate system of the screen or viewport as defined by the
    VIEW statement.

■ See Also

    VIEW, WINDOW

■ Example

    The following fragment uses PMAP to convert coordinate values from view to
    screen coordinates and from screen coordinates to view coordinates:

    SCREEN 2
    'Coordinates of upper-left corner of window defined in follow-
    'ing statement are (80,100); coordinates of lower-right corner
    'are 200,200.
    WINDOW SCREEN (80,100) - (200,200)

    'If physical screen coordinates are (0,0) in the upper-left
    'corner and (639,199) in the lower-right corner, then the
    'following statements will return the screen coordinates
    'equivalent to the view coordinates 80,100.
    X = PMAP(80,0)          'X = 0
    Y = PMAP(100,1)         'Y = 0

    'The following statements will return the screen coordinates
    'equivalent to the view coordinates 200,200.
    X = PMAP(200,0)         'X = 639
    Y = PMAP(200,1)         'Y = 199

    'The following statements will return the view coordinates
    'equivalent to the screen coordinates 639,199.
    X = PMAP(639,2)         'X = 200
    Y = PMAP(199,3)         'Y = 200


────────────────────────────────────────────────────────────────────────────
POINT Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads the color number of a pixel from the screen or returns the pixel's
    coordinates

■ Syntax

    POINT (x,y)
    POINT (number)

■ Remarks

    The coordinates x and y refer to the pixel being evaluated by the POINT
    function. When called with two coordinates, POINT returns the color number
    of the indicated pixel. If the specified pixel is out of range, POINT
    returns the value -1.

    POINT with one argument (as explained in the list below) allows the user
    to retrieve the current graphics-cursor coordinates.

    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    0                        The current physical x-coordinate.

    1                        The current physical y-coordinate.

    2                        The current view x-coordinate. This returns the
                            same value as the POINT(0) function if the WINDOW
                            statement has not been used.

    3                        The current view y-coordinate. This returns the
                            same value as the POINT(1) function if the WINDOW
                            statement has not been used.
    ──────────────────────────────────────────────────────────────────────────

■ Example

    The following example redraws the ellipse drawn with the CIRCLE statement,
    using POINT to find the border of the ellipse by testing for a change in
    color:

    DEFINT X,Y
    INPUT "Enter angle of tilt in degrees (0 to 90): ",Ang
    SCREEN 1         'Medium resolution screen.
    Ang = (3.1415926#/180)*Ang      'Convert degrees to radians.
    Cs = COS(Ang) : Sn = SIN(Ang)
    CIRCLE (45,70),50,2,,,2         'Draw ellipse.
    PAINT (45,70),2                 'Paint interior of ellipse.

    FOR Y = 20 TO 120
        FOR X = 20 TO 70
        'Check each point in rectangle enclosing ellipse.
        IF POINT(X,Y) <> 0 THEN
            'If the point is in the ellipse, plot a corresponding
            'point in the "tilted" ellipse.
            Xnew = (X*Cs - Y*Sn) + 200 : Ynew = (X*Sn + Y*Cs)
            PSET(Xnew,Ynew),2
        END IF
        NEXT
    NEXT
    END


────────────────────────────────────────────────────────────────────────────
POKE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Writes a byte into a memory location

■ Syntax

    POKE address,byte

■ Remarks

    The expression address is a value that represents the address of the
    memory location; address must be in the range 0-65,535. The expression
    byte is the data byte to be written; it is an integer value in the range
    0-255.

    The address is treated as the offset from the current default segment (as
    set by the DEF SEG statement). If the argument is a single- or
    double-precision floating-point value or a long integer, it is converted
    to a two-byte integer.

    The complementary function to POKE is PEEK.

────────────────────────────────────────────────────────────────────────────
WARNING
    Use POKE carefully. If used incorrectly, it can cause BASIC or the
    operating system to fail.
────────────────────────────────────────────────────────────────────────────

■ See Also

    DEF SEG, PEEK, VARPTR

■ Example

    See the example for the DEF SEG statement.


────────────────────────────────────────────────────────────────────────────
POS Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current horizontal position of the cursor

■ Syntax

    POS(0)

■ Remarks

    The leftmost cursor position is numbered 1. To return the current
    vertical-line position of the cursor, use the CSRLIN function.

■ See Also

    CSRLIN, LPOS

■ Example

    The following example uses POS to start input on a new line after every 40
    characters:

    PRINT "This program starts a new line after every forty"
    PRINT "characters are printed. Press <CTRL-C> to end."
    PRINT
    DO
        DO WHILE POS(0) < 41   'Stay on same line until 40 characters
        DO                  'printed.
            Char$=INKEY$
        LOOP WHILE Char$=""
        'If input is key combination CTRL-C then end; otherwise,
        'print the character.
        IF ASC(Char$) = 3 THEN END ELSE PRINT Char$;
        LOOP
        PRINT                  'Print a new line.
    LOOP


────────────────────────────────────────────────────────────────────────────
PRESET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Draws a specified point on the screen

■ Syntax

    PRESET «STEP»(xcoordinate,ycoordinate) «,color»

■ Remarks

    PRESET works exactly like PSET, except that if the color is not specified,
    the background color is selected. The following list describes the parts
    of the PRESET statement:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    STEP                     Indicates that the given x- and y-coordinates are
                            relative, not absolute. The coordinates are
                            treated as distances from the most recent cursor
                            location, not distances from the (0,0) screen
                            coordinate.
                            For example, if the most recent point referenced
                            were (10,10),
                            PRESET STEP (10,5)
                            would reference the point at (20,15).

    xcoordinate              The x-coordinate of the pixel that is to be set.

    ycoordinate              The y-coordinate of the pixel that is to be set.

    color                    The color attribute for the specified point.
    ──────────────────────────────────────────────────────────────────────────

    If a coordinate is outside the current viewport, no action is taken, nor
    is an error message given.

■ See Also

    PSET

■ Example

    The following example draws a line 20 pixels long. The line then moves
    across the screen from left to right:


    SCREEN 1 : COLOR 1,1 : CLS
    FOR I = 0 TO 299 STEP 3
        FOR J = I TO 20+I
            PSET (J,50),2                  'Draw the line in new location.
        NEXT
        FOR J = I TO 20+I
            PRESET (J,50)                  'Erase the line.
        NEXT
    NEXT


────────────────────────────────────────────────────────────────────────────
PRINT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Outputs data on the screen

■ Syntax

    PRINT «expressionlist» «{, | ;}»

■ Remarks

    If expressionlist is omitted, a blank line is printed. If expressionlist
    is included, the values of the expressions are printed on the screen. The
    expressions in the list may be numeric or string expressions. (String
    literals must be enclosed in quotation marks.)

    A printed number is always followed by a space. If the number is positive,
    it is also preceded by a space; if the number is negative, it is preceded
    by a minus sign (-).

    There are two formats that PRINT uses to display single- and
    double-precision numbers: fixed point and floating point. If PRINT can
    represent a single-precision number in the fixed-point format with seven
    or fewer digits and no loss of accuracy, then it uses the fixed-point
    format; otherwise, it uses the floating-point format. For example, the
    number 1.1E-6 is output as .0000011, but the number 1.1E-7 is output as
    1.1E-7.

    Similarly, if PRINT can represent a double-precision number in the
    fixed-point format with 16 or fewer digits and no loss of accuracy, then
    it uses the fixed-point format; otherwise, it uses the floating-point
    format. For example, the number 1.1D-15 is output as .0000000000000011,
    but the number 1.1D-16 is output as 1.1D-16.

    The PRINT statement supports only elementary BASIC data types (integers,
    long integers, single-precision real numbers, double-precision real
    numbers, and strings). To print information in a record, use the PRINT
    statement with individual record elements as in the following fragment:

    TYPE MyType
        Word AS STRING*20
        Count AS LONG
    END TYPE
    DIM Myrec AS MyType

    PRINT Myrec.Word

    PRINT POSITIONS

    The position of each printed item is determined by the punctuation used to
    separate the items in the list. BASIC divides the line into print zones of
    14 spaces each. In the expression list, a comma makes the next value print
    at the start of the next zone. A semicolon makes the next value print
    immediately after the last value. Typing one or more spaces or tabs
    between expressions has the same effect as typing a semicolon.

    If a comma or a semicolon terminates the list of expressions, the next
    PRINT statement prints on the same line, after spacing accordingly. If the
    expression list ends without a comma or a semicolon, a carriage-return and
    line-feed sequence is printed at the end of the line. If the printed line
    is wider than the screen width, BASIC goes to the next physical line and
    continues printing.

■ Examples

    In the following example, the commas in the PRINT statement print each
    value at the beginning of the next print zone:

    X=5
    PRINT X+5, X-5, X*(-5), X^5
    END

■ Output

    10            0            -25            3125

    In the following example, the semicolon at the end of the first PRINT
    statement makes the first two PRINT statements print on the same line. The
    last PRINT statement prints a blank line before the next prompt.

    DO
        INPUT "Input X (input 0 to end): ", X
        IF X = 0 THEN
        EXIT DO
        ELSE
        PRINT X "squared is" X^2 "and";
        PRINT X "cubed is" X^3
        PRINT
        END IF
    LOOP

■ Output

    Input X (input 0 to end): 9
    9 squared is 81 and 9 cubed is 729

    Input X (input 0 to end): 21
    21 squared is 441 and 21 cubed is 9261

    Input X (input 0 to end): 0

    In the following example, the semicolons in the PRINT statement print each
    value immediately after the preceding value. (Remember, a space always
    follows a number and a space precedes a positive number.)

    FOR X=1 TO 5
    J=J+5
    K=K+10
    PRINT J;K;
    NEXT X

■ Output

    5  10  10  20  15  30  20  40  25  50


────────────────────────────────────────────────────────────────────────────
PRINT #, PRINT # USING Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Writes data to a sequential file

■ Syntax

    PRINT #filenumber,«USING stringexpression;» expressionlist «{, | ;}»

■ Remarks

    The filenumber is the number specified when the file was opened for
    output. The stringexpression consists of formatting characters as
    described under PRINT USING. The expressions in expressionlist are the
    numeric or string expressions to be written to the file. Spaces, commas,
    and semicolons in the expressionlist have the same meaning they have in a
    PRINT statement.

    If you omit expressionlist, the PRINT # statement prints a blank line in
    the file.

    PRINT # works like PRINT and writes an image of the data to the file, just
    as the data would be displayed on the terminal screen. For this reason, be
    careful to delimit the data so it is output correctly. If you use commas
    as delimiters, the blanks between print fields are also written to the
    file.

    For more information, see Chapter 3, "File and Device I/O," in Programming
    in BASIC.

■ See Also

    PRINT; PRINT USING; WRITE#

■ Example

    The following example shows the effects of omitting and of including
    delimiters in data written out with PRINT #:

    A$ = "CAMERA, AUTOFOCUS" : B$= "September 20, 1985"
    : C$ = "42"
    Q$ = CHR$(34)
    OPEN "INVENT.DAT" FOR OUTPUT AS #1 'Open INVENT.DAT for writing
    'Write A$, B$, C$ without delimiters.
    PRINT #1, A$ B$ C$
    'Write A$, B$, C$ with delimiters.
    PRINT #1, Q$ A$ Q$ Q$ B$ Q$ Q$ C$ Q$
    CLOSE #1
    OPEN "INVENT.DAT" FOR INPUT AS #1  'Open INVENT.DAT for reading.
    FOR I% = 1 TO 2                    'Read first two records and
        INPUT #1, First$,Second$,Third$ 'print.
        PRINT First$ TAB(30) Second$ TAB(60) Third$ : PRINT
    NEXT
    CLOSE #1

■ Output

    CAMERA           AUTOFOCUSSeptember 20         198542

    CAMERA, AUTOFOCUS      September 20, 1985            42


────────────────────────────────────────────────────────────────────────────
PRINT USING Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Prints strings or numbers using a specified format

■ Syntax

    PRINT USING formatstring; expressionlist «{, | ;}»

■ Remarks

    The formatstring is a string literal (or variable) containing literal
    characters to print (such as labels) and special formatting characters.
    These formatting characters determine the field and the format of the
    printed strings or numbers. Spaces, commas, and semicolons in the
    expressionlist have the same meaning they do in a PRINT statement.

    The expressionlist contains the string expressions or numeric expressions
    to be printed, separated by semicolons.

    When PRINT USING is used to print strings, you may use one of three
    formatting characters to format the string field, as described in the
    following list:

    Character                Description
    ──────────────────────────────────────────────────────────────────────────
    !                        Only the first character in the given string is
                            to be printed.

    \    \                   Prints 2 + n characters from the string, where n
                            is the number of spaces between the two
                            backslashes. If the backslashes are typed with no
                            spaces, two characters are printed. With one
                            space, three characters are printed, and so on.
                            If the field is longer than the string, the
                            string is left-justified in the field and padded
                            with spaces on the right.

    &                        Indicates a variable-length string field. When
                            the field is specified with the ampersand (&),
                            the string is output without modification.
    ──────────────────────────────────────────────────────────────────────────

    When PRINT USING is used to print numbers, the following special
    characters can be used to format the numeric field:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Character                Description
    ──────────────────────────────────────────────────────────────────────────
    #                        Represents each digit position. Digit positions
                            are always filled. If the number to be printed
                            has fewer digits than positions specified, the
                            number is right-justified (preceded by spaces) in
                            the field.

    .                        Prints a decimal point. A decimal point may be
                            inserted at any position in the field. If the
                            format string specifies that a digit is to
                            precede the decimal point, the digit is always
                            printed (as 0, if necessary). If necessary,
    Character                Description
    ──────────────────────────────────────────────────────────────────────────
                            printed (as 0, if necessary). If necessary,
                            numbers are rounded.

    +                        Causes the sign of the number (plus or minus) to
                            be printed before the number (if it appears at
                            the beginning of the format string) or after (if
                            it appears at the end of the format string).

    -                        Causes a negative number to be printed with a
                            trailing minus sign if it appears at the end of
                            the format string.

    **                       Causes leading spaces in the numeric field to be
                            filled with asterisks. The double asterisk also
                            specifies positions for two more digits.

    $$                       Causes a dollar sign to be printed to the
                            immediate left of the formatted number. The $$
                            specifies two more digit positions, one of which
    Character                Description
    ──────────────────────────────────────────────────────────────────────────
                            specifies two more digit positions, one of which
                            is the dollar sign.

    **$                      Combines the effects of the double-asterisk and
                            double-dollar-sign symbols. Leading spaces are
                            asterisk-filled and a dollar sign is printed
                            before the number. The **$ symbols specify three
                            more digit positions, one of which is the dollar
                            sign. When negative numbers are printed, the
                            minus sign appears to the immediate left of the
                            dollar sign.

    ,                        If the comma appears to the left of the decimal
                            point in a format string, it causes a comma to be
                            printed to the left of every third digit left of
                            the decimal point. If it appears at the end of
                            the format string, it is printed as part of the
                            string. A comma specifies another digit position.
                            The comma has no effect if used with exponential
    Character                Description
    ──────────────────────────────────────────────────────────────────────────
                            The comma has no effect if used with exponential
                            (^^^^ or ^^^^^) format.

    ^^^^                     Specifies exponential format. You can also use
                            five carets (^^^^^) to allow E+xxx to be printed
                            for larger numbers. Any decimal point position
                            may be specified. The significant digits are
                            left-justified and the exponent is adjusted.
                            Unless a leading +, trailing +, or - is
                            specified, one digit position is used to the left
                            of the decimal point to print a space or a minus
                            sign.

    _                        An underscore in the format string prints the
                            next character as a literal character. A literal
                            underscore is printed as the result of two
                            underscores ( __ ) in the format string.

    %                        If the number to be printed is larger than the
    Character                Description
    ──────────────────────────────────────────────────────────────────────────
    %                        If the number to be printed is larger than the
                            specified numeric field, a percent sign (%) is
                            printed in front of the number. If rounding
                            causes the number to exceed the field, a percent
                            sign is printed in front of the rounded number.
                            If the number of digits specified exceeds 24, an
                            error message results that reads Illegal function
                            call.
    ──────────────────────────────────────────────────────────────────────────


■ Examples

    The following example shows the results of using the three
    string-formatting characters:

    'Using the three string-formatting characters to modify the
    'appearance of printed output.
    A$ = "LOOK" : B$ = "OUT"
    PRINT USING "!";A$;B$
    PRINT USING "\  \";A$;B$        'Two spaces between back-
                                    'slashes, will print four
                                    'characters from A$.
    PRINT USING "\   \";A$;B$;"!!"  'Three spaces, will print
    PRINT USING "!";A$;             'A$ and a blank.
    PRINT USING "&";B$

■ Output

    LO
    LOOKOUT
    LOOK OUT  !!
    LOUT

    The following example shows the effects of different combinations of
    numeric formatting characters:

    'Format and print numeric data.
    PRINT USING "##.##";.78
    PRINT USING "###.##";987.654
    PRINT USING "##.##   ";10.2,5.3,66.789,.234
    PRINT USING "+##.##   ";-68.95,2.4,55.6,-.9
    PRINT USING "##.##-   ";-68.95,22.449,-7.01
    PRINT USING "**#.#   ";12.39,-0.9,765.1
    PRINT USING "$$###.##";456.78
    PRINT USING "**$##.##";2.34
    PRINT USING "####,.##";1234.5
    PRINT USING "##.##^^^^";234.56
    PRINT USING ".####^^^^-";-888888
    PRINT USING "+.##^^^^";123
    PRINT USING "+.##^^^^^";123
    PRINT USING "_!##.##_!";12.34
    PRINT USING "##.##";111.22
    PRINT USING ".##";.999

■ Output

    0.78
    987.65
    10.20    5.30   66.79    0.23
    -68.95    +2.40   +55.60    -0.90
    68.95-   22.45     7.01-
    *12.4   *-0.9   765.1
    $456.78
    ***$2.34
    1,234.50
    2.35E+02
    .8889E+06-
    +.12E+03
    +.12E+003
    !12.34!
    %111.22
    %1.00


────────────────────────────────────────────────────────────────────────────
PSET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Draws a point on the screen

■ Syntax

    PSET «STEP»(xcoordinate,ycoordinate) «,color»

■ Remarks

    The following list describes the parts of the PSET statement:

    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    STEP                     Indicates that the given xcoordinate and
                            ycoordinate are relative, not absolute. The
                            coordinates are treated as distances from the
                            most recent cursor location, not distances from
                            the (0,0) screen coordinate.

                            For example, if the most recent point referenced
                            were (10,10) then

                            PSET STEP (10,5)

                            would reference the point at (20,15).

    xcoordinate              The x-coordinate of the pixel that is to be set.

    ycoordinate              The y-coordinate of the pixel that is to be set.

    color                    The color attribute for the specified point.
    ──────────────────────────────────────────────────────────────────────────

    If a coordinate is outside the current viewport, no action is taken nor is
    an error message given. PSET allows the color to be left off the command
    line. If it is omitted, the default is the foreground color.

■ See Also

    PRESET

■ Example

    The following example draws a line from (0,0) to (100,100) and then erases
    that line by writing over it with the background color:

    SCREEN 2  'Draw a line from (0,0) to (100,100).
    FOR I=0 TO 100
        PSET (I,I)
    NEXT I
    FOR I=0 TO 100 'Now erase that line.
        PSET STEP (-1,-1),0
    NEXT I


────────────────────────────────────────────────────────────────────────────
PUT Statement──Graphics
────────────────────────────────────────────────────────────────────────────

■ Action

    Places a graphic image obtained by a GET statement onto the screen

■ Syntax

    PUT «STEP» (x, y), arrayname«(indices)» «,actionverb»

■ Remarks

    The parts of the PUT statement are described as follows:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    STEP                     Indicates that the given x- and y-coordinates are
                            relative, not absolute. The coordinates are
                            treated as distances from the most recent cursor
                            location, not distances from the (0,0) screen
                            coordinate.

                            For example, if the most recent point referenced
                            were (10,10) then the statement

                            PUT STEP (10,5),Ball

                            would put the object stored in Ball at (20,15).
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            would put the object stored in Ball at (20,15).

    (x,y)                    Coordinates specifying the top-left corner of the
                            rectangle enclosing the image to be placed in the
                            current output window.

    arrayname                The name of the array that holds the image. See
                            the entry for GET (Graphics) for the formula that
                            computes the size of this array. The array can be
                            a multidimensional array.

    indices                  Specifies that the image is retrieved starting
                            from the designated array element, rather than at
                            the first array element.

    actionverb               The actionverb determines the interaction between
                            the stored image and the one already on the
                            screen.
    ──────────────────────────────────────────────────────────────────────────
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    ──────────────────────────────────────────────────────────────────────────


    The different values for actionverb are described in the following list.
    The default for actionverb is XOR.

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Verb                     Description
    ──────────────────────────────────────────────────────────────────────────
    PSET                     Transfers the data point-by-point onto the
                            screen. Each point has the exact color attribute
                            it had when it was taken from the screen with
                            GET.

    PRESET                   The same as PSET except that a negative image
                            (for example, black on white) is produced.

    AND                      Used when the image is to be transferred over an
                            existing image on the screen. The resulting image
    Verb                     Description
    ──────────────────────────────────────────────────────────────────────────
                            existing image on the screen. The resulting image
                            is the result of a logical AND of the stored
                            image and the screen; points that had the same
                            color in both the existing image and the stored
                            image remain the same color, while those points
                            that do not have the same color in both the
                            existing image and the stored image do not.

    OR                       Used to superimpose the image onto an existing
                            image; the stored image does not erase the
                            previous screen contents. The resulting image is
                            the product of a logical OR of the stored image
                            and the screen image.

    XOR                      A special mode often used for animation. XOR
                            causes the points on the screen to be inverted
                            where a point exists in the array image. This
                            behavior is exactly like that of the cursor: when
                            an image is placed on the screen against a
    Verb                     Description
    ──────────────────────────────────────────────────────────────────────────
                            an image is placed on the screen against a
                            complex background twice, the background is
                            restored. This allows you to move an object
                            around the screen without erasing the background.
    ──────────────────────────────────────────────────────────────────────────


    See Chapter 5, "Graphics," in Programming in BASIC for a detailed
    description of doing animation with the PUT statement.

■ See Also

    GET (Graphics), PRESET, PRINT, PSET

■ Example

    The following example creates a moving white ball that ricochets off the
    sides of the screen until you press a key to end the program:

    DEFINT A-Z
    DIM Ball(84)     'Dimension integer array large enough
                    'to hold ball.
    SCREEN 2         '640 pixels by 200 pixels screen resolution.
    INPUT "Press any key to end; press <ENTER> to start",Test$
    CLS
    CIRCLE (16,16),14       'Draw and paint ball.
    PAINT (16,16),1
    GET (0,0)-(32,32),Ball
    X = 0 : Y = 0
    Xdelta = 2 : Ydelta = 1

    DO

        'Continue moving in same direction as long as ball is within
        'the boundaries of the screen - (0,0) to (640,200).

        X = X + Xdelta : Y = Y + Ydelta
        IF INKEY$<>"" THEN END  ' Test for key press.

        'Change X direction if ball hits left or right edge.
        IF (X < 1 OR X > 600) THEN
        Xdelta = -Xdelta
        BEEP
        END IF
        'Change Y direction if ball hits top or bottom edge.
        IF (Y < 1 OR Y > 160) THEN
        Ydelta = -Ydelta
        BEEP
        END IF
        'Put new image on screen, simultaneously erasing old image.
        PUT (X,Y),Ball,PSET

    LOOP
    END


────────────────────────────────────────────────────────────────────────────
PUT Statement──File I/O
────────────────────────────────────────────────────────────────────────────

■ Action

    Writes from a variable or a random-access buffer to a file

■ Syntax

    PUT «#»filenumber«,«recordnumber»«,variable»»
    PUT «#»filenumber«,{recordnumber|recordnumber, variable|,variable}»

■ Remarks

    The following list describes the parts of the PUT statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    filenumber               The number used in the OPEN statement to open the
                            file.

    recordnumber             For random-mode files, the number of the record
                            to be written. For binary-mode files, the byte
                            position in the file where writing is done. The
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            position in the file where writing is done. The
                            first record in a file is record 1. If you omit
                            recordnumber, the next record or byte (the one
                            after the last GET or PUT statement, or the one
                            pointed to by the last SEEK) is written to. The
                            largest possible record number is 2^31-1 or
                            2,147,483,647.

    variable                 The variable containing the output to be written
                            to the file. The PUT statement writes as many
                            bytes to the file as there are bytes in the
                            variable.

                            If you use a variable, you do not need to use
                            MKI$, MKL$, MKS$, or MKD$ to convert numeric
                            fields before writing. You may not use a FIELD
                            statement with the file if you use the variable
                            argument.

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────

                            For random-access files, you can use any variable
                            as long as the length of the variable is less
                            than or equal to the length of the record.
                            Usually, a record variable defined to match the
                            fields in a data record is used.

                            For binary-mode files, you can use any variable.

                            When you use a variable-length string variable,
                            the statement writes as many bytes as there are
                            characters in the string's value. For example,
                            the following two statements write 15 bytes to
                            file number 1:

                            VarString$=STRING$ (15, "X") PUT #1,,VarString$

                            See the examples below and Chapter 3, "File and
                            Device I/O," in Programming in BASIC, for more
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            Device I/O," in Programming in BASIC, for more
                            information about using variables rather than
                            FIELD statements for random-access files.

                            A record cannot contain more than 32,767 bytes.
    ──────────────────────────────────────────────────────────────────────────


    You can omit the recordnumber, the variable, or both. If you omit only the
    recordnumber, you must still include the commas:

    PUT #4,,FileBuffer

    If you omit both arguments, you do not include the commas:

    PUT #4

    The GET and PUT statements allow fixed-length input and output for BASIC
    communications files. Be careful using GET and PUT for communications
    because PUT writes a fixed number of characters and may wait indefinitely
    if there is a communications failure.

────────────────────────────────────────────────────────────────────────────
NOTE
    When using a file buffer defined by a FIELD statement, LSET, RSET, PRINT
    #, PRINT # USING, and WRITE # may be used to put characters in the
    random-file buffer before executing a PUT statement. In the case of WRITE
    # , BASIC pads the buffer with spaces up to the carriage return. Any
    attempt to read or write past the end of the buffer causes an error
    message that reads FIELD overflow.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CVI, CVS, CVL, CVD;
    GET (File I/O);LSET; MKD$,
    MKI$, MKL$, MKS$

■ Example

    The following example reads names and test scores from the console and
    stores the names and scores in a random-access file:


    ' Read a name and a test score from the console.
    ' Store each name and score as a record in a
    ' random-access file.

    ' Define record fields.
    TYPE TestRecord
        NameField  AS STRING*20
        ScoreField AS SINGLE
    END TYPE

    ' Open the test data file.
    DIM FileBuffer AS TestRecord
    OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(FileBuffer)

    ' Read pairs of names and scores from the console.

    I=0
    DO
        I=I+1
        INPUT "Name ? ",FileBuffer.NameField
        INPUT "Score? ",FileBuffer.ScoreField
        INPUT "-->More (y/n)? ",Resp$
        PUT #1,I,FileBuffer
    LOOP UNTIL UCASE$(MID$(Resp$,1,1))="N"

    PRINT I;" records written."

    CLOSE #1


────────────────────────────────────────────────────────────────────────────
RANDOMIZE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Initializes (reseeds) the random-number generator

■ Syntax

    RANDOMIZE«expression»

■ Remarks

    If you omit expression, BASIC pauses and asks for a value by printing

    Random Number Seed (-32768 to 32767)?

    before executing the RANDOMIZE statement. When you use the argument
    expression, QuickBASIC uses this value to initialize the random-number
    generator.

    If the random-number generator is not reseeded, the RND function returns
    the same sequence of random numbers each time the program is run. To
    change the sequence of random numbers every time the program is run, place
    a RANDOMIZE statement at the beginning of the program and change the
    argument with each run.

    A convenient way to initialize the random-number generator is to use the
    TIMER function. Using TIMER ensures a new series of random numbers each
    time you use the program. See the example below.

■ See Also

    RND, TIMER

■ Example

    The following program simulates rolling two dice. The RANDOMIZE statement
    initializes the random-number generator so the program produces different
    numbers each time.

    ' Use the timer as the seed for the number generator.
    RANDOMIZE TIMER

    DO
        ' Simulate rolling two dice using RND.
        D1=INT(RND*6)+1
        D2=INT(RND*6)+1
        ' Report the roll.
        PRINT "You rolled a";D1;"and a";D2;"for a total of";D1+D2
        INPUT "Roll again (Y/N)";Resp$
        PRINT
    LOOP UNTIL UCASE$(MID$(Resp$,1,1))="N"

    END

■ Output

    You rolled a 3 and a 5 for a total of 8
    Roll again (Y/N)? y

    You rolled a 4 and a 1 for a total of 5
    Roll again (Y/N)? y

    You rolled a 5 and a 6 for a total of 11
    Roll again (Y/N)? n


────────────────────────────────────────────────────────────────────────────
READ Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads values from a DATA statement and assigns the values to variables

■ Syntax

    READ variablelist

■ Remarks

    A variablelist is a series of valid BASIC variables separated by commas.
    READ statements are always used with DATA statements. READ assigns DATA
    values to variables on a one-to-one basis. These variables may be numeric
    or string. Attempting to read a string value into a numeric variable
    produces a run-time syntax error. Reading a numeric value into a string
    variable does not produce an error, but stores the value as a string of
    numerals.

    Values read into integer variables are rounded before the value is
    assigned to the variable. Reading a numeric value too large for a variable
    produces a run-time error.

    String values read into fixed-length string variables are truncated if the
    string is too long. String values shorter than the string-variable length
    are left-justified and padded with blanks.

    Only individual elements of a record variable may appear in a READ
    statement. See example below.

    A single READ statement may use one or more DATA statements (they will be
    used in order); several READ statements may use the same DATA statement.
    If there are more variables in variablelist than there are values in the
    DATA statement or statements, an error message is printed that reads Out
    of DATA. If there are fewer variables than the number of elements in the
    DATA statement or statements, subsequent READ statements begin reading
    data at the first unread element. If there are no subsequent READ
    statements, the extra items are ignored.

    Use the RESTORE statement to reread DATA statements.

■ See Also

    DATA, RESTORE

■ Example

    The following fragment shows how a READ statement can be used to read
    information into the user-defined type named Employee:

    TYPE Employee
        FullName AS STRING*35
        SocSec AS STRING*9
        JobClass AS INTEGER
    END TYPE

    DIM ThisEmp AS Employee
    DATA "Julia Magruder","300-32-3403",3
    DATA "Amelie Reeves Troubetzkoy","777-29-3206",7
    .
    .
    .
    READ ThisEmp.FullName, ThisEmp.SocSec, ThisEmp.JobClass
    .
    .
    .

    See also the examples for DATA and RESTORE.


────────────────────────────────────────────────────────────────────────────
REDIM Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Changes the space allocated to an array that has been declared ¢DYNAMIC

■ Syntax

    REDIM «SHARED» variable(subscripts)«AS type» «,variable(subscripts)«AS typ
    e»»...

■ Remarks

    The REDIM statement has the following arguments:

    Arguments                Description
    ──────────────────────────────────────────────────────────────────────────
    SHARED                   The optional SHARED attribute allows a module to
                            share variables with all the procedures in the
                            module; this differs from the SHARED statement,
                            which affects only the variables within a single
                            module. SHARED can only be used in REDIM
                            statements in the module-level code.

    variable                 A BASIC variable name.

    subscripts               The dimensions of the array. Multiple dimensions
                            can be declared. The subscript syntax is
                            described below.

    AS type                  Declares variable as an elementary or
                            user-defined type. The elementary types are
                            INTEGER, LONG, SINGLE, DOUBLE, and STRING.
    ──────────────────────────────────────────────────────────────────────────

    Subscripts in REDIM statements have the following form:

    «lower TO» upper «, «lower TO» upper»...

    The TO keyword provides a way to indicate both the lower and the upper
    bounds of an array's subscripts. The arguments lower and upper are numeric
    expressions specifying the lowest and highest value for the subscript. See
    the DIM statement for more information about using the TO keyword.

    The REDIM statement changes the space allocated to an array that has been
    declared dynamic. See Chapter 2, "Data Types," for more information about
    both static and dynamic arrays.

    When a REDIM statement is compiled, all arrays declared in the statement
    are treated as dynamic. At run time, when a REDIM statement is executed,
    the array is deallocated (if it is already allocated) and then reallocated
    with the new dimensions. Old array-element values are lost because all
    numeric elements are reset to 0 and all string elements are reset to null
    strings. Although you may change the size of an array's dimensions with
    the REDIM statement, you may not change the number of dimensions. For
    example, the following statements are legal:

    ' ¢DYNAMIC
    DIM A(50,50)
    ERASE A
    REDIM A(20,15)    'Array A still has two dimensions.

    However, the following statements are not legal and produce an error
    message that reads Wrong number of dimensions:

    ' ¢DYNAMIC
    DIM A(50,50)
    ERASE A
    REDIM A(5,5,5)   'Changed number of dimensions from
                    'two to three.

■ See Also

    DIM, ERASE, LBOUND, OPTION BASE, SHARED, UBOUND

■ Example

    The following program fragment shows one way to use REDIM to allocate an
    array of records when the records are needed and later to free the memory
    that the records use:

    TYPE KeyElement
        Word AS STRING*20
        Count AS INTEGER
    END TYPE

    ' Make arrays dynamic.
    ' ¢DYNAMIC
    .
    .
    .
    ' Allocate an array of records when you need it.
    REDIM Keywords(500) AS KeyElement
    Keywords(99).Word="ERASE"
    Keywords(99).Count=2
    PRINT Keywords(99).Word,Keywords(99).Count
    .
    .
    .
    ' Free the space taken by Keywords when you're finished.
    ERASE Keywords
    .
    .
    .
    END


────────────────────────────────────────────────────────────────────────────
REM Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Allows explanatory remarks to be inserted in a program

■ Syntax 1

    REM remark

■ Syntax 2

    ' remark

■ Remarks

    REM statements are not compiled, but they appear exactly as entered when
    the program is listed. You may branch from a GOTO or GOSUB statement to a
    REM statement. Execution continues with the first executable statement
    after the REM statement.

    A single quotation mark can be used instead of the REM keyword. If the REM
    keyword follows other statements on a line, it must be separated from the
    statements by a colon.

    REM statements are also used to introduce metacommands (see Appendix F,
    "Metacommands," in Programming in BASIC for more information).

────────────────────────────────────────────────────────────────────────────
NOTE
    Do not use the single quotation form of the REM statement in a DATA
    statement because it will be considered valid data.
────────────────────────────────────────────────────────────────────────────

■ Examples

    The following two lines are equivalent (notice that the colon is not
    required with the single quote):

    FOR I=1 TO 23 : Array(I)=1 : NEXT I : REM Initialize the array.
    FOR I=1 TO 23 : Array(I)=1 : NEXT I   ' Initialize the array.


────────────────────────────────────────────────────────────────────────────
RESET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Closes all disk files

■ Syntax

    RESET

■ Remarks

    The RESET statement closes all open disk files and writes data still in
    the file buffers to disk. All files must be closed before a disk is
    removed from its drive.

■ See Also

    CLOSE, END, SYSTEM

■ Example

    There are no programming examples for the RESET statement.


────────────────────────────────────────────────────────────────────────────
RESTORE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Allows DATA statements to be reread from a specified line

■ Syntax

    RESTORE «{linenumber | linelabel }»

■ Remarks

    After executing a RESTORE statement without a specified linenumber or
    linelabel, the next READ statement gets the first item in the first DATA
    statement in the program.

    If linenumber or linelabel is specified, the next READ statement gets the
    first item in the specified DATA statement. If a line is specified, the
    line number or line label must be in the module-level code. (Note that in
    the QuickBASIC environment, DATA statements are automatically moved to the
    module-level code.)

■ See Also

    DATA, READ

■ Example

    The RESTORE statement in the following fragment (from a program that
    generates random bridge hands) allows the program to reread the prompts in
    the DATA statement so the user can enter new boundary conditions for the
    different suits:

    DEFINT A-Z
    DIM X(13), Param(5,2)
    DATA Spades, Hearts, Diamonds, Clubs, Points

    CALL GetParameters(Param())

    DO
    .
    .
    .
        INPUT "Repeat with same parameters"; Ch$
        IF UCASE$(Ch$) <> "Y" THEN
        INPUT "Repeat with new parameters"; Ch$
        IF UCASE$(Ch$) <> "Y" THEN
            EXIT DO
        ELSE
            RESTORE
            CALL GetParameters(Param())
        END IF
        END IF
    LOOP

    END

    SUB GetParameters(Param(2)) STATIC
        CLS
        FOR I = 0 TO 4
        READ SUIT$
        PRINT SUIT$ " (low, high)";
        INPUT Param(I,0), Param(I,1)
        NEXT
    END SUB

■ Output

    Spades (low, high)? 5,10
    Hearts (low, high)? 5,10
    Diamonds (low, high)? 6,8
    Clubs (low, high)? 6,8
    Points (low, high)? 5,15
    .
    .
    .
    Repeat with same parameters? n
    Repeat with new parameters? y
    Spades (low, high)? 4,8
    Hearts (low, high)? 4,8
    .
    .
    .


────────────────────────────────────────────────────────────────────────────
RESUME Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Continues program execution after an error-trapping routine has been
    invoked

■ Syntax

    RESUME «0»
    RESUME NEXT
    RESUME  { linenumber | linelabel }

■ Remarks

    The different forms of the RESUME statement redirect program flow as
    described in the following list:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Statement                Where Execution Resumes
    ──────────────────────────────────────────────────────────────────────────
    RESUME «0»               At the last statement executed in the module
                            containing the error handler.

                            If an active error handler is found in the module
                            where the error occurs, execution resumes with
                            the statement that caused the error.

    RESUME NEXT              At the statement immediately following the last
                            statement executed in the module containing the
                            error handler.

                            If an active error handler is found in the module
                            where the error occurs, execution resumes with
                            the statement immediately following the statement
                            that caused the error.

    Statement                Where Execution Resumes
    ──────────────────────────────────────────────────────────────────────────

    RESUME linenumber        At linenumber.

    RESUME linelabel         At linelabel.
    ──────────────────────────────────────────────────────────────────────────


    A RESUME statement that is not in an error-handling routine produces the
    error message RESUME without error. Reaching the end of an error-handling
    routine without finding RESUME produces the error message No RESUME.

    The line specified in a RESUME { linenumber | linelabel } statement must
    be defined at module level. As a rule, avoid using a line number or line
    label with a RESUME statement. Omitting the line number allows your
    program to continue no matter where the error occurred.

────────────────────────────────────────────────────────────────────────────
NOTE
    Programs containing error-handling routines must be compiled with either
    the /E (On Error) or /X (Resume Next) options when you are compiling from
    the BC command line. No options are required when compiling in the
    QuickBASIC environment, or using the Make EXE command from the QuickBASIC
    Run menu.
────────────────────────────────────────────────────────────────────────────

■ DIFFERENCES FROM BASICA

    In BASICA, if an error occurs in a DEF FN function, both RESUME and RESUME
    NEXT attempt to resume program execution at the line containing the
    function.

■ See Also

    ERR, ERL; ERROR; ON ERROR

■ Example

    This example has an error-handling routine starting at line 900. In
    BASICA, this routine would cause an error message (No negative arguments)
    to be printed for I= -1 and -2. The routine would then end. In BASIC, the
    error-handling routine prints its message when I= -1, then resumes at the
    beginning of the FOR...NEXT loop with I reset to 4, as seen below.

    10 ON ERROR GOTO 900
    20 DEF FNTEST(A) = 1 - SQR(A)
    30 FOR I = 4 TO -2 STEP -1
    40     PRINT I,FNTEST(I)
    50 NEXT
    60 END

    900 'Error-handling routine
    910     PRINT "No negative arguments"
    920 RESUME NEXT

■ Output

    4      -1
    3      -.7320509
    2      -.4142136
    1       0
    0       1
    -1      No negative arguments
    4      -1
    3      -.7320509
    2      -.4142136
    .
    .
    .


────────────────────────────────────────────────────────────────────────────
RETURN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns control from a subroutine

■ Syntax

    RETURN «{linenumber | linelabel }»

■ Remarks

    Without a line label or number, RETURN continues execution where an event
    occurred (for event handling) or at the statement following the GOSUB (for
    subroutine calls). GOSUB and RETURN without a line number can be used
    anywhere in a program, but the GOSUB and corresponding RETURN must be at
    the same level.

    The linenumber or linelabel in the RETURN statement causes an
    unconditional return from a GOSUB subroutine to the specified line. RETURN
    with a line label or line number can only return control to a statement in
    the module-level code.

    A RETURN statement cannot be used to return control to a calling program
    from a subprogram defined by SUB. Use EXIT SUB.

────────────────────────────────────────────────────────────────────────────
NOTE
    BASIC's SUB procedures provide a more well-structured alternative to GOSUB
    subroutines.
────────────────────────────────────────────────────────────────────────────

■ See Also

    EXIT, GOSUB, ON event

■ Example

    See the example for the GOSUB statement.


────────────────────────────────────────────────────────────────────────────
RIGHT$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the rightmost n characters of a string

■ Syntax

    RIGHT$(stringexpression,n)

■ Remarks

    The argument stringexpression can be any string variable, string constant,
    or string expression. If n is equal to the number of characters in the
    argument stringexpression, then the RIGHT$ function returns
    stringexpression. If n = 0, RIGHT$ returns the null string (length zero).

■ See Also

    LEFT$, MID$

■ Example

    This program converts names that have been input in the form "Firstname
    [Middlename] Lastname" to the form "Lastname, Firstname [Middlename]":

    LINE INPUT "Name: "; Nm$
    I = 1 : Sppos = 0
    DO WHILE I > 0
        I = INSTR(Sppos+1,Nm$," ")   'Get position of next space.
        IF I > 0 THEN Sppos = I
    LOOP

    'SPPOS now points to the position of the last space.
    IF Sppos = 0 THEN
        PRINT Nm$                    'There was just a last name.
    ELSE
        'Everything after last space.
        Lastname$ = RIGHT$(Nm$,LEN(Nm$)-Sppos)
        'Everything before last space.
        Firstname$ = LEFT$(Nm$,Sppos-1)
        PRINT Lastname$ ", " Firstname$
    END IF
    END


────────────────────────────────────────────────────────────────────────────
RMDIR Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Removes an existing directory

■ Syntax

    RMDIR pathname

■ Remarks

    The pathname is the name of the directory that is to be deleted. The
    pathname must be a string of less than 128 characters. The directory to be
    removed must be empty except for the working directory ('.') and the
    parent directory ('..'); otherwise, one of two error messages is printed,
    either Path not found or Path/File access error.

    RMDIR works like the DOS command of the same name; the syntax in BASIC
    cannot be shortened to RD, as in DOS.

■ See Also

    CHDIR, MKDIR

■ Example

    The following example illustrates the use of the RMDIR statement:

    CHDIR "C:\SALES\TEMP"         'Move to \TEMP subdirectory in \SALES.
    KILL "*.*"                    'Remove all files in \TEMP.
    CHDIR ".."                    'Move back up to \SALES.
    RMDIR "TEMP"                  'Remove \TEMP subdirectory.


────────────────────────────────────────────────────────────────────────────
RND Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a single-precision random number between 0 and 1

■ Syntax

    RND«(n)»

■ Remarks

    The value of n determines how RND generates the next random number:

    Argument                 Number Returned
    ──────────────────────────────────────────────────────────────────────────
    n < 0                    Always returns the same number for any given n

    n > 0 or n omitted       Returns the next random number in the sequence

    n = 0                    Returns the last number generated
    ──────────────────────────────────────────────────────────────────────────

    Even if n>0, the same sequence of random numbers is generated each time
    the program is run unless you initialize the random-number generator each
    time you run the program. (See the RANDOMIZE statement entry for more
    information about initializing the random-number generator.)

    To produce random integers in a given range, use the formula

    INT ((upperbound - lowerbound + 1)*RND + lowerbound)

    where upperbound is the highest number in the range, and lowerbound is the
    lowest number in the range.

■ Example

    See the examples for the RANDOMIZE and TYPE statements.


────────────────────────────────────────────────────────────────────────────
RSET Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    The stringvariable is usually a random-access file field defined in a
    FIELD statement, although it can be any string variable. The
    stringexpression is the value assigned to the variable.

    If stringexpression requires fewer bytes than were defined for
    stringvariable in the FIELD statement, the RSET statement right-justifies
    the string in the field (LSET left-justifies the string). Spaces are used
    to pad the extra positions. If the string is too long for the field, both
    LSET and RSET truncate characters from the right. Numeric values must be
    converted to strings before they are justified with the RSET or LSET
    statements.

    The RSET statement can be used with string variables unrelated to FIELD
    statements. When used with a fixed-length string variable, the value is
    right-justified and left-padded with blanks.

    When RSET is used with a variable-length string, the string is treated as
    a fixed field. The length of the field is the length of the value the
    variable had before the RSET statement. See the example below.

■ See Also

    FIELD; LSET; MKD$, MKI$, MKL$, MKS$; PUT

■ Example

    The following example shows the effects of using RSET to assign values to
    fixed- and variable-length strings:

    DIM TmpStr2 AS STRING * 10
    PRINT "         1         2         3"
    PRINT "123456789012345678901234567890"
    ' Use RSET on null variable-length string of length.
    ' Nothing prints because TmpStr$ is a zero-length field.
    TmpStr$ = ""
    RSET TmpStr$ = "Another"
    PRINT TmpStr$
    ' Use RSET on variable-length string with a value.
    TmpStr$ = SPACE$(20)
    RSET TmpStr$ = "Another"
    PRINT TmpStr$

    ' Use RSET on fixed-length string of length 10.
    RSET TmpStr2 = "Another"
    PRINT TmpStr2

■ Output

    1         2         3
    123456789012345678901234567890

                Another
        Another


────────────────────────────────────────────────────────────────────────────
RTRIM$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string with trailing (right-hand) spaces removed

■ Syntax

    RTRIM$(stringexpression)

■ Remarks

    The stringexpression can be any string expression. The RTRIM$ function
    works with both fixed- and variable-length string variables.

■ See Also

    LTRIM$

■ Example

    The example shows the effects of the RTRIM$ function on fixed- and
    variable-length strings. See also the example for the LTRIM$ function.

    DIM FixStr AS STRING * 10
    PRINT "         1         2"
    PRINT "12345678901234567890"
    FixStr = "Twine"
    PRINT FixStr + "*"
    PRINT RTRIM$(FixStr) + "*"
    VarStr$ = "Braided" + SPACE$(10)
    PRINT VarStr$ + "*"
    PRINT RTRIM$(VarStr$) + "*"

■ Output

    1         2
    12345678901234567890
    Twine     *
    Twine*
    Braided          *
    Braided*


────────────────────────────────────────────────────────────────────────────
RUN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Restarts the program currently in memory or executes a specified program

■ Syntax

    RUN «{ linenumber | filespec }»

■ Remarks

    The RUN statement accepts the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    linenumber               The numeric label of the line where execution
                            begins. If no argument is given, execution begins
                            at the first executable line of code.

    filespec                 A string expression naming the program file to
                            load and run. The current program is cleared from
                            memory before the specified program is loaded.
    ──────────────────────────────────────────────────────────────────────────

    The line where execution begins must be in the module-level code.
    Therefore, a RUN statement in a SUB or FUNCTION procedure must point to
    labels at module level. If no line label is given, execution always starts
    with the first executable line of the program's main module.

    During compilation, if linenumber cannot be found in the module-level
    code, compilation halts and the error message Label not defined appears.

    Program lines can have line numbers or alphanumeric labels, such as
    OpenWindow:. If an alphanumeric label is the target of a RUN statement,
    execution halts, and the error message Type mismatch appears. Note that
    the QuickBASIC syntax checker does not warn you if you give the RUN
    statement an alphanumeric label instead of a line number.

    You do not need to specify the file name extension in filespec. The .BAS
    extension is assumed in the QuickBASIC environment, and the .EXE extension
    is assumed when running compiled, stand-alone programs. If the program you
    wish to run has a different extension, you must give the extension. If the
    program name has no extension, the file name given must end with a period.

    For example,

    RUN "CATCHALL"

    would execute CATCHALL.EXE from a BC-compiled program, and CATCHALL.BAS
    from within QuickBASIC.

    Programs running within the QuickBASIC environment must call only
    QuickBASIC program files. The file is loaded and run as if it were a
    QuickBASIC program; if it is not in the QuickBASIC program format,
    execution halts. The error message that appears varies, depending on the
    file's contents. Likewise, programs compiled with BC must not invoke
    QuickBASIC source files, as these run only within the QuickBASIC
    environment.

    An executable file need not have been written in QuickBASIC. Any
    executable file may be run.

    When running a program under QuickBASIC, if an executable file matching
    the file name in filespec cannot be found, the error message File not
    found appears, and control returns to QuickBASIC. When running a program
    compiled by BC, the error message File not found in module programname
    appears, and control returns to DOS.

    When the invoked program completes execution, control does not return to
    the invoking program. If the invoking program ran outside QuickBASIC,
    control returns to DOS. If the invoking program ran under QuickBASIC,
    control returns to QuickBASIC.

    If you edit a QuickBASIC program containing a RUN statement, then run the
    program before saving the changes, QuickBASIC asks if you wish to save the
    new version of the program before RUN clears it from memory.

    RUN closes all files and clears program memory before loading the
    designated program.The BC compiler does not support the R option from
    BASICA. (This option keeps all open data files open.) If you want to run a
    different program, but leave open files open, use the CHAIN statement.

■ See Also

    CHAIN

■ Examples

    The following example shows how RUN linenumber resets all numeric
    variables to 0. As the line number following RUN increases in lines 60,
    70, 80, and 90, the variables in the earlier statements lose their
    assigned values.

    10 A = 9
    20 B = 7
    30 C = 5
    40 D = 4
    50 PRINT A,B,C,D
    60 IF A = 0 THEN 70 ELSE RUN 20
    70 IF B = 0 THEN 80 ELSE RUN 30
    80 IF C = 0 THEN 90 ELSE RUN 40
    90 IF D = 0 THEN END ELSE RUN 50

■ Output

    9   7   5   4
    0   7   5   4
    0   0   5   4
    0   0   0   4
    0   0   0   0


────────────────────────────────────────────────────────────────────────────
SADD Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the address of the specified string expression

■ Syntax

    SADD(stringvariable)

■ Remarks

    The SADD function returns the address of a string as an offset (near
    pointer) from the current data segment. The offset is a two-byte integer.
    SADD is most often used in mixed-language programming.

    The argument may be a simple string variable or a single element of a
    string array. You may not use fixed-length string arguments.

    Use this function with care because strings can move in the BASIC string
    space (storage area) at any time. SADD works only with string variables
    stored in DGROUP.

────────────────────────────────────────────────────────────────────────────
NOTE
    Do not add characters to the beginning or end of a string passed using
    SADD and LEN. Adding characters may produce a run-time error.
────────────────────────────────────────────────────────────────────────────

■ See Also

    CALL, CALLS (Non-BASIC); DECLARE (Non-BASIC); FRE; PEEK; POKE;
    VARPTR; VARPTR$; VARSEG

■ Example

    The following example uses SADD and LEN to pass a string to a function
    written in C. The C function returns the ASCII value of a character at a
    given position in the string. The C program would be separately compiled
    and stored in a Quick library or explicitly linked to form an .EXE file.
    Note that BYVAL is the default for C.

    ' Pass a string to a C function using SADD and LEN.
    DEFINT A-Z
    ' Declare the function;
    DECLARE FUNCTION MyAsc CDECL (BYVAL A%, BYVAL B%, BYVAL C%)

    A$="abcdefghijklmnopqrstuvwxyz"
    PRINT "Enter a character position (1-26). Enter 0 to Quit."
    DO

    ' Get a character position.
        INPUT N
    ' End if the position is less than zero.
        IF N<=0 THEN EXIT DO
    ' Call C function; the function returns the ASCII code of the
    ' character at position N in A$.
        AscValue=MyAsc(SADD(A$),LEN(A$),N)
        PRINT "ASCII value: ";AscValue;"Character: ";CHR$(AscValue)

    LOOP
    END

    /* C function to return the ASCII value of the character
        at position pos in string c of length len.          */

    int far myasc(c,len,pos)
    char near *c;
    int len, pos;
    {

        if(pos>len) return(c[--len]);/* Avoid indexing off end. */
        else if (pos<1) return(c[0]);/* Avoid indexing off start. */
        else
        return(c[--pos]);/* pos is good. Return the character at
                            pos-1 because C arrays (strings) are
                            zero-indexed. */
    }

■ Output

    Enter a character position (1-26). Enter -1 to Quit.
    ? 24
    ASCII value:  120 Character: x
    ? -1


────────────────────────────────────────────────────────────────────────────
SCREEN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Reads a character's ASCII value or its color from a specified screen
    location

■ Syntax

    SCREEN(row,column«,colorflag»)

■ Remarks

    The following list describes the SCREEN function's arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    row                      The row number of the screen location. The row is
                            a numeric expression that evaluates to an
                            unsigned integer.

    column                   The column number of the screen location. The
                            column is a numeric expression that evaluates to
                            an unsigned integer.

    colorflag                A numeric expression. When colorflag is nonzero,
                            SCREEN returns the number of the color at the
                            screen location. If the colorflag is zero or
                            absent, the ASCII code of the character at the
                            location is returned as an integer.
    ──────────────────────────────────────────────────────────────────────────

■ Examples

    If the character at (10,10) in the following examples is A, then the
    function would return 65, the ASCII code for A:

    X=SCREEN(10,10)

    The following example returns the color attribute of the character in the
    upper-left corner of the screen:

    X=SCREEN(1,1,1)


────────────────────────────────────────────────────────────────────────────
SCREEN Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the specifications for the display screen

■ Syntax

    SCREEN «mode» «,«colorswitch»
    »«,«apage» »«,«vpage»»

■ Remarks

    The SCREEN statement selects a screen mode appropriate for a particular
    combination of display and adapter. Later sections describe the available
    modes for specific adapters. The following list describes the arguments of
    the SCREEN statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    mode                     An integer constant or expression indicating the
                            screen mode. The valid modes are described below
                            for each of the supported adapters.

    colorswitch              Determines whether color is displayed on
                            composite monitors. The colorswitch is a numeric
                            expression in the range 0-255. When it is true
                            (nonzero), color is disabled and only
                            black-and-white images are displayed. When
                            colorswitch is false (zero), images are in color.
                            The colorswitch argument's meaning is inverted in
                            screen mode 0. In screen modes 2 and up,
                            colorswitch is ignored.

    apage                    A numeric expression that is the number of the
                            screen page that text output or graphics commands
                            write to. Tables below indicate valid values for
                            apage with various adapters.
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
                            apage with various adapters.

    vpage                    A numeric expression that is the number of the
                            screen page being displayed. Tables below
                            indicate valid values for vpage with various
                            adapters.
    ──────────────────────────────────────────────────────────────────────────


    The next two subsections summarize the screen modes and discuss the modes
    available with specific combinations of adapters and displays. The final
    subsection summarizes attributes and colors.

    SUMMARY OF SCREEN MODES

    The following paragraphs briefly summarize each of the screen modes. The
    color adapters referred to are the IBM Color Graphics Adapter (CGA), the
    IBM Enhanced Graphics Adapter (EGA), the IBM Video Graphics Array (VGA)
    and the IBM Multicolor Graphics Array (MCGA). The Hercules(R) Graphics
    Card, Graphics Card Plus and InColor(R) adapters are supported, but only
    with monochrome monitors. The next subsection supplies detailed
    information about the effects of a screen mode when used with a specific
    combination of display and adapter.

────────────────────────────────────────────────────────────────────────────
NOTE
    Many screen modes support more than one combination of rows and columns on
    the screen. See the entry for the WIDTH statement for more information
    about changing the number of rows and columns on the display.
────────────────────────────────────────────────────────────────────────────

    Screen 0

    ■ Text mode only

    ■ Either 40 x 25, 40 x 43, 40 x 50, 80 x 25, 80 x 43, or 80 x 50 text
    format with character-box size of 8 x 8 (8 x 14, 9 x 14, or 9 x 16 with
    EGA or VGA)

    ■ Assignment of 16 colors to 2 attributes

    ■ Assignment of 16 colors to any of 16 attributes (with CGA or EGA)

    ■ Assignment of 64 colors to any of 16 attributes (with EGA or VGA)

    Screen 1

    ■ 320 x 200 pixel medium-resolution graphics

    ■ 40 x 25 text format with character-box size of 8 x 8

    ■ Assignment of 16 colors to 4 attributes with EGA or VGA

    ■ Supports CGA, EGA, VGA, and MCGA

    Screen 2

    ■ 640 x 200 pixel high-resolution graphics

    ■ 80 x 25 text format with character-box size of 8 x 8

    ■ Assignment of 16 colors to 2 attributes with EGA or VGA

    ■ Supports CGA, EGA, VGA, and MCGA Screen 3

    ■ Hercules adapter required

    ■ Monochrome monitor only

    ■ 720 x 348 pixel resolution, monochrome

    ■ 80 x 25 text format with character-box size of 9 x 14; bottom two scan
    lines of 25th row not visible

    ■ Two screen pages (one only if a second display adapter is installed)

    ■ PALETTE statement not supported

────────────────────────────────────────────────────────────────────────────
NOTE
    The Hercules driver (MSHERC.COM) must be loaded for the Hercules card to
    function. This file is supplied with QuickBASIC. Type MSHERC before
    running QuickBASIC. If a compatible color adapter is also installed (eg,
    CGA), type MSHERC /H instead. This limits the Hercules card to one screen
    page but permits normal operation of the color adapter. If the Hercules
    driver is not loaded, the Hercules card operates like an IBM Monochrome
    Display Adapter (MDA).
────────────────────────────────────────────────────────────────────────────

    Screen 4

    ■ 640 x 400 pixel high-resolution graphics

    ■ 80 x 25 text format with character-box size of 8 x 16

    ■ Assignment of 1 of 16 colors as the foreground color (selected by the
    COLOR statement); background fixed at black

    ■ Supports Olivetti(R) Personal Computers, models M24, M240, M28, M280,
    M380, M380/C, and M380/T, and AT&T(R) Personal Computers 6300 series

────────────────────────────────────────────────────────────────────────────
WARNING
    Olivetti personal computers running in DOS-compatibility mode under
    Microsoft Operating System/2 should avoid this screen mode.
────────────────────────────────────────────────────────────────────────────

    Screen 7

    ■ 320 x 200 pixel medium-resolution graphics

    ■ 40 x 25 text format with character-box size of 8 x 8

    ■ Multiple screen pages

    ■ Assignment of 16 colors to any of 16 attributes

    ■ EGA or VGA required

    Screen 8

    ■ 640 x 200 pixel high-resolution graphics

    ■ 80 x 25 text format with character-box size of 8 x 8

    ■ Multiple screen pages

    ■ Assignment of 16 colors to any of 16 attributes

    ■ EGA or VGA required

    Screen 9

    ■ 640 x 350 pixel enhanced-resolution graphics

    ■ 80 x 25 or 80 x 43 text format with character-box size of 8 x 14 or 8 x
    8

    ■ Assignment of either 64 colors to 16 attributes (more than 64K of EGA or
    VGA memory) or 16 colors to 4 attributes (64K of EGA or VGA memory)

    ■ Multiple screen pages

    ■ EGA or VGA required

    Screen 10

    ■ Monochrome only

    ■ 640 x 350 pixel enhanced-resolution graphics

    ■ 80 x 25 or 80 x 43 text format with character-box size of 8 x 14 or 8 x
    8

    ■ Multiple screen pages

    ■ Assignment of up to nine pseudocolors to 4 attributes (refer to Tables
    R.9 and R.10 in the next section)

    ■ EGA or VGA required

    Screen 11

    ■ 640 x 480 pixel very high-resolution graphics

    ■ 80 x 30 or 80 x 60 text format with character-box size of 8 x 16 or 8 x
    8

    ■ Assignment of up to 256K colors to 2 attributes

    ■ VGA or MCGA required

    Screen 12

    ■ 640 x 480 pixel very-high-resolution graphics

    ■ 80 x 30 or 80 x 60 text format with character-box size of 8 x 16 or 8 x
    8

    ■ Assignment of up to 256K colors to 16 attributes

    ■ VGA required

    Screen 13

    ■ 320 x 200 pixel medium-resolution graphics

    ■ 40 x 25 text format with character-box size of 8 x 8

    ■ Assignment of up to 256K colors to up to 256 attributes

    ■ VGA or MCGA required

    SCREEN MODES, ADAPTERS, AND DISPLAYS

    This section describes the screen modes for specific combinations of
    adapters and displays. The IBM Monochrome Display and Printer Adapter
    (MDPA) can be used only with a monochrome display. Only screen mode 0,
    text mode, can be used with the MDPA. Table R.6 summarizes the effect of
    using screen mode 0 with an MDPA.

    Table R.6   MDPA Screen Modes

    Screen      Rows and
    Mode        Columns      Attributes  Colors      Resolution   Pages
    ──────────────────────────────────────────────────────────────────────────
    0           80x25        16          3           720x350      1
    ──────────────────────────────────────────────────────────────────────────

    Table R.7 summarizes the screen modes available with Hercules adapters.

    Table R.7   Hercules Screen Modes

    Screen      Rows and
    Mode        Columns      Attributes  Colors      Resolution   Pages
    ──────────────────────────────────────────────────────────────────────────
    0           80x25        16          1           720x348      2
    3           80x25        16          1           720x348      2
    ──────────────────────────────────────────────────────────────────────────

    The IBM Color Graphics Adapter (CGA) and Color Display are typically
    paired. This combination permits running text-mode programs and both
    medium-resolution and high-resolution graphics programs.

    Table R.8 summarizes the screen modes available with the CGA.

    Table R.8   CGA Screen Modes

    Screen         Rows and
    Mode           Columns        Colors        Resolution     Pages
    ──────────────────────────────────────────────────────────────────────────
    0              40x25          16            320x200        8
                    80x25          16            640x200        4
    1              40x25          4             320x200        1
    2              80x25          2             640x200        1
    ──────────────────────────────────────────────────────────────────────────

    The IBM Enhanced Graphics Adapter (EGA) may be used with either the IBM
    Color Display or the Enhanced Color Display. In screen modes 0, 1, 2, 7,
    and 8, these pairings produce similar results, except for the following
    possible differences:

    1. The border color cannot be set on an Enhanced Color Display when it is
        in 640 x 350 text mode.

    2. The text quality is better on the Enhanced Color Display (an 8 x 14
        character box for Enhanced Color Display versus an 8 x 8 character box
        for Color Display).

    Screen mode 9 takes full advantage of the capabilities of the Enhanced
    Color Display and provides for the highest resolution possible for the
    EGA/Enhanced Color Display configuration. Programs written for this mode
    will not work for any other hardware configuration except the VGA. Table
    R.9 summarizes the screen modes that can be used with an EGA.

    Table R.9   EGA Screen Modes

╓┌─┌───────┌─────────┌────────┌──────────┌───────┌──────────┌─────────┌──────╖
    Screen  Rows and                                         Page
    Mode    Columns   Display  Attributes Colors  Resolution Size      Pages
                    ☼
    ──────────────────────────────────────────────────────────────────────────
    0       40x25     C        16         16      320x200    N/A       8
            40x25     E        16         64      320x350    N/A       8
            40x43     E        16         64      320x350    N/A       8☼
            80x25     C        16         16      640x200    N/A       8☼
            80x25     E        16         64      640x350    N/A       8☼
            80x25     C        16         16      640x200    N/A       8☼
            80x25     M        16         3       720x350    N/A       8☼
            80x43     E        16         64      640x350    N/A       4☼
            80x43     M        16         3       720x350    N/A       4☼
    Screen  Rows and                                         Page
    Mode    Columns   Display  Attributes Colors  Resolution Size      Pages
                    ☼
    ──────────────────────────────────────────────────────────────────────────
            80x43     M        16         3       720x350    N/A       4☼
    1       40x25     N/A      4          16      320x200    16K       1
    2       80x25     N/A      2          16      640x200    16K       1
    7       40x25     N/A      16         16      320x200    32K       ☼
    8       80x25     N/A      16         16      640x200    64K       ☼
    9☼      80x25     E        4          64      640x350    64K       1
            80x43     E        4          64      640x350    64K       1
            80x25     E        16         64      640x350    128K      ☼
            80x43     E        16         64      640x350    128K      ☼
    10      80x25     M        4          9       640x350    64K       ☼
            80x43     M        4          9       640x350    64K       ☼
    ──────────────────────────────────────────────────────────────────────────


    Only the EGA and VGA can be paired with the IBM Monochrome Display to run
    programs in screen mode 10. This mode can be used to display monochrome
    graphics at a very high resolution.

    The following two tables summarize the default attributes and colors for
    screen mode 10 used with a monochrome display.

    Table R.10   Default Attributes: Screen Mode 10, Monochrome Display

    Attribute                Displayed
    Value                    Pseudocolor
    ──────────────────────────────────────────────────────────────────────────
    0                        Off
    1                        On, normal intensity
    2                        Blink
    3                        On, high intensity
    ──────────────────────────────────────────────────────────────────────────

    Table R.11   Color Values: Screen Mode 10, Monochrome Display

    Color                    Displayed
    Value                    Pseudocolor
    ──────────────────────────────────────────────────────────────────────────
    0                        Off
    1                        Blink, off to on
    2                        Blink, off to high intensity
    3                        Blink, on to off
    4                        On
    5                        Blink, on to high intensity
    6                        Blink, high intensity to off
    7                        Blink, high intensity to on
    8                        High intensity
    ──────────────────────────────────────────────────────────────────────────

    The IBM Video Graphics Array (VGA) adapter offers significantly enhanced
    text and graphics in all screen modes. Table R.12 summarizes the modes
    available with the VGA.

    Table R.12   VGA Screen Modes

╓┌─┌──────────┌─────────┌──────────┌─────────┌──────────┌─────────┌──────────╖
                Rows and                                  Page
    Mode       Columns   Attributes Colors    Resolution Size      Pages
    ──────────────────────────────────────────────────────────────────────────
    0          40x25     16         64        360x400    N/A       8
                Rows and                                  Page
    Mode       Columns   Attributes Colors    Resolution Size      Pages
    ──────────────────────────────────────────────────────────────────────────
    0          40x25     16         64        360x400    N/A       8
                40x43     16         64        320x350    N/A       8
                40x50     16         64        320x400    N/A       4
                80x25     16         64        720x400    N/A       8
                80x43     16         64        640x350    N/A       4
                80x43     16         3         720x350    N/A       4
                80x50     16         64        640x400    N/A       4
                80x50     16         3         720x400    N/A       4
    1          40x25     4          16        320x200    16K       1
    2          80x25     2          16        640x200    16K       1
    7          40x25     16         16        320x200    32K       ☼
    8          80x25     16         16        640x200    64K       ☼
    9          80x25     16         64        640x350    128K      ☼
                80x43     16         64        640x350    128K      ☼
    10         80x25     4          9         640x350    64K       ☼
                80x43     4          9         640x350    64K       ☼
    11         80x30     2          256K      640x480    64K       1
                80x60     2          256K      640x480    64K       1
                Rows and                                  Page
    Mode       Columns   Attributes Colors    Resolution Size      Pages
    ──────────────────────────────────────────────────────────────────────────
                80x60     2          256K      640x480    64K       1
    12         80x30     16         256K      640x480    256K      1
                80x60     16         256K      640x480    256K      1
    13         40x25     256        256K      320x200    64K       1
    ──────────────────────────────────────────────────────────────────────────


    See the PALETTE statement for a description of how the VGA calculates
    color values.

    The IBM Multicolor Graphics Array (MCGA) combines the modes of the CGA
    with the very high resolution and 256K color modes of the VGA to provide
    enhanced text and graphics in all modes. Table R.13 summarizes the modes
    supported by the MCGA.

    Table R.13   MCGA Screen Modes

                Rows and                                  Page
    Mode       Columns   Attributes Colors    Resolution Size      Pages
    ──────────────────────────────────────────────────────────────────────────
    0          40x25     16         N/A       320x400    N/A       8
                80x25     16         N/A       640x400    N/A       8
    1          40x25     4          N/A       320x200    16K       1
    2          80x25     2          N/A       640x200    16K       1
    11         80x30     2          256K      640x480    64K       1
                80x60     2          256K      640x480    64K       1
    13         40x25     256        256K      320x200    64K       1
    ──────────────────────────────────────────────────────────────────────────

    The MCGA uses the same color values as the VGA. See the PALETTE statement
    for a description of how the MCGA calculates color values.

    ATTRIBUTES AND COLORS

    For various screen modes and display hardware configurations, different
    attribute and color settings exist. (See the PALETTE statement for a
    discussion of attribute and color number.) The majority of these attribute
    and color configurations are summarized in Tables R.14-R.16.

    Table R.14   Default Attributes and Colors for Screen Modes 1 and 9☼

    Attributes   Color Display                  Monochrome Display
                Number☼        Color           Number☼       Color
    ──────────────────────────────────────────────────────────────────────────
    0            0              Black           0             Off
    1            11             Light cyan      2             High intensity
    2            13             Light magenta   2             High intensity
    3            15             High-intensity  0             Off
                                white
    ──────────────────────────────────────────────────────────────────────────

    Table R.15   Default Attributes and Colors for Screen Modes 2 and 11

    Attributes   Color Display                  Monochrome Display
                Number☼        Color           Number☼Color
    ──────────────────────────────────────────────────────────────────────────
    0            0              Black           0             Off
    1            15             High-intensity  0             Off
                                white
    ──────────────────────────────────────────────────────────────────────────

    Table R.16   Default Attributes and Colors for Screen Modes 0, 7, 8, 9☼,
    12, and 13

╓┌─┌──────────────┌────────────┌───────────────┌─────────────┌───────────────╖
    Attributes     Color Display                Monochrome Display
                    Number☼      Color           Number☼       Color
    ──────────────────────────────────────────────────────────────────────────
    0              0            Black           0             Off
    1              1            Blue                          Underlined☼
    2              2            Green           1             On☼
    3              3            Cyan            1             On☼
    4              4            Red             1             On☼
    5              5            Magenta         1             On☼
    6              6            Brown           1             On☼
    7              7            White           1             On☼
    8              8            Gray            0             Off
    9              9            Light blue                    High intensity
                                                            Underlined
    10             10           Light green     2             High intensity
    11             11           Light cyan      2             High intensity
    Attributes     Color Display                Monochrome Display
                    Number☼      Color           Number☼       Color
    ──────────────────────────────────────────────────────────────────────────
    11             11           Light cyan      2             High intensity
    12             12           Light red       2             High intensity
    13             13           Light magenta   2             High intensity
    14             14           Yellow          2             High intensity
    15             15           High-intensity  0             Off
                                white
    ──────────────────────────────────────────────────────────────────────────


■ Example

    See the LINE, CIRCLE, and DRAW statements for examples of the SCREEN
    statement.


────────────────────────────────────────────────────────────────────────────
SEEK Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current file position

■ Syntax

    SEEK(filenumber)

■ Remarks

    The filenumber is the number used in the OPEN statement to open the file.
    SEEK returns a value in the range 1 to 2,147,483,647 (equivalent to
    2^31-1).

    SEEK returns the number of the next record read or written when used on
    RANDOM mode files. For files opened in BINARY, OUTPUT, APPEND, or INPUT
    mode, SEEK returns the byte position in the file where the next operation
    is to take place. The first byte in a file is 1.

    When used on a device that does not support SEEK, the function returns
    zero. The BASIC devices (SCRN:, CONS:, KYBD:, COMn:, and LPTn:) do not
    support SEEK.

    See Chapter 3, "File and Device I/O," in Programming in BASIC for more
    information.

■ See Also

    GET (File I/O), OPEN, PUT (File I/O), SEEK Statement

■ Example

    The following code fragment prints a message indicating whether the last
    read or write was done in the first, second, or final third of the file:

    SELECT CASE (SEEK(1))
        CASE IS < .333*LOF(1)
        PRINT "In first third of file."
        CASE .333*LOF(1) TO .667*LOF(1)
        PRINT "In second third of file."
        CASE IS >= .667*LOF(1)
        PRINT "In last third of file."
        CASE ELSE
    END SELECT


────────────────────────────────────────────────────────────────────────────
SEEK Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the position in a file for the next read or write

■ Syntax

    SEEK «#»filenumber,position

■ Remarks

    The filenumber is an integer number used in the OPEN statement to open the
    file.

    The position is a numeric expression indicating where the next read or
    write is done. The position must be in the range 1 to 2,147,483,647
    (equivalent to 2^31-1). For files opened in RANDOM mode, position is the
    number of a record in the file.

    For files opened in BINARY, INPUT, OUTPUT, or APPEND modes, position is
    the number of a byte from the beginning of the file. The first byte in a
    file is 1. After a SEEK, the next file I/O operation starts at that byte
    in the file.

────────────────────────────────────────────────────────────────────────────
NOTE
    Record numbers on a GET or PUT override the file positioning done by SEEK.
────────────────────────────────────────────────────────────────────────────

    Performing a file write after doing a SEEK beyond the end of a file
    extends the file. A SEEK to a negative or zero position produces an error
    message that reads Bad record number.

    When used on a device that does not support SEEK, BASIC ignores SEEK and
    leaves the file position unchanged. The BASIC devices (SCRN:, CONS:,
    KYBD:, COMn:, and LPTn:) do not support SEEK.

    See Chapter 3, "File and Device I/O," in Programming in BASIC for more
    information.

■ See Also

    GET (File I/O), OPEN, PUT (File I/O), SEEK Function

■ Example

    The following code fragment uses a combination of the SEEK function and
    SEEK statement to back up the file position and rewrite a record if a
    variable is true (nonzero):

    CONST FALSE=0, TRUE=NOT FALSE
    .
    .
    .
    IF ReWriteFlag = TRUE THEN
        ' Back up file by the length of the record variable that
        ' is used to write to the file.
        SEEK #1, SEEK(1)-LEN(RecordVar)
        PUT #1,,RecordVar
    END IF


────────────────────────────────────────────────────────────────────────────
SELECT CASE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    The following list describes the parts of the SELECT CASE statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    testexpression           Any numeric or string expression.

    statementblock-1,        The elements statementblock-1 to statementblock-n
    statementblock-2,        consist of any number of statements on one or
    statementblock-n         more lines.

    expressionlist1,         These elements can have any of the three
    expressionlist2          following forms: expression«,expression...»
                            expression TO expression IS relational-operator
                            expression
    ──────────────────────────────────────────────────────────────────────────

    The following list describes the parts of an expressionlist:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    expression               Any numeric or string expression. The type of the
                            expression must match the type of the expression
                            being tested.

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────

    relational-operator      Any of the following operators:

                            Symbol                  Meaning

                            <                       Less than

                            <=                      Less than or equal to

                            >                       Greater than

                            >=                      Greater than or equal to

                            <>                      Not equal

                            =                       Equal

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

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────


    If the testexpression matches the expressionlist associated with a CASE
    clause, then the statement block following that CASE clause is executed up
    to the next CASE clause or, for the last one, up to END SELECT. Control
    then passes to the statement following END SELECT.

    If you use the TO keyword to indicate a range of values, the smaller value
    must appear first. For example, the statements associated with the line
    CASE -1 TO -5 are not executed if the testexpression is -4. The line
    should be written as CASE -5 TO -1.

    You may use a relational operator only if the IS keyword appears. If CASE
    ELSE is used, its associated statements are executed only if the
    testexpression does not match any of the other CASE selections. It is a
    good idea to have a CASE ELSE statement in your SELECT CASE block to
    handle unforeseen testexpression values.

    When there is no CASE ELSE statement and no expression listed in the CASE
    clauses matches testexpression, program execution continues normally. No
    error occurs.

    You may use multiple expressions or ranges in each CASE clause. For
    example, the following line is valid:

    CASE 1 TO 4, 7 TO 9, 11, 13, IS > MaxNumber%

    You may also specify ranges and multiple expressions for strings:

    CASE "everything", "nuts" TO "soup", TestItem$

    CASE matches strings that are exactly equal to everything, the current
    value of TestItem$, or that fall between nuts and soup in alphabetical
    order.

    Strings are evaluated according to the ASCII values of their characters.
    Lowercase letters have larger ASCII values than uppercase letters, so

    nuts  >  Nuts  >  NUTS

    If an expression appears in more than one CASE clause, only the statements
    associated with the first appearance of the expression are executed.

    SELECT CASE statements may be nested. Each SELECT CASE statement must have
    a matching END SELECT statement.

■ Example

    In the following program, the SELECT CASE statement is used to take
    different actions based on the input value:

    ' Program demonstrates various forms of CASE items
        INPUT "Enter acceptable level of risk (1-10): ", Total
        SELECT CASE Total

            CASE IS >= 10
                PRINT "Maximum risk and potential return"
                PRINT "Choose stock investment plan"

            CASE  6 TO 9
                PRINT "High risk and potential return"
                PRINT "Choose corporate bonds"

            CASE  2 TO 5
                PRINT "Moderate risk and return"
                PRINT "Choose mutual fund"

            CASE 1
                PRINT "No risk, low return"
                PRINT "Choose IRA"

            CASE ELSE
                PRINT "RESPONSE OUT OF RANGE"

        END SELECT

■ Output

    Enter acceptable level of risk (1-10): 10
    Maximum risk and potential return
    Choose stock investment plan

    Enter acceptable level of risk (1-10): 0
    RESPONSE OUT OF RANGE


────────────────────────────────────────────────────────────────────────────
SETMEM Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Changes the amount of memory used by the far heap──the area where far
    objects and internal tables are stored

■ Syntax

    SETMEM(numeric-expression)

■ Remarks

    The SETMEM function increases or decreases the far heap by the number of
    bytes indicated by numeric-expression. If the numeric-expression is
    negative, SETMEM decreases the far heap by the indicated number of bytes.
    When the numeric-expression is positive, SETMEM attempts to increase the
    far heap space by the number of bytes.

    SETMEM returns the total number of bytes in the far heap. If the
    numeric-expression is zero, SETMEM returns the current size of the far
    heap. If SETMEM cannot change the far heap by the requested number of
    bytes, it reallocates as many bytes as possible.

    SETMEM can be used in mixed-language programming to decrease the far heap
    space so procedures in other languages can dynamically allocate far
    memory. A first call to SETMEM trying to increase the far heap has no
    effect because BASIC allocates as much memory as possible to the far heap
    when a program starts.

■ Example

    The following program outlines how SETMEM could be used to free memory for
    a C function that uses malloc to get dynamic memory. The C function is
    separately compiled and then put in a Quick library or linked to the BASIC
    program. The C function is compiled using the large memory model, so calls
    to malloc use the far space freed by the BASIC program.

    DEFINT A-Z
    DECLARE SUB CFunc CDECL (BYVAL X AS INTEGER)

    ' Decrease the size of the far heap so CFunc can use
    ' malloc to get dynamic memory.
    BeforeCall=SETMEM(-2048)

    ' Call the C function.
    CFunc(1024%)

    ' Return the memory to the far heap; use a larger value so
    ' all space goes back into the heap.
    AfterCall=SETMEM(3500)

    IF AfterCall <= BeforeCall THEN PRINT "Memory not reallocated."

    END

    void far cfunc(bytes)
    int bytes;
    {
        char *malloc();
        char *workspace;

        /* Allocate working memory using amount BASIC freed. */
        workspace=malloc((unsigned) bytes);

        /* Working space would be used here. */

        /* Free memory before returning to BASIC. */
        free(workspace);
    }


────────────────────────────────────────────────────────────────────────────
SGN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Indicates the sign of a numeric expression

■ Syntax

    SGN(numeric-expression)

■ Remarks

    The SGN function returns a value depending on the sign of its argument:

    If numeric-expression > 0, then SGN(numeric-expression) returns 1.

    If numeric-expression = 0, then SGN(numeric-expression) returns 0.

    If numeric-expression < 0, then SGN(numeric-expression) returns -1.

■ Example

    The following program calculates and prints the solution for a quadratic
    (or for a second-degree) equation. The program uses the sign of a test
    expression to determine how to calculate the solution.

    CONST NoRealSoln=-1, OneSoln=0, TwoSolns=1
    ' Input coefficients of quadratic equation:
    ' ax^2 + bx + c = 0.
    INPUT;"a = ",   A
    INPUT;",  b = ",B
    INPUT ",  c = ",C
    Test = B^2 - 4*A*C
    SELECT CASE SGN(Test)
        CASE  NoRealSoln
        PRINT "This equation has no real-number solutions."
        CASE  OneSoln
        PRINT "This equation has one solution: ";
        PRINT -B/(2*A)
        CASE  TwoSolns
        PRINT "This equation has two solutions: ";
        PRINT (-B + SQR(Test))/(2*A) " and ";
        PRINT (-B - SQR(Test))/(2*A)
    END SELECT

■ Output

    a = 12,  b = -5,  c = -2
    This equation has two solutions:  .6666667          -.25


────────────────────────────────────────────────────────────────────────────
SHARED Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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»»...

■ Remarks

    The argument variable is either an array name followed by () or a variable
    name. The AS clause can be used to indicate the variable's type. The type
    argument can be INTEGER, LONG, SINGLE, DOUBLE, STRING, fixed-length string
    (STRING*length), or a user-defined type.

    By using either the SHARED statement in a SUB or FUNCTION procedure, or
    the SHARED attribute with COMMON or DIM in the module-level code, you can
    use variables in a procedure without passing them as parameters. The
    SHARED attribute shares variables among all procedures in a module, while
    the SHARED statement shares variables between a single procedure and the
    module-level code.

────────────────────────────────────────────────────────────────────────────
NOTE
    The SHARED statement only shares variables within a single compiled
    module. It does not share variables with programs in the Quick library or
    with procedures compiled separately and linked to the program. The SHARED
    statement only shares variables between the module-level code and a SUB or
    FUNCTION in the same module.
────────────────────────────────────────────────────────────────────────────

    The SHARED statement can appear only in a SUB or FUNCTION. For more
    information see Chapter 2, "SUB and FUNCTION Procedures," in Programming
    in BASIC and Chapter 4, "Programs and Modules," in this manual.

■ See Also

    COMMON, DIM, SUB

■ Example

    The following program calls a subprogram named CONVERT that converts the
    input decimal number to its string representation in the given new base.
    The string N$ is shared by the subprogram and the main program.

    DEFINT A-Z
    DO
        INPUT "Decimal number (input number <= 0 to quit): ",Decimal
        IF Decimal <= 0 THEN EXIT DO
        INPUT "New base: ",Newbase
        N$ = ""
        PRINT Decimal "base 10 equals ";
        DO WHILE Decimal > 0
        CALL Convert (Decimal,Newbase)
        Decimal = Decimal\Newbase
        LOOP
        PRINT N$ " base" Newbase
        PRINT
    LOOP

    SUB Convert (D,Nb) STATIC
    SHARED N$
        ' Take the remainder to find the value of the current
        ' digit.
        R = D MOD Nb
        ' If the digit is less than ten, return a digit (0...9).
        ' Otherwise, return a letter (A...Z).
        IF R < 10 THEN Digit$ = CHR$(R+48) ELSE Digit$ = CHR$(R+55)
        N$ = RIGHT$(Digit$,1) + N$
    END SUB

■ Output

    Decimal number (input number <= 0 to quit): 256
    New base: 2
    256 base 10 equals 100000000 base 2

    Decimal number (input number <= 0 to quit): 31
    New base: 16
    31 base 10 equals 1F base 16

    Decimal number (input number <= 0 to quit): -1


────────────────────────────────────────────────────────────────────────────
SHELL Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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»

■ Remarks

    The commandstring must be a valid string expression containing the name of
    a program to run and any program options.

    Any .COM file, .EXE file, .BAT program, or DOS function that runs under
    the SHELL statement is called a "child process." Child processes are
    executed by the SHELL statement, loading and running a copy of COMMAND.COM
    with the /C option automatically; this option allows any parameters in
    commandstring to be passed to the child process. It also allows
    redirection of standard input and output, and execution of built-in
    commands such as DIR, PATH, and SORT.

    The program name in commandstring may have any extension you wish. If no
    extension is supplied, COMMAND.COM looks for a .COM file, then an .EXE
    file, and finally, a .BAT file. If COMMAND.COM is not found, SHELL issues
    an error message that reads File not found. BASIC does not generate an
    error if COMMAND.COM cannot find the file specified in commandstring.

    Any text separated from the program name by at least one blank is treated
    as program parameters by COMMAND.COM. BASIC remains in memory while the
    child process is running. When the child process finishes, BASIC
    continues.

    SHELL with no commandstring gives you a new COMMAND.COM shell. You may now
    do anything that COMMAND.COM allows. Enter the DOS command EXIT when you
    are ready to return to BASIC.

■ Examples

    This example shows how a SHELL statement starts up a new COMMAND.COM:

    SHELL   'Get a new COMMAND.COM.

■ Output

    The IBM Personal Computer DOS
    Version 3.20 (C)Copyright International
    Business Machines Corp 1981, 1986 (C)Copyright
    Microsoft Corp 1981, 1986

    D:\QB4>

    The following example copies all files modified on a certain date from a
    specified directory:

    ' This program copies all files in this directory modified
    ' on a certain date to the drive and directory you specify.

    DECLARE FUNCTION GetName$ (DirLine$)
    LINE INPUT "Enter target drive and directory: ",PathSpec$
    SHELL "DIR > DIRFILE"
    'Store directory listing in DIRFILE.
    DO
        OPEN "DIRFILE" FOR INPUT AS #1
        INPUT "Enter date (MM-DD-YY): ",MDate$
        PRINT

        ' Read DIRFILE, test for input date.
        DO
        LINE INPUT #1, DirLine$
        ' Test directory line to see if date matches and the line
        ' is not one of the special directories ( . or .. ).
        IF INSTR(DirLine$,MDate$) > 0 AND LEFT$(DirLine$,1) <> "." THEN
            FileSpec$ = GetName$(DirLine$)
            ' Make sure we don't move our temporary file.
            IF FileSpec$ <> "DIRFILE" THEN
                ' Build the DOS command line to copy the file.
                DoLine$ = "COPY " + FileSpec$ + "  " + PathSpec$
                PRINT DoLine$
                ' Copy the file.
                SHELL DoLine$
            END IF
        END IF
        LOOP UNTIL EOF(1)

    CLOSE #1
        PRINT "New date?"
        R$ = INPUT$(1)
        CLS
    LOOP UNTIL UCASE$(R$) <> "Y"
    ' KILL "DIRFILE".
    END

    ' This function gets the file name and extension from
    ' the directory-listing line.
    FUNCTION GetName$ (DirLine$) STATIC
        BaseName$ = RTRIM$(LEFT$(DirLine$,8))

        ' Check for extension.
        ExtName$  = RTRIM$(MID$(DirLine$,10,3))

        IF ExtName$ <> "" THEN
        BaseName$ = BaseName$ + "." + ExtName$
        END IF

        GetName$ = BaseName$
    END FUNCTION

■ Output

    Enter target drive and directory: c:\bas\temp
    Enter date (MM-DD-YY): 6-11-87

    COPY CONF.DAT  c:\bas\temp
    COPY TEST.BAS  c:\bas\temp
    COPY TEMPFILE  c:\bas\temp

    New date? n


────────────────────────────────────────────────────────────────────────────
SIN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the sine of the angle x, where x is in radians

■ Syntax

    SIN(x)

■ Remarks

    When x is a double-precision value, the SIN function is calculated with
    double-precision accuracy. When x is not double precision, SIN is
    calculated with single-precision accuracy.

■ See Also

    ATN, COS, TAN

■ Example

    The example plots the graph of the polar equation r = 1 + sin n (Θ). This
    figure is sometimes known as a cardioid, owing to its resemblance to a
    heart when n equals 1.

    CONST PI = 3.141593
    SCREEN 1 : COLOR 1,1      'Medium resolution, blue background.
    WINDOW (-3,-2)-(3,2)      'Convert screen to Cartesian
                            'coordinates.
    INPUT "Number of petals = ", N
    CLS
    PSET (1,0)         'Set initial point.
    FOR Angle = 0 TO 2*PI STEP .02
        R = 1 + SIN(N*Angle)   'Polar equation for "flower."
        X = R * COS(Angle)     'Convert polar coordinates to
        Y = R * SIN(Angle)     'Cartesian coordinates.
        LINE -(X,Y)         'Draw line from previous point to
                            'new point.
    NEXT


────────────────────────────────────────────────────────────────────────────
SLEEP Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Suspends execution of the calling program

■ Syntax

    SLEEP  « seconds »

■ Remarks

    The optional argument seconds determines the number of seconds the program
    is suspended. The SLEEP statement suspends the program until one of the
    following events occurs:

    ■ The time period in the seconds argument elapses.

    ■ A key is pressed.

    ■ An enabled event occurs.

    If seconds is zero or not specified, the program is suspended
    indefinitely. Only an enabled event or a keystroke can interrupt an
    indefinite suspension.

    SLEEP responds only to keystrokes that occur after it executes. SLEEP
    ignores characters in the keyboard buffer that were typed before it
    executed.

    An event (such as ON COM or ON TIMER) cannot interrupt a SLEEP suspension
    unless its trapping is active when the event occurs. This means that
    trapping must have been initialized with an ON event statement, turned on
    with an event ON statement, and not have been disabled with an event OFF
    statement or an event STOP statement.

■ See Also

    WAIT

■ Example

    The following program suspends execution for 10 seconds. There is no ON
    event statement, so the only way to interrupt the suspension before 10
    seconds have passed is to press a key.

    PRINT "Taking a 10 second nap..."
    SLEEP 10
    PRINT "Awake!"
    END


────────────────────────────────────────────────────────────────────────────
SOUND Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Generates sound through the speaker

■ Syntax

    SOUND frequency,duration

■ Remarks

    The frequency is the desired frequency in hertz (cycles/second). It must
    be a numeric expression returning an integer in the range 37-32,767.

    The duration is the duration in clock ticks. (There are 18.2 clock ticks
    per second regardless of CPU speed.) The duration must be a numeric
    expression returning an unsigned integer in the range 0-65,535.

    If the duration is zero, any current SOUND statement that is running is
    turned off. If no SOUND statement is running, a SOUND statement with a
    duration of zero has no effect.

■ SEE ALSO

    PLAY

■ Example

    This program fragment produces a rising and descending glissando:

    FOR I = 440 TO 1000 STEP 5
        SOUND I, I/1000
    NEXT
    FOR I = 1000 TO 440 STEP -5
    SOUND I, I/1000
    NEXT


────────────────────────────────────────────────────────────────────────────
SPACE$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string of spaces of length n

■ Syntax

    SPACE$(n)

■ Remarks

    The expression n is rounded to an integer and must be in the range
    0-32,767.

■ See Also

    SPC

■ Example

    This example illustrates the use of SPACE$:

    FOR I=1 TO 5
        X$=SPACE$(I)
        PRINT X$;I
    NEXT I

■ Output

    1
    2
        3
        4
        5


────────────────────────────────────────────────────────────────────────────
SPC Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Skips n spaces in a PRINT statement

■ Syntax

    SPC(n)

■ Remarks

    SPC may only be used with PRINT and LPRINT statements. The argument n must
    be in the range 0-32,767. A semicolon (;) is assumed to follow the SPC(n)
    command.

■ See Also

    SPACE$

■ Example

    This example illustrates the use of SPC:

    PRINT "OVER";SPC(15) "THERE"

■ Output

    OVER               THERE


────────────────────────────────────────────────────────────────────────────
SQR Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the square root of n

■ Syntax

    SQR(n)

■ Remarks

    The argument n must be >= 0.

■ Example

    The following program plots the graphs of y = √-x for -9 <= x < 0 and of y
    = √x for 0 <= x <= 9:

    SCREEN 1 : COLOR 1         'Low-resolution color graphics mode.
    WINDOW (-9,-.25)-(9,3.25)  'Convert screen to Cartesian
                                'coordinates.
    LINE (-9,0)-(9,0)          'Draw X-axis.
    LINE (0,-.25)-(0,3.25)     'Draw Y-axis.

    FOR X = -9 TO 9
        LINE(X,.04)-(X,-.04)   'Put tick marks on X-axis.
    NEXT

    FOR Y = .25 TO 3.25 STEP .25
        LINE (-.08,Y)-(.12,Y)  'Put tick marks on Y-axis.
    NEXT

    PSET (-9,3)                'Plot the first point of function.
    FOR X = -9 TO 9 STEP .25
        Y = SQR(ABS(X))
        'SQR argument cannot be negative.
        LINE -(X,Y),2          'Draw a line to the next point.
    NEXT


────────────────────────────────────────────────────────────────────────────
STATIC Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    A STATIC statement variablelist has the following syntax:

    variable«( )»«AS type» «, variable«( )»«AS type»»...

    The variablelist takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    variable                 Either a variable name or an array name.

    AS type                  Declares the type of variable. The type argument
                            can be INTEGER, LONG, SINGLE, DOUBLE, STRING, or
                            a user-defined type.
    ──────────────────────────────────────────────────────────────────────────

    The STATIC statement can appear only in a SUB, FUNCTION, or DEF FN
    function. Earlier versions of BASIC required the number of dimensions in
    parentheses after an array name. In QuickBASIC, the number of dimensions
    is optional.

    Variables declared in a STATIC statement override variables of the same
    name shared by DIM or COMMON statements in the module-level code.
    Variables in a STATIC statement also override global constants of the same
    name.

    Usually, variables used in DEF FN functions are global to the module;
    however, you can use the STATIC statement inside a DEF FN statement to
    declare a variable as local to only that function.

────────────────────────────────────────────────────────────────────────────
NOTE
    The STATIC attribute on SUB and FUNCTION statements declares the default
    for variables to be static. Variables having the same name as variables
    shared by the module-level code are still shared. In contrast, the STATIC
    statement makes specific variables static and overrides any variables
    shared by the module-level code. The ¢STATIC metacommand affects how
    memory is allocated for arrays. See Chapter 2, "Data Types," for a
    discussion of the differences among these statements and attributes.
────────────────────────────────────────────────────────────────────────────

■ See Also

    COMMON, DEF FN, DIM, FUNCTION, SHARED, SUB

■ Examples

    This example contrasts the STATIC and SHARED statements within a
    subprogram AUGMENT. The variables R and N are both local to this
    subprogram, while the variables REP and NUM are shared between the main
    program and the subprogram. The STATIC R,N statement ensures that R and N
    retain the last values assigned to them each time the main program calls
    the subprogram.

    Rep = 0 : Num = 0
    PRINT "Before loop, REP = ";Rep;", NUM = ";Num;
    PRINT ", R = ";R;", N = ";N
    FOR I = 1 TO 10
        CALL Augment
    NEXT
    PRINT "After loop, REP = ";Rep;", NUM = ";Num;
    PRINT ", R = ";R;", N = ";N
    END

    SUB Augment STATIC
    SHARED Rep,Num    'Shared with main program.
    STATIC R,N        'Not shared with main program.
        R = R + 1      'Both R and N initially equal 0.
        N = N + 2
        Rep = R
        Num = N
    END SUB

■ Output

    Before loop, REP = 0 , NUM = 0 , R = 0 , N = 0
    After loop, REP = 10 , NUM = 20 , R = 0 , N = 0

    The following program searches for every occurrence of a certain string
    expression (stored in the variable OLD$) in the specified file and
    replaces that string with the string stored in NW$. The name of the file
    with these changes is the old filename with the extension .NEW. The
    program also prints the number of substitutions and the number of lines
    changed.

    INPUT "Name of file";F1$
    INPUT "String to replace";Old$
    INPUT "Replace with";Nw$
    Rep = 0 : Num = 0
    M = LEN(Old$)
    OPEN F1$ FOR INPUT AS #1
    CALL Extension
    OPEN F2$ FOR OUTPUT AS #2

    DO WHILE NOT EOF(1)
        LINE INPUT #1, Temp$
        CALL Search
        PRINT #2, Temp$
    LOOP

    CLOSE
    PRINT "There were ";Rep;" substitutions in ";Num;" lines."
    PRINT "Substitutions are in file ";F2$
    END
    SUB Extension STATIC
    SHARED F1$,F2$
        Mark = INSTR(F1$,".")
        IF Mark = 0 THEN
        F2$ = F1$ + ".NEW"
        ELSE
        F2$ = LEFT$(F1$,Mark - 1) + ".NEW"
        END IF
    END SUB

    SUB Search STATIC
    SHARED Temp$,Old$,Nw$,Rep,Num,M
    STATIC R
        Mark = INSTR(Temp$,Old$)
        WHILE Mark
        Part1 = LEFT$(Temp$,Mark - 1)
        Part2 = MID$(Temp$,Mark + M)
        Temp$ = Part1$ + Nw$ + Part2$
        R = R + 1
        Mark = INSTR(Temp$,Old$)
        WEND
        IF Rep = R THEN
            EXIT SUB
        ELSE
            Rep = R
            Num = Num + 1
        END IF
    END SUB

■ Output

    Name of file? CHAP1.S
    String to replace? CHAPTER 1
    Replace with? INTRODUCTION
    There were 23 substitutions in 19 lines.
    Substitutions are in file CHAP1.NEW

    The file CHAP1.NEW now contains every line in CHAP1.S, with each
    occurrence of the string CHAPTER 1 replaced by INTRODUCTION.


────────────────────────────────────────────────────────────────────────────
STICK Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the x- and y-coordinates of the two joysticks

■ Syntax

    STICK(n)

■ Remarks

    The argument n is a numeric expression whose value is an unsigned integer
    in the range 0 to 3:

    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    0                        The x-coordinate of joystick A

    1                        The y-coordinate of joystick A when STICK(0) was
                            last called

    2                        The x-coordinate of joystick B when STICK(0) was
                            last called

    3                        The y-coordinate of joystick B when STICK(0) was
                            last called
    ──────────────────────────────────────────────────────────────────────────

    The x- and y-coordinates have a range of 1 to 200. You must use STICK(0)
    before you use STICK(1), STICK(2), or STICK(3). STICK(0) not only returns
    the x-coordinate of joystick A, it also records the other joystick
    coordinates. These recorded coordinates are returned by calling
    STICK(1)-STICK(3).

■ Example

    The following fragment prints the coordinates of joystick B:

    TEMP = STICK(0)
    PRINT STICK(2), STICK(3)


────────────────────────────────────────────────────────────────────────────
STOP Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Terminates the program

■ Syntax

    STOP

■ Remarks

    STOP statements can be used anywhere in a program to terminate execution.

    When running in the QuickBASIC environment, the STOP statement leaves
    files open and does not exit to the operating system. In contrast, a STOP
    statement in a stand-alone .EXE file does close all files and return to
    the operating system.

    If you use the /D, /E, or /X compile options on the bc command line, the
    STOP statement prints the number of the line where execution stopped, if
    your program has line numbers. If there is no line number associated with
    the STOP statement, the most recent line number is printed. If your
    program has no line numbers, then the line number printed is 0.

    In the past, STOP statements were used for debugging. QuickBASIC's new
    debugging features make this use of STOP unnecessary.

■ Example

    There is no programming example for the STOP statement.


────────────────────────────────────────────────────────────────────────────
STR$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string representation of the value of a numeric expression

■ Syntax

    STR$(numeric-expression)

■ Remarks

    If numeric-expression is positive, the string returned by the STR$
    function contains a leading blank. The VAL function complements STR$.

■ See Also

    VAL

■ Example

    The following example contains a FUNCTION that uses the STR$ function to
    convert a number to its string representation. The FUNCTION then strips
    out the leading and trailing blanks that BASIC prints with numeric output.

    FUNCTION NumRemBlanks$(X) STATIC
        X$ = STR$(X)
        NumRemBlanks$ = LTRIM$(RTRIM$(X$))
    END FUNCTION

    PRINT "Enter 0 to end."
    DO
        INPUT "Find cosine of: ",Num
        IF Num = 0 THEN EXIT DO
        PRINT "COS(" NumRemBlanks$(Num) ") = " COS(Num)
    LOOP

■ Output

    Enter 0 to end.
    Find cosine of: 3.1
    COS(3.1) = -.9991351
    Find cosine of: 0


────────────────────────────────────────────────────────────────────────────
STRIG Function and Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the status of a specified joystick trigger

■ Syntax 1 (Function)

    STRIG(n)

■ Syntax 2 (Statement)

    STRIG {ON | OFF}

■ Remarks

    The STRIG function is used to test the joystick trigger status. In
    previous versions of BASIC, the statement STRIG ON enables testing of the
    joystick triggers; STRIG OFF disables joystick trigger testing. QuickBASIC
    ignores STRIG ON and STRIG OFF statements──the statements are provided for
    compatibility with earlier versions.

    The numeric expression n is an unsigned integer in the range 0-7,
    indicating the joystick and trigger to check. The following list describes
    the values returned by the STRIG(n) function for different values of n:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    0                        Returns -1 if the lower button on joystick A has
                            been pressed since the last STRIG(0) call;
                            otherwise returns 0

    1                        Returns -1 if the lower button on joystick A is
                            currently down; otherwise returns 0

    2                        Returns -1 if the lower button on joystick B has
    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    2                        Returns -1 if the lower button on joystick B has
                            been pressed since the last STRIG(2) call;
                            otherwise returns 0

    3                        Returns -1 if the lower button on joystick B is
                            currently down; otherwise returns 0

    4                        Returns -1 if the upper button on joystick A has
                            been pressed since the last STRIG(4) call;
                            otherwise returns 0

    5                        Returns -1 if the upper button on joystick A is
                            currently down; otherwise returns 0

    6                        Returns -1 if the upper button on joystick B has
                            been pressed since the last STRIG(6) call;
                            otherwise returns 0

    7                        Returns -1 if the upper button on joystick B is
    Argument                 Value Returned
    ──────────────────────────────────────────────────────────────────────────
    7                        Returns -1 if the upper button on joystick B is
                            currently down; otherwise returns 0
    ──────────────────────────────────────────────────────────────────────────


    You can also use event trapping to get information from the joystick by
    using the ON STRIG statement (see the ON event statement). You cannot use
    the STRIG function inside a joystick event trap because the event that
    caused the trap is destroyed.

■ Differences From Basica

    If you are compiling from the BC command line, you must use the /V or /W
    option if a program contains a STRIG statement.

■ See Also

    ON event; STRIG ON, OFF, and STOP

■ Example

    The following example illustrates STRIG:

    'Wait for trigger A to be pressed.
    DO
        GotATrig = STRIG(0)
    LOOP UNTIL GotATrig
    'As long as trigger A is down, beep.
    DO
        GotATrig = STRIG(1)
        BEEP
    LOOP WHILE GotATrig


────────────────────────────────────────────────────────────────────────────
STRIG ON, OFF, and STOP Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables, disables, or inhibits trapping of joystick activity

■ Syntax

    STRIG(n) ON
    STRIG(n) OFF
    STRIG(n) STOP

■ Remarks

    The argument, n, is a numeric expression indicating the joystick button to
    trap:

    Value                    Button
    ──────────────────────────────────────────────────────────────────────────
    0                        Lower button, joystick A
    2                        Lower button, joystick B
    4                        Upper button, joystick A
    6                        Upper button, joystick B
    ──────────────────────────────────────────────────────────────────────────

    The STRIG(n) ON statement enables joystick event trapping by an ON STRIG
    statement (see the ON event statement). While trapping is enabled, and if
    a nonzero line number is specified in the ON STRIG statement, BASIC checks
    between every statement to see if the joystick trigger has been pressed.

    The STRIG(n) OFF statement disables event trapping. If a subsequent event
    occurs (i.e., if the trigger is pressed), it will not be remembered when
    the next STRIG ON is executed.

    The STRIG(n) STOP statement inhibits event trapping. If an event occurs it
    is remembered, and the event trap takes place as soon as trapping is
    reenabled.

■ See Also

    ON event, STRIG

■ Example

    There is no programming example for the STRIG statement.


────────────────────────────────────────────────────────────────────────────
STRING$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    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)

■ Remarks

    The STRING$ function has the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    m                        A numeric expression indicating the length of the
                            string to return.

    n                        The ASCII code of the character to use to build
                            the string. It is a numeric expression that
                            evaluates to an integer value in the range 0-255.

    stringexpression         The string expression whose first character is
                            used to build the return string.
    ──────────────────────────────────────────────────────────────────────────

■ Examples

    The following example uses STRING$ to create part of a report heading:

    Dash$ = STRING$(10,45)
    PRINT Dash$;"MONTHLY REPORT";Dash$

■ Output

    ----------MONTHLY REPORT----------

    The following program uses STRING$ to generate a bar graph:

    PRINT TAB(7);"Daily Mean Temperature in Seattle" :
    PRINT
    'Get data for each month and graph.
    FOR Month = 1 TO 12 STEP 2
        READ Month$, Temp
        'Print Temp-35 stars.
        PRINT Month$;" +"; STRING$(Temp-35,"*")
        PRINT "    |"
    NEXT Month

    'Print horizontal line.
    PRINT "    +";
    FOR X = 1 TO 7
        PRINT "----+";
    NEXT X
    PRINT

    'Print temperature labels.
    FOR X = 4 TO 39 STEP 5
        PRINT TAB(X); X+31;
    NEXT X
    PRINT

    DATA Jan, 40, Mar, 46, May, 56
    DATA Jul, 66, Sep, 61, Nov, 46

■ Output

    Daily Mean Temperature in Seattle

    Jan +*****
        |
    Mar +***********
        |
    May +*********************
        |
    Jul +*******************************
        |
    Sep +**************************
        |
    Nov +***********
        |
        +----+----+----+----+----+----+----+
        35   40   45   50   55   60   65   70


────────────────────────────────────────────────────────────────────────────
SUB Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Marks the beginning and end of a subprogram

■ Syntax

    SUB globalname«(parameterlist)» «STATIC»
    .
    .
    .
    «EXIT SUB»
    .
    .
    .
    END SUB

■ Remarks

    The SUB statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    globalname               A variable name up to 40 characters long. This
                            name cannot appear in any other FUNCTION or SUB
                            statement in the same program or the user
                            library.

    parameterlist            Contains the names of simple variables and arrays
                            passed to the subprogram when the SUB is invoked.
                            Each name is separated from the preceding name by
                            a comma. Note that these variables and arrays are
                            passed by reference, so any change to an
                            argument's value in the subprogram also changes
                            its value in the calling program. See below for a
                            complete description of the syntax.
    ──────────────────────────────────────────────────────────────────────────

    A SUB parameterlist has the following syntax:

    variable«( )» «AS type» «, variable«( )» «AS type»»...

    A variable is a BASIC variable name. Previous versions of BASIC required
    the number of dimensions in parentheses after an array name. In
    QuickBASIC, the number of dimensions is not required. The argument type is
    the type of the variable. The type argument can be INTEGER, LONG, SINGLE,
    DOUBLE, STRING, or a user-defined type. You may not use a fixed-length
    string, or an array of fixed-length strings, as a parameter. However, you
    may use a simple fixed-length string as an argument in a CALL
    statement──QuickBASIC converts a simple fixed-length string argument to a
    variable-length string argument before passing the string to a SUB.

    A subprogram is a separate procedure, like a FUNCTION. However, a SUB
    cannot be used in an expression, unlike a FUNCTION.

    SUB and END SUB mark the beginning and end of a subprogram. You may also
    use the optional EXIT SUB statement to exit a subprogram.

    Subprograms are called by a CALL statement or by using the subprogram name
    followed by the argument list. See the entry for the CALL statement.
    QuickBASIC subprograms can be recursive──they can call themselves to
    perform a given task. See the second example below and Section 4.4,
    "Recursion."

    The STATIC attribute indicates that all variables local to the SUB are
    static──their values are saved between calls. Using the STATIC keyword
    slightly increases execution speed. STATIC is not usually used with
    recursive subprograms. See the examples below.

    Any subprogram variables or arrays are considered local to that subprogram
    unless they are explicitly declared as shared variables in a SHARED
    statement. You cannot define SUB procedures, DEF FN functions, or FUNCTION
    procedures inside a SUB procedure.

────────────────────────────────────────────────────────────────────────────
NOTE
    You cannot use GOSUB, GOTO, or RETURN to enter or exit a subprogram.
────────────────────────────────────────────────────────────────────────────

    See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for
    more information.

■ See Also

    CALL (BASIC), DECLARE (BASIC), SHARED, STATIC

■ Examples

    In this example, the main program calls a subprogram, LINESEARCH, which
    searches for the given string, P$, in each line of input from file F$.
    When the subprogram finds P$ in a line, it prints the line, along with the
    number of the line. Notice that the value of Num is saved between calls
    because the STATIC keyword is used on the SUB statement.

    INPUT "File to be searched";F$
    INPUT "Pattern to search for";P$
    OPEN F$ FOR INPUT AS #1
    DO WHILE NOT EOF(1)
        LINE INPUT #1, Test$
        CALL Linesearch(Test$,P$)
    LOOP

    SUB Linesearch(Test$,P$) STATIC
        Num = Num + 1
        X = INSTR(Test$,P$)
        IF X > 0 THEN PRINT "Line #";Num;": ";Test$
    END SUB

■ Output

    File to be searched? search.bas
    Pattern to search for? SUB
    Line # 9 : SUB Linesearch(Test$,P$) STATIC
    Line # 13 : END SUB

    The following example uses a recursive SUB to solve the classic Tower of
    Hanoi puzzle for a variable number of disks. For large numbers of disks,
    the stack size must be increased using the CLEAR statement.

    DECLARE SUB Hanoi (N%, Srce%, Dest%, Hold%)
    DEFINT A-Z
    DIM SHARED MoveCount

    MoveCount = 0
    CLS
    PRINT "Tower of Hanoi Puzzle"
    INPUT "Enter number of disks: ", Disks

    ' Call the recursive Hanoi SUB to solve the puzzle.
    CALL Hanoi(Disks, 1, 3, 2)

    PRINT "Puzzle complete in"; MoveCount; "moves."

    END

    ' Move N disks from Srce to Dest using Hold as holding peg.
    SUB Hanoi (N, Srce, Dest, Hold)
        IF N <= 1 THEN
        ' Only 1 disk. Move it directly to Dest.
        PRINT "Move a disk from"; Srce; "to"; Dest
        MoveCount = MoveCount + 1
        ELSE
        ' More than one disk.
        ' Move the N-1 disks to Hold, using Dest as holding peg.
        CALL Hanoi(N - 1, Srce, Hold, Dest)
        ' Move the Nth disk directly to Dest.
        PRINT "Move a disk from"; Srce; "to"; Dest:
        MoveCount = MoveCount + 1
        ' Move the N-1 disks to Dest, using Srce as holding peg.
        CALL Hanoi(N - 1, Hold, Dest, Srce)
        END IF
    END SUB

■ Output

    Tower of Hanoi Puzzle
    Enter number of disks: 3
    Move a disk from 1 to 3
    Move a disk from 1 to 2
    Move a disk from 3 to 2
    Move a disk from 1 to 3
    Move a disk from 2 to 1
    Move a disk from 2 to 3
    Move a disk from 1 to 3
    Puzzle complete in 7 moves.


────────────────────────────────────────────────────────────────────────────
SWAP Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Exchanges the values of two variables

■ Syntax

    SWAP variable1,variable2

■ Remarks

    Any type of variable can be swapped (integer, long, single precision,
    double precision, string, or record). However, the two variables must be
    exactly the same type or an error message appears (Type mismatch). For
    example, trying to swap an integer with a single-precision value produces
    Type mismatch.

■ Example

    The following subroutine (ShellSort) sorts the elements of a string array
    in descending order using a Shell sort. ShellSort uses SWAP to exchange
    array elements that are out of order.

    ' Sort the word list using a Shell sort.
    SUB ShellSort (Array$(), Num%) STATIC
        Span% = Num% \ 2
        DO WHILE Span% > 0
        FOR I% = Span% TO Num% - 1

            J% = I% - Span% + 1
        FOR J% = (I% - Span% + 1) TO 1 STEP -Span%

        IF Array$(J%) <= Array$(J% + Span%) THEN EXIT FOR
        ' Swap array elements that are out of order.
        SWAP Array$(J%), Array$(J% + Span%)
    NEXT J%

        NEXT I%
        Span% = Span% \ 2
        LOOP
    END SUB


────────────────────────────────────────────────────────────────────────────
SYSTEM Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Closes all open files and returns control to the operating system

■ Syntax

    SYSTEM

■ Remarks

    When a SYSTEM command is executed, all files are closed and BASIC exits to
    the operating system (for stand-alone executable programs) or stops
    program execution (if the program is run in the QuickBASIC environment).

────────────────────────────────────────────────────────────────────────────
NOTE
    A program containing a SYSTEM statement exits to the operating system if
    run from the QuickBASIC command line with the /RUN option. Entering a
    SYSTEM statement in the Immediate window terminates QuickBASIC.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    END and SYSTEM are distinct in BASICA but act identically in QuickBASIC.

■ Example

    There is no programming example for the SYSTEM statement.


────────────────────────────────────────────────────────────────────────────
TAB Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Moves the print position

■ Syntax

    TAB(column)

■ Remarks

    The argument, column, is a numeric expression that is the column number of
    the new print position. If the current print position is already beyond
    column, the TAB function moves the print position to that column on the
    next line. Column 1 is the leftmost position, and the rightmost position
    is the current line width of the output device minus one. If column is
    greater than the output width, TAB wraps the output and the print position
    becomes 1 + (column MOD width). If column is less than 1, TAB moves the
    print position to column 1.

    TAB can only be used in PRINT and LPRINT statements.

■ See Also

    WIDTH

■ Examples

    The following example uses TAB to locate columns of output:

    FOR I = 1 TO 4
        READ A$,B$
        PRINT A$ TAB(25) B$
    NEXT
    DATA NAME, AMOUNT,,, G.T. JONES, $25.00, H.L. STEVENS, $32.25

■ Output

    NAME                    AMOUNT

    G.T. JONES              $25.00
    H.L. STEVENS            $32.25

    The following example shows the effects of different values used as
    arguments to TAB:

    'Assumes 80-column screen width.
    PRINT TAB(1287); "one"
    PRINT TAB(255); "two"
    PRINT TAB(-5); "three"
    PRINT "123456789012345678901234567890" TAB(20) "four"

■ Output

        one
                two
    three
    123456789012345678901234567890
                        four


────────────────────────────────────────────────────────────────────────────
TAN Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the tangent of the angle x, where x is in radians

■ Syntax

    TAN(x)

■ Remarks

    TAN is calculated with single-precision accuracy unless x is a
    double-precision value, in which case TAN is calculated with
    double-precision accuracy.

■ Differences From Basica

    In BASICA, if TAN overflows, the interpreter displays the Overflow error
    message, returns machine infinity as the result, and continues execution.

    If TAN overflows, QuickBASIC does not display machine infinity and
    execution halts (unless the program has an error-handling routine).

■ Example

    The following example computes the height of an object using the distance
    from the object and the angle of elevation. The program draws the triangle
    produced by the base and the computed height.

    SCREEN 2

    INPUT "LENGTH OF BASE: ",Baselen
    INPUT "ANGLE OF ELEVATION (DEGREES,MINUTES): ",Deg,Min

    Ang = (3.141593/180)*(Deg + Min/60)   'Convert to radians.
    Height = Baselen*TAN(Ang)      'Calculate height.
    PRINT "HEIGHT =" Height
    H = 180 - Height
    B = 15 + Baselen

    LINE (15,180)-(B,180):LINE -(B,H)       'Draw triangle.
    LINE -(10,180)
    LOCATE 24,1 : PRINT "Press any key to continue...";
    DO
    LOOP WHILE INKEY$=""


────────────────────────────────────────────────────────────────────────────
TIME$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the current time from the operating system

■ Syntax

    TIME$

■ Remarks

    The TIME$ function returns an eight-character string in the pattern
    hh:mm:ss, where hh is the hour (00-23), mm is minutes (00-59), and ss is
    seconds (00-59). A 24-hour clock is used; therefore, 8:00 PM is shown as
    20:00:00.

    To set the time, use the TIME$ statement.

■ See Also

    TIME$ Statement, TIMER

■ Example

    The following example converts the 24-hour time returned by TIME$ to a
    12-hour time:

    'Convert the 24-hour clock used by TIME$ to
    '12-hour output followed by "AM" or "PM."
    T$ = TIME$
    Hr = VAL(T$)
    IF Hr < 12 THEN Ampm$ = " AM" ELSE Ampm$ = " PM"
    IF Hr > 12 THEN Hr = Hr - 12
    PRINT "The time is" STR$(Hr) RIGHT$(T$,6) Ampm$

■ Output

    The time is 11:26:31 AM


────────────────────────────────────────────────────────────────────────────
TIMER Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the number of seconds elapsed since midnight

■ Syntax

    TIMER

■ Remarks

    The TIMER function can be used with the RANDOMIZE statement to generate a
    random number. It can also be used to time programs or parts of programs.

■ Example

    The following program searches for the prime numbers from 3 to 10,000
    using a variation of the Sieve of Eratosthenes. The TIMER function is used
    to time the program.

    DEFINT A-Z
    CONST UNMARK = 0, MARKIT = NOT UNMARK
    DIM Mark(10000)
    Start! = TIMER
    Num = 0
    FOR N = 3 TO 10000 STEP 2
        IF NOT Mark(N) THEN
        'PRINT N,   'To print the primes, remove the
                    'remark delimiter in front of the
                    'PRINT statement.
        Delta = 2*N
        FOR I = 3*N TO 10000 STEP Delta
            Mark(I) = MARKIT
        NEXT
        Num = Num + 1
        END IF
    NEXT
    Finish! = TIMER
    PRINT : PRINT "Program took"; Finish!-Start!;
    PRINT "seconds to find the"; Num; "primes"
    END

■ Output

    Program took .1601563 seconds to find the 1228 primes


────────────────────────────────────────────────────────────────────────────
TIMER ON, OFF, and STOP Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables, disables, or inhibits timer event trapping

■ Syntax

    TIMER ON
    TIMER OFF
    TIMER STOP

■ Remarks

    TIMER ON enables timer event trapping by an ON TIMER statement (see the
    statement ON event). While trapping is enabled, a check is made after
    every statement to see if the specified time has elapsed. If it has, the
    ON TIMER event-handling routine is executed.

    TIMER OFF disables timer event trapping. If an event takes place, it is
    not remembered if a subsequent TIMER ON is executed.

    TIMER STOP disables the timer event trapping. However, if an event occurs,
    it is remembered and the ON TIMER event-handling routine is executed as
    soon as trapping is reenabled with TIMER ON.

■ See Also

    ON event

■ Example

    The following example displays the time of day on line 1, and updates the
    display once a minute:

    TIMER ON
    ON TIMER(60) GOSUB Display
    DO WHILE INKEY$ = "" : LOOP
    END

    Display:
        Oldrow = CSRLIN       'Save current row.
        Oldcol = POS(0)       'Save current column.
        LOCATE 1,1 : PRINT TIME$;
        LOCATE Oldrow,Oldcol   'Restore row & column.
    RETURN


────────────────────────────────────────────────────────────────────────────
TIME$ Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the time

■ Syntax

    TIME$=stringexpression

■ Remarks

    The stringexpression must be in one of the following forms:

    Form                     Description
    ──────────────────────────────────────────────────────────────────────────
    hh                       Sets the hour; minutes and seconds default to 00
    hh:mm                    Sets the hour and minutes; seconds default to 00
    hh:mm:ss                 Sets the hour, minutes, and seconds
    ──────────────────────────────────────────────────────────────────────────

    A 24-hour clock is used, so 8:00 PM would be entered as 20:00:00.

    This statement complements the TIME$ function, which returns the current
    time.

■ See Also

    TIME$ Function

■ Example

    The following example sets the current time to 8:00 AM:

    TIME$="08:00:00"


────────────────────────────────────────────────────────────────────────────
TRON/TROFF Statements
────────────────────────────────────────────────────────────────────────────

■ Action

    Traces the execution of program statements

■ Syntax

    TRON
    TROFF

■ Remarks

    In the QuickBASIC environment, executing a TRON statement has the same
    effect as selecting Trace On from the Debug menu──each statement is
    highlighted on the screen as it executes.

    The TROFF statement turns off the program trace.

    The TRON and TROFF statements only display line numbers when compiled with
    the Debug option or the /D option on the BC command line.

────────────────────────────────────────────────────────────────────────────
NOTE
    The debugging features of the QuickBASIC environment make these statements
    unnecessary.
────────────────────────────────────────────────────────────────────────────

■ Example

    There is no programming example for the TRON statement.


────────────────────────────────────────────────────────────────────────────
TYPE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines a data type containing one or more elements

■ Syntax

    TYPE usertype
        elementname AS typename
        elementname AS typename
    .
    .
    .
    END TYPE

■ Remarks

    The TYPE statement takes the following arguments:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    usertype                 A name given to the user-defined data type.
                            Follows the same rules as a BASIC variable name.

    elementname              The name of an element of the user-defined data
                            type. Follows the same rules as a BASIC variable
                            name. Cannot be the name of an array.

    typename                 May be any of the following BASIC data types:
                            INTEGER, LONG, SINGLE, DOUBLE, fixed-length
                            string (see note below), or user-defined type.
    ──────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────
NOTE
    Strings in user types must be fixed-length strings. String lengths are
    indicated by an asterisk and a numeric constant. For example, the
    following line defines an element named Keyword in a user-defined type as
    a string with length 40:

    Keyword AS STRING*40

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

    A user-defined type must be declared in a TYPE declaration before it can
    be used in the program. Although a user-defined type can only be declared
    in the module-level code, you may declare a variable to be of a
    user-defined type anywhere in the module, even in a SUB or FUNCTION.

    Use the DIM, REDIM, COMMON, STATIC, or SHARED statements to declare a
    variable to be of a user-defined type.

■ Example

    The following example simulates a deck of cards by using a user-defined
    type. The program builds a deck of cards (an array of user-defined type
    Card), shuffles the deck, and displays the first five cards.

    ' This program uses a user-defined type to
    ' simulate a deck of cards.

    ' Define the Card type--an integer value and a string
    ' representing the suit.
    TYPE Card
        Value AS INTEGER
        Suit AS STRING*9
    END TYPE

    DEFINT A-Z
    ' Define the Deck as a 52-element array of Cards.
    DIM Deck(1 TO 52) AS Card

    ' Build, shuffle, and deal the top five cards.
    CALL BuildDeck(Deck())
    CALL Shuffle(Deck())
    FOR I%=1 TO 5
        CALL ShowCard(Deck(I%))
    NEXT I%

    ' Build the deck--fill the array of Cards with
    ' appropriate values.
    SUB BuildDeck(Deck(1) AS Card) STATIC
    DIM Suits(4) AS STRING*9

        Suits(1)="Hearts"
        Suits(2)="Clubs"
        Suits(3)="Diamonds"
        Suits(4)="Spades"
    ' This loop controls the suit.
        FOR I%=1 TO 4
        ' This loop controls the face value.
        FOR J%=1 TO 13
            ' Figure out which card (1...52) you're creating.
            CardNum%=J%+(I%-1)*13
            ' Place the face value and suit into the Card.
            Deck(CardNum%).Value=J%
            Deck(CardNum%).Suit=Suits(I%)
        NEXT J%
        NEXT I%

    END SUB

    ' Shuffle a deck (an array containing Card elements).
    SUB Shuffle(Deck(1) AS Card) STATIC

        RANDOMIZE TIMER
    ' Shuffle by transposing 1000 randomly selected pairs of cards.
        FOR I%=1 TO 1000
        CardOne%=INT(52*RND+1)
        CardTwo%=INT(52*RND+1)
        ' Notice that SWAP works on arrays of user types.
        SWAP Deck(CardOne%),Deck(CardTwo%)
        NEXT I%

    END SUB

    ' Display a single card by converting and printing the
    ' face value and the suit.
    SUB ShowCard (SingleCard AS Card) STATIC

        SELECT CASE SingleCard.Value
        CASE 13
            PRINT "King ";
        CASE 12
            PRINT "Queen";
        CASE 11
            PRINT "Jack ";
        CASE  1
            PRINT "Ace  ";
        CASE ELSE
            PRINT USING "  ## ";SingleCard.Value;
        END SELECT

        PRINT " ";SingleCard.Suit

    END SUB

■ Output

        3  Clubs
        4  Hearts
        3  Diamonds
    Jack  Clubs
        8  Spades


────────────────────────────────────────────────────────────────────────────
UBOUND Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the upper bound (largest available subscript) for the indicated
    dimension of an array

■ Syntax

    UBOUND(array«,dimension»)

■ Remarks

    The argument dimension is an integer from 1 to the number of dimensions in
    array. For an array dimensioned as follows, UBOUND returns the values
    listed below:

    DIM A(1 TO 100, 1 TO 50, -3 TO 4)

    Invocation               Value Returned
    ──────────────────────────────────────────────────────────────────────────
    UBOUND(A,1)              100
    UBOUND(A,2)              50
    UBOUND(A,3)              4
    ──────────────────────────────────────────────────────────────────────────

    You can use the shortened syntax UBOUND(array) for one-dimensional arrays
    since the default value for dimension is 1. Use the LBOUND function to
    find the lower limit of an array dimension.

■ See Also

    LBOUND

■ Example

    LBOUND and UBOUND can be used together to determine the size of an array
    passed to a subprogram, as in the following program fragment:

    CALL PRNTMAT(ARRAY())
    .
    .
    .
    SUB PRNTMAT(A()) STATIC
        FOR I% = LBOUND(A,1) TO UBOUND(A,1)
        FOR J% = LBOUND(A,2) TO UBOUND(A,2)
            PRINT A(I%,J%);" ";
            NEXT J%
        PRINT:PRINT
        NEXT I%
    END SUB


────────────────────────────────────────────────────────────────────────────
UCASE$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string expression with all letters in uppercase

■ Syntax

    UCASE$ (stringexpression)

■ Remarks

    The stringexpression argument can be any string expression. The UCASE$
    function works with both variable- and fixed-length strings. The UCASE$
    and LCASE$ statements are helpful in making string comparisons case
    insensitive.

■ See Also

    LCASE$

■ Example

    The following program contains a FUNCTION, YesQues, that returns a Boolean
    value depending on how the user responds. The program YesQues uses UCASE$
    to make a case-insensitive test of the user's response.

    DEFINT A-Z

    FUNCTION YesQues(Prompt$,Row,Col) STATIC
        OldRow=CSRLIN
        OldCol=POS(0)
        ' Print prompt at Row, Col.
        LOCATE Row,Col : PRINT Prompt$ "(Y/N):";
        DO
        ' Get the user to press a key.
        DO
            Resp$=INKEY$
        LOOP WHILE Resp$=""
        Resp$=UCASE$(Resp$)
        ' Test to see if it's yes or no.
        IF Resp$="Y" OR Resp$="N" THEN
            EXIT DO
        ELSE
            BEEP
        END IF
        LOOP
        ' Print the response on the line.
        PRINT Resp$;
        ' Move the cursor back to the old position.
        LOCATE OldRow,OldCol
        ' Return a Boolean value by returning the result of a test.
        YesQues=(Resp$="Y")
    END FUNCTION

    DO
    LOOP WHILE NOT YesQues("Do you know the frequency?",12,5)


────────────────────────────────────────────────────────────────────────────
UEVENT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Enables, disables, or suspends event trapping for a user-defined event

■ Syntax

    UEVENT ON
    UEVENT OFF
    UEVENT STOP

■ Remarks

    The effects of the UEVENT statements are like that of other event-trapping
    statements. When UEVENT ON is executed, the event-trapping routine is
    enabled. Occurrences of the event trigger execution of the event-handling
    routine.

    When UEVENT OFF is executed, the event-trapping routine is disabled. Any
    occurrences of the event are ignored.

    When UEVENT STOP is executed, the event-trapping routine is suspended. An
    event occurrence is remembered and the event-trapping routine performed as
    soon as a UEVENT ON statement is executed.

■ See Also

    ON UEVENT

■ Example

    See the example for ON UEVENT.


────────────────────────────────────────────────────────────────────────────
UNLOCK Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Releases locks applied to parts of a file

■ Syntax

    UNLOCK «#» filenumber «,{record | «start» TO end}»

■ Remarks

    The UNLOCK statement is used only after a LOCK statement. See the LOCK
    statement for a complete discussion.

    For binary-mode files, the arguments record, start, and end represent the
    number of a byte relative to the beginning of the file. The first byte in
    a file is byte 1.

    For random-access files, these arguments are the number of a record
    relative to the beginning of the file. The first record is record 1.

■ See Also

    LOCK

■ Example

    See the example for LOCK.


────────────────────────────────────────────────────────────────────────────
Creating a User-Defined Event
────────────────────────────────────────────────────────────────────────────

    In previous versions of QuickBASIC, the only events that could be trapped
    were those already defined in the language: COM, KEY, PEN, PLAY, STRIG and
    TIMER. There was no way to define your own event.

    QuickBASIC 4.5 allows you to define your own event trap. When the event
    occurs, BASIC calls the routine that handles the trap, just as if the
    event were part of the QuickBASIC language.

    A user-defined event has three elements. The first is a routine that
    detects the event. The second is this routine's call to the BASIC
    procedure SetUEvent, which traps the event. The third is BASIC's call to a
    routine that handles the event.

    You create a user-defined event by writing two pieces of code. The first
    is the routine that detects the event. (The event could be a hardware
    interrupt, or perhaps an altered data value at a special memory location.)
    This routine can be written in BASIC, or other languages, such as C and
    assembler. (BASIC routines can be included in the main module. Code
    written in other languages must be separately compiled and added to a
    Quick Library.)

    The event-detecting routine must block; that is, it must sit waiting for
    the event. (A routine that does not block would have to be called
    repeatedly to see if the event has occurred. This defeats the purpose of a
    user-defined event, as it is no different from conventional polling.) When
    the event occurs, it calls the BASIC routine SetUEvent. It is this call
    that traps the event. BASIC then calls the event handler.

    The event handler is the second piece of code. The advantage of separating
    event trapping from event handling is that the handling can be tailored to
    the needs of the moment; the same event can be handled differently in
    different parts of the program.

    Let's consider a simple example to see how this works. Our hypothetical
    programmer has designed an interface board for home monitoring and
    control. One of its features is a mailbox alarm: opening the mailbox door
    closes a switch that sets the most-significant bit at a specific buss
    address.

    Here is a simple BASIC routine to monitor this switch. (The segment and
    address quantities are for illustration only. They are in the video RAM
    space, and probably wouldn't be useful for other kinds of interfaces.)

    MailBoxOpened:

        DEF SEG = &h9000              ' set the address segment
        value% = PEEK (&h1234)        ' read value at address in that segment
        IF value% THEN CALL SetUEvent ' tell BASIC event has occurred
        DEF SEG                       ' return to BASIC data segment

■ RETURN

    Value% is either zero, or has its MSB set. In the latter case it is
    logically "true" (indicating that the mailbox was opened), and the
    SetUEvent routine is called. This routine (which is part of BASIC) tells
    BASIC that the expected event has occurred, and it is time to execute the
    event-handling routine. All event-detecting routines, regardless of the
    languages they are written in, must call SetUEvent.

    If the event-detecting routine is in a language other than BASIC, the
    Quick Library containing it has to be loaded before a QuickBASIC program
    that uses it can run or be compiled. Include a DECLARE SUB statement in
    the module calling the event-detection routine, so that BASIC knows how to
    find it.

    Now let's write an event-handling routine to tell our programmer his mail
    has arrived:

    MailCame:

        PRINT "Ta-Dah! Your day is made! The mail came!"

■ RETURN

    All that's left is to tell BASIC about the user-defined event handler,
    using the ON UEVENT statement. ON UEVENT works just like ON EVENT; it
    associates the user-defined event with the event-handling routine:

    ON UEVENT GOSUB MailCame  ' associate the handler routine with user event
    UEVENT ON                 ' initiate user-event trapping
        .
        .
        .
    CALL MailBoxOpened        ' call the routine that looks for the event
        .
        .
        .
    END

    Note that ON UEVENT deals only with the event-handler; it is not concerned
    with event-detection. Once the UEVENT ON statement has been executed, any
    call to SetUEvent will trigger the specified event-handler, regardless of
    how or where the call is issued.

    Here is a summary of the steps in creating and using a user-defined event
    handler:

    1. Write the routine that detects the event. When the event occurs, the
        routine must call the BASIC routine SetUEvent.

    2. If the event-detecting routine is in BASIC, place it after the END
        statement in the module where it will be called.

        If the event-detecting routine is not in BASIC, compile it and include
        it in a BASIC Quick Library. The module(s) that call this routine must
        include a DECLARE SUB statement so that BASIC can find the routine.

    3. Write the routine that handles the event.

    4. Use the ON UEVENT statement to tell BASIC the name of the
        event-handling routine associated with the user-defined event.

    5. Use the UEVENT ON statement to initiate trapping. (UEVENT OFF and
        UEVENT STOP may be used to terminate or postpone trapping.)

    6. Call the event-detecting routine. When the event occurs, BASIC will
        call the event-handling routine named in the ON UEVENT statement.


────────────────────────────────────────────────────────────────────────────
VAL Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the numeric value of a string of digits

■ Syntax

    VAL(stringexpression)

■ Remarks

    The stringexpression is a sequence of characters that can be interpreted
    as a numeric value. The VAL function stops reading the string at the first
    character that it cannot recognize as part of a number. The VAL function
    also strips leading blanks, tabs, and line feeds from the argument string.
    For example,

    VAL("    -33/LP")

    returns the value -33.

■ See Also

    STR$

■ Example

    The following program prints the names and addresses of people with
    specific telephone area codes:

    INPUT "Search for which area: ", Targetarea
    OPEN "MAIL.DAT" FOR INPUT AS #1
    DO WHILE NOT EOF(1)
        INPUT #1, Nm$, Phonenum$, Street$, Citystate$
        'VAL reads everything up to the first non-numeric
        'character ("-" in this case).
        Area = VAL(Phonenum$)
        IF Area = Targetarea THEN
        PRINT : PRINT Nm$
        PRINT Street$
        PRINT Citystate$
        END IF
    LOOP
    CLOSE : END



────────────────────────────────────────────────────────────────────────────
VARPTR, VARSEG Functions
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns the address of a variable

■ Syntax

    VARPTR(variablename)
    VARSEG(variablename)

■ Remarks

    The variablename may be any BASIC variable, including a record variable or
    record element. The VARPTR function returns an unsigned integer that is
    the offset of the variable within its segment. The VARSEG function returns
    an unsigned integer that is the segment part of the variable's address. If
    variablename is not defined before either VARPTR or VARSEG is called, the
    variable is created and its address is returned. When variablename is a
    string variable, VARPTR and VARSEG return the location of the first byte
    of the string descriptor.

────────────────────────────────────────────────────────────────────────────
NOTE
    Because many BASIC statements change the locations of variables in memory,
    use the values returned by VARPTR and VARSEG immediately after the
    functions are used. See Section 2.3.3, "Variable Storage Allocation," for
    a list of things that cause variable locations to move.
────────────────────────────────────────────────────────────────────────────

    VARPTR and VARSEG are often used with BLOAD, BSAVE, CALL ABSOLUTE, CALL
    INTERRUPT, PEEK, POKE, or when passing arrays to procedures written in
    other languages.

    When using VARPTR or VARSEG to get the address of an array, use the first
    element of the array as the argument:

    DIM A(150)
    .
    .
    .
    ArrAddress=VARPTR(A(1))

    You may no longer use VARPTR to get the address of a file's buffer. Use
    the function FILEATTR to get information about a file. In addition,
    programs written in earlier versions of BASIC that used VARPTR to access
    numeric arrays may no longer work. You must now use a combination of
    VARPTR and VARSEG. For example, the following QuickBASIC Version 3.0
    fragment no longer works correctly:

    DIM Cube(675)
    .
    .
    .
    BSAVE "graph.dat",VARPTR(Cube(1)),2700

    The fragment would be rewritten as follows:

    DIM Cube(675)
    .
    .
    .
    ' Change segment to segment containing Cube.
    DEF SEG=VARSEG(Cube(1))
    BSAVE "graph.dat",VARPTR(Cube(1)),2700
    ' Restore BASIC segment.
    DEF SEG

    You may use VARPTR alone to get the address of a variable stored in
    DGROUP. You must use both VARPTR and VARSEG to get the complete address of
    a variable stored as a far object. See Section 2.3.3, "Variable Storage
    Allocation," for rules to determine when a variable is stored in DGROUP.

    The VARSEG function combined with VARPTR replaces the PTR86 subprogram
    used in previous versions of QuickBASIC.

■ See Also

    BLOAD, BSAVE, CALL ABSOLUTE, CALL INTERRUPT, DEF SEG, PEEK, POKE

■ Example

    See the entries for BLOAD, BSAVE, CALL ABSOLUTE, and CALL INTERRUPT for
    examples of how to use VARPTR and VARSEG with those statements.

    The following program illustrates how to use VARPTR and VARSEG to pass a
    BASIC array to a C function. The C function would be separately compiled
    and then placed in a Quick library or linked to the BASIC main program.

    ' BASIC program passing an array to C function.
    DECLARE SUB AddArr CDECL (BYVAL Offs%, BYVAL Segm%, BYVAL Num%)
    DIM A(1 TO 100) AS INTEGER
    ' Fill the array with the numbers 1 to 15.
    FOR I=1 TO 15
        A(I)=I
    NEXT I

    ' Call the C function. AddArr expects a far address (segment
    ' and offset). Because CDECL puts things on the stack from
    ' right to left, put the offset ( VARPTR(A(1)) ) first in the
    ' list, followed by the segment ( VARSEG(A(1)) ).
    CALL AddArr(VARPTR(A(1)),VARSEG(A(1)),15%)

    ' Print the modified array.
    FOR I=1 TO 15
        PRINT A(I)
    NEXT I

    END

    /* Add one to the first num elements of array arr.*/
    void far addarr(arr,num)
    int far *arr;
    int num;
    {
        int i;
        for(i=0;i<num;i++) arr[i]++;
    }


────────────────────────────────────────────────────────────────────────────
VARPTR$ Function
────────────────────────────────────────────────────────────────────────────

■ Action

    Returns a string representation of a variable's address as needed for use
    in DRAW and PLAY statements

■ Syntax

    VARPTR$(variablename)

■ Remarks

    The variablename is the name of a variable in the program. If variablename
    is an array element, then the array must be dimensioned before the VARPTR$
    function is used. The array must be an array of variable-length strings.

────────────────────────────────────────────────────────────────────────────
NOTE
    To guarantee correct results, use the value of VARPTR$ immediately after
    invoking the function.
────────────────────────────────────────────────────────────────────────────

■ Differences From Basica

    In QuickBASIC programs, VARPTR$ must be used in the DRAW and PLAY
    statements to execute substrings containing variables. BASICA supports
    both the VARPTR$ syntax and the syntax containing just the variable name.

■ See Also

    DRAW, PLAY

■ Example

    See the DRAW and PLAY statement for examples.


────────────────────────────────────────────────────────────────────────────
VIEW Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines screen limits for graphics output

■ Syntax

    VIEW ««SCREEN» (x1,y1)-(x2,y2) «,«color» «,border»»»

■ Remarks

    The list below describes the parts of the VIEW statement:

╓┌─┌────────────────────────┌────────────────────────────────────────────────╖
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
    SCREEN                   When SCREEN is used, the x-and y-coordinates are
                            absolute to the screen, not relative to the
                            border of the physical viewport. Only graphics
                            within the viewport are plotted. When SCREEN is
    Part                     Description
    ──────────────────────────────────────────────────────────────────────────
                            within the viewport are plotted. When SCREEN is
                            omitted, all points are plotted relative to the
                            viewport (x1 and x2 are added to coordinates
                            before plotting the point).

    (x1,y1) - (x2,y2)        Indicates a rectangular area on the screen. The
                            placeholders x1, y1, x2, and y2 are numeric
                            expressions that are the coordinates of
                            diagonally opposite corners of the area.

    color                    The color attribute of the color used to fill the
                            area. If you omit color, the area is not filled.

    border                   Any numeric expression in this area draws a line
                            around the viewport if space is available. If you
                            omit border, no border is drawn.
    ──────────────────────────────────────────────────────────────────────────


    The VIEW statement defines a "physical viewport," or a rectangular section
    of the screen into which graphics can be mapped. All coordinates used in
    the statement must be within the physical bounds of the screen.

    If VIEW is given with no arguments, the entire screen is defined as the
    viewport. RUN and SCREEN also define the entire screen as the viewport and
    disable any viewports defined with VIEW.

■ Examples

    The following example contrasts the output after VIEW and VIEW SCREEN are
    executed:

    SCREEN 1
    'SCREEN option makes all screen coordinates absolute.
    VIEW SCREEN (10,10)-(200,100)
    'This line will not be visible, since its end
    'points are outside the viewport.
    LINE (5,5)-(100,5)
    PRINT "Press any key to continue."
    SUSPEND$ = INPUT$(1)
    'Wait for a key to be pressed.

    'No SCREEN option - all screen coordinates relative to
    'this viewport.
    VIEW (10,10)-(200,100)
    'This line is now visible, since its end points
    'are added to (10,10).
    LINE (5,5)-(100,5)

    You may use multiple VIEW statements. If the newly described viewport is
    not wholly within the previous viewport, the screen can be reinitialized
    with the VIEW statement and the new viewport can be defined. If the new
    viewport is entirely within the previous one, as in the following example,
    the intermediate VIEW statement is not necessary. This example opens three
    viewports, each smaller than the previous one. In each case, the points of
    the line that lie outside the viewport borders are clipped and do not
    appear on the screen.

    SCREEN 1
    CLS
    VIEW
    'Make the viewport cover most of the screen.
    VIEW (10,10) - (300,180),,1
        CLS
        LINE (0,0) - (310,190),1
        LOCATE 1,11: PRINT "A big viewport"
    VIEW SCREEN (50,50)-(250,150),,1
        CLS
    'Note CLS clears only viewport.
        LINE (300,0)-(0,199),1
        LOCATE 9,9: PRINT "A medium viewport"
    VIEW SCREEN (80,80)-(200,125),,1
        CLS
        CIRCLE (150,100),20,1
        LOCATE 11,9: PRINT "A small viewport"


────────────────────────────────────────────────────────────────────────────
VIEW PRINT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sets the boundaries of the screen text viewport

■ Syntax

    VIEW PRINT «topline TO bottomline»

■ Remarks

    The topline argument is the number of the upper line in the viewport; the
    bottomline is the number of the lower line.

    Without topline and bottomline parameters, the VIEW PRINT statement
    initializes the whole screen area as the text viewport. The number of
    lines in the screen depends on the screen mode and whether or not the /H
    option was used when QuickBASIC was started. See the entry for the WIDTH
    statement and Chapter 3, "File and Device I/O," in Programming in BASIC,
    for more information.

    Statements and functions that operate within the defined text viewport
    include CLS, LOCATE, PRINT, and the SCREEN function.

■ See Also

    CLS, LOCATE, PRINT, SCREEN Function, VIEW

■ Example

    See the example for CLS.


────────────────────────────────────────────────────────────────────────────
WAIT Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Suspends program execution while monitoring the status of a machine input
    port

■ Syntax

    WAIT portnumber,and-expression«,xor-expression»

■ Remarks

    The following list describes the arguments of the WAIT statement:

    Argument                 Description
    ──────────────────────────────────────────────────────────────────────────
    portnumber               An integer expression in the range 0-255 that is
                            the number of the port

    and-expression           An integer expression combined with data from the
                            port through an AND operation

    xor-expression           An integer expression combined with data from the
                            port using an XOR operation
    ──────────────────────────────────────────────────────────────────────────

    The WAIT statement suspends execution until a specified bit pattern is
    read from a designated input port. The data read from the port is
    combined, using an XOR operation, with xor-expression, if it appears. The
    result is then combined with the and-expression using an AND operation. If
    the result is zero, BASIC loops back and reads the data at the port again.
    If the result is nonzero, execution continues with the next statement. If
    xor-expression is omitted, it is assumed to be 0.

────────────────────────────────────────────────────────────────────────────
WARNING
    It is possible to enter an infinite loop with the WAIT statement if the
    input port fails to develop a nonzero bit pattern. In this case, you must
    manually restart the machine.
────────────────────────────────────────────────────────────────────────────

■ Example

    The following example illustrates the WAIT statement:

    WAIT 32,2


────────────────────────────────────────────────────────────────────────────
WHILE...WEND Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Executes a series of statements in a loop, as long as a given condition is
    true

■ Syntax

    WHILE condition
    .
    .
    .
    «statements»
    .
    .
    .
    WEND

■ Remarks

    If the condition is true (that is, if it does not equal zero), then any
    intervening statements are executed until the WEND statement is
    encountered. BASIC then returns to the WHILE statement and checks
    condition. If it is still true, the process is repeated. If it is not true
    (or if it equals zero), execution resumes with the statement following the
    WEND statement.

────────────────────────────────────────────────────────────────────────────
NOTE
    QuickBASIC's DO...LOOP statement provides a more powerful and flexible
    loop-control structure.
────────────────────────────────────────────────────────────────────────────

    WHILE...WEND loops may be nested to any level. Each WEND matches the most
    recent WHILE. An unmatched WHILE statement causes an error message that
    reads WHILE without WEND. An unmatched WEND statement causes an error
    message that reads WEND without WHILE.

────────────────────────────────────────────────────────────────────────────
NOTE
    Do not branch into the body of a WHILE...WEND loop without executing the
    WHILE. This may cause run-time errors or program problems that are
    difficult to locate.
────────────────────────────────────────────────────────────────────────────

■ See Also

    DO...LOOP

■ Example

    The following fragment performs a bubble sort on the array A$. The second
    line makes the variable Exchange true by assigning it a nonzero value and
    thereby forces one pass through the WHILE...WEND loop (this construction
    is unnecessary with DO...LOOP). When there are no more swaps, all elements
    of A$ are sorted, the variable Exchange is false (equal to zero), and the
    program continues execution with the line following the WEND statement.

    ' Bubble sort of array A$.
    CONST FALSE=0, TRUE=NOT FALSE
    Max = UBOUND(A$)
    Exchange=TRUE  ' Force first pass through the array.

    WHILE Exchange ' Sort until no elements are exchanged.
        Exchange=FALSE
        ' Compare the array elements by pairs. When two
        ' are exchanged, force another pass by setting Exchange
        ' to TRUE.
        FOR I = 2 TO Max
        IF A$(I-1) > A$(I) THEN
            Exchange=TRUE
            SWAP A$(I-1),A$(I)
        END IF
        NEXT
    WEND

    .
    .
    .


────────────────────────────────────────────────────────────────────────────
WIDTH Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    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

■ Remarks

    Both files and devices can be assigned an output-line width. The different
    forms of the WIDTH statement are explained in the following list:

╓┌─┌────────────────────────────────────┌────────────────────────────────────╖
    Syntax                               Description
    ──────────────────────────────────────────────────────────────────────────
    Syntax                               Description
    ──────────────────────────────────────────────────────────────────────────
    WIDTH «columns»«,lines»              Sets the number of columns and lines
                                        to display on the screen.

                                        The value of columns must be either
                                        40 or 80. The default value is 80.

                                        The value of lines may be 25, 30, 43,
                                        50, or 60, depending on both the
                                        display adapter used and the screen
                                        mode.

                                        The number of lines displayed when
                                        the program started will determine
                                        the default value. See the SCREEN
                                        statement for more information.

    WIDTH #filenumber, width             Sets to width the line width of an
                                        output device opened as a file (for
                                        example, LPT1: or CONS:). The
    Syntax                               Description
    ──────────────────────────────────────────────────────────────────────────
                                        example, LPT1: or CONS:). The
                                        filenumber argument is the number
                                        associated with the file in the OPEN
                                        statement.

                                        This form permits altering the width
                                        while a file is open, since the
                                        statement takes place immediately.

    WIDTH device,width                   Sets to width the line width of
                                        device (a device file name). The
                                        device should be a string expression
                                        (for example, "CONS:").

                                        Note that this width assignment is
                                        deferred until the next OPEN
                                        statement affecting the device; the
                                        assignment does not affect output for
                                        an already open file.
    Syntax                               Description
    ──────────────────────────────────────────────────────────────────────────
                                        an already open file.

    WIDTH LPRINT width                   Sets to width the line width of the
                                        line printer for use by subsequent
                                        LPRINT statements.
    ──────────────────────────────────────────────────────────────────────────


■ See Also

    SCREEN Statement

■ Example

    In the following example, the record width for file #1 (the lineprinter)
    is set to different widths:

    OPEN "LPT1:" FOR OUTPUT AS #1
    Test$ = "1234567890"
    WIDTH #1, 3
    PRINT #1, Test$
    WIDTH #1, 4
    PRINT #1, Test$
    CLOSE

■ Output

    123
    456
    789
    0
    1234
    5678
    90


────────────────────────────────────────────────────────────────────────────
WINDOW Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Defines the dimensions of the current viewport

■ Syntax

    WINDOW ««SCREEN» (x1,y1)-(x2,y2)»

■ Remarks

    The WINDOW statement allows the user to create a customized coordinate
    system to draw lines, graphs, or objects without being constrained by the
    screen's physical coordinates (the dimensions of the screen). This is done
    by redefining the screen-border coordinates with the "view coordinates"
    (x1, y1) and (x2, y2). These view coordinates are single-precision
    numbers.

    WINDOW defines the section of the view coordinate system that is mapped to
    the physical coordinates of the screen. All subsequent graphics statements
    use these new view coordinates and are displayed within the current
    viewport. (The size of the viewport can be changed with the VIEW
    statement.)

    Either the RUN statement or WINDOW with no arguments disables the window
    transformation. The WINDOW SCREEN variant inverts the normal Cartesian
    direction of the y-coordinate, so y values go from negative to positive
    from top to bottom.

    Figure R.1 shows the effects of WINDOW and WINDOW SCREEN on a line drawn
    in screen mode 2. Notice the change in the coordinates of the screen
    corners.

■ Examples

    The following example illustrates two lines with the same end-point
    coordinates. The first is drawn on the default screen, and the second is
    on a redefined window.

    SCREEN 2
    LINE (100,100) - (150,150), 1
    LOCATE 2,20 : PRINT "The line on the default screen"
    WINDOW SCREEN (100,100) - (200,200)
    LINE (100,100) - (150,150), 1
    LOCATE 8,18 : PRINT"& the same line on a redefined window"

                                Increasing X
                            ─────────────────────────►
                        │ ┌─────────────────────────┐
                        │ │(0,0)             (639,0)│
                Increasing│ │                         │
                    Y     │ │                         │
                        │ │                         │
                        │ │                         │
                        │ │                         │
                        │ │                         │
                        │ │(0,199)         (639,199)│
                        ▼ └─────────────────────────┘
                                        /  \
                                    /       \
                                    /            \
            WINDOW (-25,-15)   /        WINDOW SCREEN (-25,-15)-(5,10)
            LINE (-15,-10)-(-5,-5)      LINE  (-15,-10)-(-5,-5)
                            /                           \
                        /                                \
                        /                                     \
                    /                                          \      Increas
                ┌─────────────────────────┐                     ───────────────
                │(-25,10)           (5,10)│                   │  ┌─────────────
            │ │                         │                   │  │(-25,-15)
    Increasing│ │                 (0,0)   │        Increasing │  │
        Y     │ │                         │            Y      │  │      ∙\(-15,
            │ │           (-5,-5)∙      │                   │  │         \
            │ │              /          │                   │  │           \∙
            │ │            /            │                   │  │
            │ │  (-15,-10)∙             │                   │  │
            │ │(-25,-15)         (5,-15)│                   │  │
                └─────────────────────────┘                   │  │(-25,10)
                ─────────────────────────►                    ▼  └─────────────
                        Increasing X

    Figure R.1 WINDOW and WINDOW SCREEN

    The following example shows how changing the window size changes the size
    of a figure drawn on the screen. The effect is one of zooming in and out;
    as the window gets smaller, the figure appears larger on the screen, until
    parts of it are finally clipped because they lie outside the window. As
    the window gets larger, the figure appears smaller on the screen.

    PRINT "Press ENTER to start."
    INPUT;"",A$
    SCREEN 1 : COLOR 7              'Grey screen.
    X = 500 : Xdelta = 50

    DO
        DO WHILE X < 525 AND X > 50
        X = X + Xdelta            'Change window size.
        CALL Zoom(X)
        FOR I = 1 TO 1000         'Delay loop.
            IF INKEY$ <> "" THEN END   'Stop if key pressed.
        NEXT
        LOOP
        X = X - Xdelta
        Xdelta = -Xdelta             'Reverse size change.
    LOOP

    SUB Zoom(X) STATIC
        CLS
        WINDOW (-X,-X)-(X,X)         'Define new window.
        LINE (-X,-X)-(X,X),1,B       'Draw window border.
        CIRCLE (0,0),60,1,,,.5       'Draw ellipse with x-radius 60.
        PAINT (0,0),1                'Paint ellipse.
    END SUB


────────────────────────────────────────────────────────────────────────────
WRITE Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Sends data to the screen

■ Syntax

    WRITE «expressionlist»

■ Remarks

    If expressionlist is omitted, a blank line is written. If expressionlist
    is included, the values of the expressions are written to the screen. The
    expressions in the list may be numeric and/or string expressions. They
    must be separated by commas.

    When the printed items are written, each item is separated from the last
    by a comma. Printed strings are delimited by quotation marks. After the
    last item in the list is printed, BASIC inserts a carriage-return and
    line-feed. The WRITE statement writes numeric values without leading or
    trailing spaces.

■ See Also

    PRINT

■ Example

    The following example shows the difference between the PRINT and WRITE
    statements:

    A=80 : B=90 : C$="That's all." : D=-1.0E-13
    WRITE A,B,C$,D
    PRINT A,B,C$,D

■ Output

    80,90,"That's all.",-1E-13
    80            90           That's all.  -1E-13


────────────────────────────────────────────────────────────────────────────
WRITE # Statement
────────────────────────────────────────────────────────────────────────────

■ Action

    Writes data to a sequential file

■ Syntax

    WRITE #filenumber,expressionlist

■ Remarks

    The filenumber is the number used in the OPEN statement. The file must be
    opened in OUTPUT or APPEND mode. The expressions in the argument
    expressionlist are string and/or numeric expressions, separated by commas.
    If you omit the expressionlist, the WRITE # statement writes a blank line
    to the file.

    The WRITE # statement, unlike the PRINT # statement, inserts commas
    between items as they are written to the file. You do not have to put
    explicit delimiters in the list. A new line is inserted once the last item
    in the list has been written to the file.

    If WRITE # attempts to write data to a sequential file restricted by a
    LOCK statement, an error message appears that reads Permission denied
    unless the error is trapped by the program. All of BASIC's usual
    error-handling routines can trap and examine this error.

■ See Also

    LOCK, OPEN, PRINT #, WRITE

■ Example

    The output from the following program illustrates the difference between
    the WRITE # and PRINT # statements:

    A$ = "VCR, remote control" : B$ = "$399.00"
    OPEN  "PRICES" FOR OUTPUT AS #1       'Open PRICES for writing.
    PRINT #1,A$,B$   'Store A$ and B$ in first record with PRINT #.
    WRITE #1,A$,B$   'Store A$ and B$ in second record with WRITE #.
    CLOSE #1

■ Output

    VCR, remote control         $399.00
    "VCR, remote control","$399.00"


════════════════════════════════════════════════════════════════════════════
Glossary


CONTROL FLOW

FOR...NEXT  Repeats statements between FOR and NEXT a specific number of
    times.

EXIT FOR  alternative exit from FOR...NEXT

DO...LOOP  Repeats statements between DO and LOOP, while (until) a condition
    is(becomes) true.

EXIT DO  alternative exit from DO...LOOP

WHILE...WEND  Repeats statements between WHILE and WEND while a given
    condition is true.

IF...THEN...ELSE... END IF  Conditionally executes or branches todifferent
    statements.

SELECT CASE  Conditionally executes statements based on value of a variable.

GOSUB...RETURN  Transfers contol to a specific line in a module; control
    returns to the line following GOSUB. (Old style; SUB is a more powerful
    alternative.)

RUN  Restarts current program, or loads and runs another program.

CHAIN "program"  Passes execution to program specified, then returns.

SLEEP  Suspends program execution.

WAIT  Suspends program execution while monitoring status of a machine input
    port.


PROCEDURES

SUB...END SUB  Mark the beginning and end of a SUBprocedure.

EXIT SUB  alternative exit from a SUB procedure

FUNCTION... END FUNCTION  Mark the beginning and end of aFUNCTION procedure.

EXIT FUNCTION  alternative exit from aFUNCTION procedure

DEF FN...END DEF  Mark the beginning and end of a DEF FN function. (Old
    style; FUNCTION is a more powerful alternative.)

EXIT DEF  alternative exit from aDEF FN function

CALL, CALLS  Transfers control to a BASIC SUB procedure, or a procedure
    written in another language and compiled separately.


STANDARD I/O

BEEP  Makes the speaker beep.

SOUND  Makes a sound of specified frequency and duration.

PRINT [USING]  Outputs [formatted] text to the screen.

WIDTH  Sets screen width and number of lines.

INKEY$  Reads a character from the keyboard.

INP (n)  Returns the value read from I/O port n.

INPUT  Reads string and/or numerical input from the keyboard and stores it
    in a list ofvariables.

INPUT$  Reads characters from the keyboard into a string variable.

LINE INPUT  Reads an entire line (up to 255 chars) into a string variable.

LOCATE  Moves cursor to a specified screen row and column.

SPC  Skips spaces in printed output.

TAB  Skips to a specified display column.

CSRLIN  Returns row number of cursor.

POS  Returns line number of cursor.

LPOS  Returns position of line printer's print head within the printer
    buffer.

VIEW PRINT  Sets top and bottom rows for displaying print.

LPRINT [USING]  Prints [formatted] data on LPT1: printer.

OPEN COMn:  Opens and initializes a communications channel for I/O.

OUT  Sends a byte to a machine I/O port.

PEN  Returns the light pen coordinates.

STICK  Returns the x and y coordinates of the two joysticks.

STRIG  Returns the status of a specified joystick trigger (fire button).

READ  Returns values from a DATA statement and assigns them to variables.

RESTORE  Allows DATA statements to be reread from a specified line.


FILE I/O

OPEN  Opens a file for reading or writing records.

CLOSE  Ends I/O operations to a file.

RESET  Closes all disk files.

PRINT [USING] #  Stores a [formatted] list of variables in a file.

WRITE #  Stores a list of variables as record fields in a file.

FIELD  Allocates space for variables in a random-access file buffer.

WIDTH  Specifies a standard length for each record in a file.

PUT  Stores contents of a variable in a file.

INPUT #  Reads fields from a record; assigns each to a variable.

INPUT$  Reads a string of characters from a file.

LINE INPUT #  Reads a record and stores it in a string variable.

GET  Reads data from a file; assigns data to elements of a variable.

FREEFILE  Returns the next available file number.

EOF  Tests whether the end of a disk file has been reached.

FILEATTR  Returns a number indicating the mode in which a file was opened.

LOC  Gives the current position within a file.

LOF  Gives the number of bytes in an open file.

SEEK (function)  Gives the location where the next file I/O operation will
    occur.

SEEK (statement)  Sets the byte position for the next file I/O operation.

IOCTL  Transmits a control data string to a device driver.

IOCTL$  Receives a control data string from a device driver.

LOCK...UNLOCK  Controls access by other processes to all or part of an open
    file.


STRING PROCESSING

LEFT$  Returns characters from the left side of the string.

RIGHT$  Returns characters from the right side of the string.

MID$ function  Returns characters from anywhere in the string.

MID$ statement  Replaces part of a string with another string.

LTRIM$  Strips leading blanks from string.

RTRIM$  Strips trailing blanks from string.

INSTR  Searches for a string within another string.

LCASE$  Converts a string to all lower-case letters.

UCASE$  Converts a string to all upper-case letters.

LSET  Left-justifies a fixed-length string.

RSET  Right-justifies a fixed-length string.

STR$  Returns the string representation of the decimal value of a numeric
    expression.

HEX$  Returns the string representation of the hex value of a numeric
    expression.

VAL  Returns the numeric value of a stringexpression.

SPACE$  Returns a string of blanks.

STRING$  Returns a string of one repeatedcharacter.

LEN  Returns the number of characters in a string.

ASC  Returns the ASCII value of a character.

CHR$  Returns the character with the given ASCII value.

SADD  Returns the address of the specifiedstring expression.


GRAPHICS

SCREEN  Specifies a BASIC screen mode.

PSET  Sets a pixel to the foreground color.

PRESET  Sets a pixel to the background color.

LINE  Draws a straight line or a box.

CIRCLE  Draws a circle or an ellipse.

DRAW  Combines BASIC graphics features into a graphics macro language.

WINDOW  Sets the logical coordinates for a screen viewport.

VIEW  Specifies a viewport rectangle for graphics output.

PMAP  Maps pixel physical coordinates to logical coordinates.

POINT  Returns physical or logical coordinates of cursor, or color number of
    pixel.

COLOR  Sets default colors for graphics output.

PALETTE  Assigns colors to color numbers.

PAINT  Fills an area with color or a pattern.

GET  Saves a rectangular area of graphics screen in memory.

PUT  Displays graphics stored by GET.

PCOPY  Copies one screen storage page to another.


ERROR AND EVENT TRAPPING

ON ERROR GOTO line  Program branches to line number or line label when error
    occurs.

RESUME  Returns control after executing error-handling routine.

ERR  Returns code for run-time error.

ERL  Returns line number on which erroroccurred.

ERDEV  Returns code for last device which caused an error.

ERDEV$  Returns name of last device which caused an error.

ERROR  Simulates occurrence of a BASIC error.

ON event GOSUB line  Branches to routine labelled with line, whenever event
    occurs.

event ON  Enables trapping of event.

event OFF



────────────────────────────────────────────────────────────────────────────
Appendix A  Keyboard Scan Codes and ASCII Character Codes

        A.1  Keyboard Scan Codes
        A.2  ASCII Character Codes

A.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   .  │             │              │
└────────┴───────┴────────────┴─────────────┴─────────────┴──────────────┘

┌──────────────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│Ctrl Dec Hex 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│    │
└───┴───┴────┘       └───┴───┴─┴──┘       └───┴───┴────┘       └───┴───┴────┘


A.2  ASCII Character Codes

╓┌─┌───────────┌────────────┌───────────┌────────────────────────────────────╖
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
                0            00H         NUL (Null)
    ☺           1            01H         SOH (Start of heading)
    ☻           2            02H         STX (Start of text)
    ♥           3            03H         ETX (End of text)
    ♦           4            04H         EOT (End of transmission)
    ♣           5            05H         ENQ (Enquiry)
    ♠           6            06H         ACK (Acknowledge)
    •           7            07H         BEL (Bell)
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    •           7            07H         BEL (Bell)
    ◘           8            08H         BS (Backspace)
                9            09H         HT (Horizontal tab)
                10           0AH         LF (Linefeed)
    ♂           11           0BH         VT (Vertical tab)
                12           0CH         FF (Formfeed)
                13           0DH         CR (Carriage return)
    ♫           14           EH          SO (Shift out)
                15           0FH         SI (Shift in)
    ►           16           10H         DLE (Data link escape)
    ◄           17           11H         DC1 (Device control 1)
    ↕           18           12H         DC2 (Device control 2)
    ‼           19           13H         DC3 (Device control 3)
    ¶           20           14H         DC4 (Device control 4)
    §           21           15H         NAK (Negative acknowledge)
    ▬           22           16H         SYN (Synchronous idle)
    ↨           23           17H         ETB (End transmission block)
    ↑           24           18H         CAN (Cancel)
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ↑           24           18H         CAN (Cancel)
    ↓           25           19H         EM (End of medium)
                26           1AH         SUB (Substitute)
    ←           27           1BH         ESC (Escape)
    ∟           28           1CH         FS (File separator)
    ↔           29           1DH         GS (Group separator)
                30           1EH         RS (Record separator)
    ▼           31           1FH         US (Unit separator)
                32           20H
    !           33           21H
    "           34           22H
    #           35           23H
    $           36           24H
    %           37           25H
    &           38           26H
    '           39           27H
    (           40           28H
    )           41           29H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    )           41           29H
    *           42           2AH
    +           43           2BH
    ,           44           2CH
    -           45           2DH
    .           46           2EH
    /           47           2FH
    0           48           30H
    1           49           31H
    2           50           32H
    3           51           33H
    4           52           34H
    5           53           35H
    6           54           36H
    7           55           37H
    8           56           38H
    9           57           39H
    :           58           3AH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    :           58           3AH
    ;           59           3BH
    <           60           3CH
    =           61           3DH
    >           62           3EH
    ?           63           3FH
    @           64           40H
    A           65           41H
    B           66           42H
    C           67           43H
    D           68           44H
    E           69           45H
    F           70           46H
    G           71           47H
    H           72           48H
    I           73           49H
    J           74           4AH
    K           75           4BH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    K           75           4BH
    L           76           4CH
    M           77           4DH
    N           78           4EH
    O           79           4FH
    P           80           50H
    Q           81           51H
    R           82           52H
    S           83           53H
    T           84           54H
    U           85           55H
    V           86           56H
    W           87           57H
    X           88           58H
    Y           89           59H
    Z           90           5AH
    [           91           5BH
    \           92           5CH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    \           92           5CH
    ]           93           5DH
    ^           94           5EH
    _           95           5FH
    g           96           60H
    a           97           61H
    b           98           62H
    c           99           63H
    d           100          64H
    e           101          65H
    f           102          66H
    g           103          67H
    h           104          68H
    i           105          69H
    j           106          6AH
    k           107          6BH
    l           108          6CH
    m           109          6DH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    m           109          6DH
    n           110          6EH
    o           111          6FH
    p           112          70H
    q           113          71H
    r           114          72H
    s           115          73H
    t           116          74H
    u           117          75H
    v           118          76H
    w           119          77H
    x           120          78H
    y           121          79H
    z           122          7AH
    {           123          7BH
    |           124          7CH
    }           125          7DH
    ~           126          7EH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ~           126          7EH
                127          7FH         DEL (Delete)
    Ç           128          80H
    ü           129          81H
    é           130          82H
    â           131          83H
    ä           132          84H
    à           133          85H
    å           134          86H
    ç           135          87H
    ê           136          88H
    ë           137          89H
    è           138          8AH
    ï           139          8BH
    î           140          8CH
    ì           141          8DH
    Ä           142          8EH
    Å           143          8FH
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    Å           143          8FH
    É           144          90H
    æ           145          91H
    Æ           146          92H
    ô           147          93H
    ö           148          94H
    ò           149          95H
    û           150          96H
    ù           151          97H
    ÿ           152          98H
    Ö           153          99H
    Ü           154          9AH
    ¢           155          9BH
    £           156          9CH
    ¥           157          9DH
    ₧           158          9EH
    ƒ           159          9FH
    á           160          A0H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    á           160          A0H
    í           161          A1H
    ó           162          A2H
    ú           163          A3H
    ñ           164          A4H
    Ñ           165          A5H
    ª           166          A6H
    º           167          A7H
    ¿           168          A8H
    ⌐           169          A9H
    ¬           170          AAH
    ½           171          ABH
    ¼           172          ACH
    ¡           173          ADH
    «           174          AEH
    »           175          AFH
    ░           176          B0H
    ▒           177          B1H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ▒           177          B1H
    ▓           178          B2H
    │           179          B3H
    ┤           180          B4H
    ╡           181          B5H
    ╢           182          B6H
    ╖           183          B7H
    ╕           184          B8H
    ╣           185          B9H
    ║           186          BAH
    ╗           187          BBH
    ╝           188          BCH
    ╜           189          BDH
    ╛           190          BEH
    ┐           191          BFH
    └           192          C0H
    ┴           193          C1H
    ┬           194          C2H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ┬           194          C2H
    ├           195          C3H
    ─           196          C4H
    ┼           197          C5H
    ╞           198          C6H
    ╟           199          C7H
    ╚           200          C8H
    ╔           201          C9H
    ╩           202          CAH
    ╦           203          CBH
    ╠           204          CCH
    ═           205          CDH
    ╬           206          CEH
    ╧           207          CFH
    ╨           208          D0H
    ╤           209          D1H
    ╥           210          D2H
    ╙           211          D3H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ╙           211          D3H
    ╘           212          D4H
    ╒           213          D5H
    ╓           214          D6H
    ╫           215          D7H
    ╪           216          D8H
    ┘           217          D9H
    ┌           218          DAH
    █           219          DBH
    ▄           220          DCH
    ▌           221          DDH
    ▐           222          DEH
    ▀           223          DFH
                224          E0H
    ß           225          E1H
    Γ           226          E2H
    π           227          E3H
    Σ           228          E4H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    Σ           228          E4H
    σ           229          E5H
    µ           230          E6H
    τ           231          E7H
    Φ           232          E8H
    Θ           233          E9H
    Ω           234          EAH
    δ           235          EBH
    ∞           236          ECH
    φ           237          EDH
    ε           238          EEH
    ∩           239          EFH
    ≡           240          F0H
    ±           241          F1H
    ≥           242          F2H
    ≤           243          F3H
    ⌠           244          F4H
    ⌡           245          F5H
                    Number
    Char        Dec          Hex         Control
    ──────────────────────────────────────────────────────────────────────────
    ⌡           245          F5H
    ÷           246          F6H
    ≈           247          F7H
    °           248          F8H
    ∙           249          F9H
    ·           250          FAH
    √           251          FBH
    ⁿ           252          FCH
    ²           253          FDH
    ■           254          FEH
                255          FFH
    ──────────────────────────────────────────────────────────────────────────





────────────────────────────────────────────────────────────────────────────
Appendix B  Error Messages

        B.1  Error-Message Display
        B.2  Invocation, Compile-Time, and Run-Time Error Messages
        B.3  LINK Error Messages
        B.4  LIB 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 B.2 lists alphabetically the invocation, compile-time, and
    run-time error messages, along with any error codes that are assigned.
    Table B.1 lists the run-time error messages and error codes in numerical
    order. Section B.3 lists the Microsoft Overlay Linker error messages, and
    Section B.4, the Microsoft Library Manager error messages.


B.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," in Programming in BASIC for more information.

    Table B.1 lists the error codes in numerical order. See the alphabetical
    listing for explanations of the errors.

    Table B.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

    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

    Code        Description              Code        Description
    ──────────────────────────────────────────────────────────────────────────

    13          Type mismatch            63          Bad record number

    14          Out of string space      64          Bad file name

    16          String formula too       67          Too many files
                complex

    19          No RESUME                68          Device unavailable

    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

    Code        Description              Code        Description
    ──────────────────────────────────────────────────────────────────────────

    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

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


    QYInvocation Error


B.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 $INCLUDE 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...GOTO or 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 X is 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)


B.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;

                generates this error, since LINK cannot tell which of the
                three options beginning with the letter "N" was intended.

    L1002       option : unrecognized option name
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
    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

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.

    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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
    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.

    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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.

    L1027       unmatched left parenthesis

                A left parenthesis was missing from the contents specification
                of an overlay on the command line.

    L1043       relocation table overflow
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
    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 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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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. 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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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 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.

    L1052       too many libraries
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
    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

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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 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.
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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. 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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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

                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.

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

    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

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.

    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.

    L1090       cannot reopen list file

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

                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.

    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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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. 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

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

                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

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.)

    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.

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

                ■ 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:

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                EXTRN   main:far
                code   SEGMENT public 'CODE'
                start  PROC    far
                        call    main
                        ret
                start  ENDP
                code   ENDS

                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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
    L2004       LOBYTE-type fixup overflow

                A LOBYTE fixup generated an address overflow. (See the
                Microsoft MS-DOS Programmer's Reference for more information.)

    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.

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

    L2012       name : array-element size mismatch

                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).

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

    L2025       name : symbol defined more than once

                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 message and the
                list are also written to the map file, if one exists.
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.

    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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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

                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.
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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.

    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
    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────
                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 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.

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

    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.

    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.

    Number      LINK Error Message
    ──────────────────────────────────────────────────────────────────────────

    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

                LINK could not find the specified file. Enter a new file name,
                a new path specification, or both.

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



B.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 Assistance Request form included
                with the documentation.

    U1173       internal failure

                Note the circumstances of the failure and notify Microsoft
                Corporation using the Product Assistance 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

' (apostrophe)
    entering
+ (concatenation operator)

A

ABS function
ALIAS, use in DECLARE statement
Alphanumeric line labelsLine labels
Angle measurement
    degrees to radians, converting from
    radians to degrees, converting from
Animation
Apostrophe (')
    entering
Arctangent, ATN function
Argument passing
Arithmetic operators
Arithmetic overflow
Arrays
    dimensioning
    dynamic
    ERASE statement
    REDIM statement
    elements
    INT86OLD statements
    LBOUND function
    location in memory
    of records
    static, ERASE statement
    subscripts, specifying
    changing lower bound for
    described
    maximum value for
    number of
    UBOUND function
    variables
AS clause
ASC function
ASCII character codes
    special character
    string expression
    (table)
Assembly language subroutines
    calling
    name, PUBLIC symbol
    string descriptor length
Assignment statements
ATN function
AT&T displays
Automatic variables

B

Background music
.BAS files
BASIC
    error codes
    run-time errors
BASICA, differences from
    BLOAD statement
    BSAVE statement
    CALL ABSOLUTE statement
    CALL statement
    CLEAR statement
    COM statement
    DEF SEG statement
    DEF type statements
    DIM statement
    DRAW statement
    ERL function
    FIELD statement
    RESUME statement
    STRIG function
    SYSTEM statement
    TAN function
    VARPTR$ function
basica, Differences From
    Chain Statement
    For...Next Statement
BEEP statement
Binary mode
    functions
    FILEATTR
    LOC
    statements
    GET (File I/O)
    LOCK
    OPEN
    PUT (File I/O)
    SEEK
BLOAD statement
Block IF...THEN...ELSE statement
Bold text, indicating keywords
Boolean operations
BSAVE statement
Built-in functions
BYVAL, use in DECLARE statement

C

CALL ABSOLUTE statement
CALL INT86OLD statement
CALL INT86XOLD statement
CALL INTERRUPT statement
CALL INTERRUPTX statement
CALL statement (BASIC procedures)
CALL statement (non-BASIC procedures)
    described
    location of arguments
Calling conventions
CALLS statement
    described
    location of arguments
Cardioid
Carriage return
CASE clause
Case, line labels
CDBL function
CDECL, use in DECLARE statement
CGA adapter
CHAIN statement
Chaining programs, statements for
    CHAIN
    COMMON
    RUN
Chainingprograms, statements for
    COMMON
Characters recognized by BASIC
CHDIR statement
CHR$ function
CINT function
CIRCLE statement
CLEAR statement
CLNG function
CLOSE statement
CLS statement
/CMD option
Color Graphics AdapterCGA adapter
COLOR statement
COM devices
COM statements
COMMAND$ function
COMMAND.COM
Commandline, passing to BASIC program
Comments
    introducing
    REM statement
COMMON statement
    blank
    chaining programs
    declaring variables
    named
    order of variables
    SHARED attribute
Compile-time error messages
Concatenation operator(+)
CONST statement
Constants
    global
    local
    scope rules
    symbolic
Control-flow statements
    CALL
    CALL ABSOLUTE
    CALLS
    CHAIN
    DEF FN
    DO...LOOP
    FOR...NEXT
    FUNCTION
    GOSUB...RETURN
    GOTO
    IF...THEN...ELSE
    ON GOSUB
    ON GOTO
    RETURN
    SELECT CASE
    WHILE...WEND
COS function
Cosine, COS function
CSNG function
CSRLIN function
CVD function
CVDMBF function
CVI function
CVL function
CVS function
CVSMBF function

D

DATA statement
Data types
    double-precision floating-point numeric
    fixed-length string
    four-byte integer numeric
    integer numeric
    long-integer numeric
    single-precision floating-point numeric
    specifying
    two-byte integer numeric
    TYPE statement
    variable-length string
Date and time
    functions
    DATE$
    TIME$
    statements
    DATE$
    TIME$
DATE$ function
DATE$ statement
Debugging statements
Declarations
    CONST statement
    DECLARE statement (BASIC procedures)
    DECLARE statement (non-BASIC procedures)
    DEF type statements
    DIM statement
    fixed-length strings
    simple variables
    variable types
DECLARE statements
    described
    location of arguments
DEF FN functions
    BASIC, used in
    exit from, alternative
    variable scope
DEF FN statement
DEF SEG statement
DEF type statements
Default data segments
DEFDBL statement
DEFINT statement
DEFLNG statement
DEFSNG statement
DEFSTR statement
Device errors
Devices, handling
    functions
    IOCTL$
    LPOS
    PEN
    statements
    IOCTL
    OPEN COM
    OUT
    WAIT
Device-status information
DGROUP, defined
DIM statement
    description
    SHARED attribute
    variable types
Directory statements
    CHDIR
    FILES
    MKDIR
    NAME
    RMDIR
Display memory, PCOPY statement
Division by zero
DO UNTIL statement
DO WHILE statement
Document conventions
DO...LOOP statement
    exit from, alternative
    flow control
DOS
    environment variables
    interrupts
DOS-level commands
Double precision
    numbers
    converting to
    description
    PRINT, displayed by
    variables
DRAW statement
    description
DRAWstatement
    VARPTR$ function, using
¢DYNAMIC arrays
    described
    location in memory
Dynamic arrays
    ERASE statement
    REDIM statement

E

EGA adapter
    COLOR statement
    PALETTE statement
    SCREEN statement
EGAadapter
    COLOR statement
END CASE clause
END DEF statement
END FUNCTION statement
END IF statement
END SELECT statement
END statement
END SUB statement
END TYPE statement
Enhanced Graphics AdapterEGA adapter
ENVIRON$ function
ENVIRON statement
Environment variables
Environment-string table
EOF function
ERASE statement
ERDEV function
ERDEV$ function
ERL function
    described
    line labels with
ERR code
ERR function
Error codes
Error handling
    error line number
    statements
    ERDEV
    ERR, ERL
    ERROR
    ON ERROR
    RESUME
Error messages
    compile-time
    described
    invocation
    LIB
    LINK
    run-time
ERROR statement
Error trapping
    ERROR statement
    line 0, using
Event-trapping statements
    COM
    KEY(n)
    ON event
    ON UEVENT
    PEN ON, OFF, and STOP
    PLAY ON, OFF, and STOP
    TIMER ON, OFF, and STOP
    UEVENT
.EXE files
EXIT DEF statement
EXIT DO statement
EXIT FOR statement
EXIT FUNCTION statement
EXIT statement
    description
    multiline functions, use in
    subprograms, use in
EXIT SUB statement
EXP function
Expressions
    conversion of operands
    definition

F

Far addresses
FIELD statement
File access
    LOCK statement
    UNLOCK statement
File conversion
File handling
    functions
    EOF
    FILEATTR
    FREEFILE
    LOC
    LOF
    SEEK
    statements
    CHDIR
    CLOSE
    FIELD
    GET
    INPUT #
    KILL
    LOCK
    NAME
    OPEN
    RESET
    SEEK
    UNLOCK
File names, described
FILEATTR function
Files
    attributes
    binary mode, statements and functions
    FILEATTR
    GET
    LOC
    LOCK
    OPEN
    PUT
    SEEK function
    SEEK statement
    random access, statements and functions
    EOF
    FIELD
    GETIO
    KILL
    LOC
    LOCK
    LSET
    MKI$, MKS$, MKD$, MKL$
    OPEN
    PUT
    RSET
    SEEK function
    SEEK statement
    sequential, statements and functions
    EOF
    INPUT #
    KILL
    LINE INPUT #
    LOC
    LOF
    OPEN
    PRINT #
    WRITE #
FILES statement
FIX function
Fixed-point constants
Floating point
    double precision
    constants
    range
    numbers
    single precision, range
Formatting output
FOR...NEXT statements
    description
    exit from, alternative
FRE function
FREEFILE function
FUNCTION procedures
    DECLARE statements
    exit from, alternative
    module organization
    STATIC keyword
FUNCTION statements
Functional operators
Functions
    built-in
    intrinsic
    user-defined
    variables, declaring as local

G

GET statements
    FIELD statement
    File I/O
    Graphics
Global constants
Global variables
GOSUB statement
GOTO statement
    description
    line labels, using
    subroutines, use with
Graphics
    functions
    PMAP
    POINT
    macro language
    statements
    BLOAD
    BSAVE
    CIRCLE
    COLOR
    DRAW
    GET
    LINE
    PAINT
    PALETTE
    PALETTE USING
    PRESET
    PSET
    PUT
    VIEW
    WINDOW

H

Hercules adapters
HEX$ function
Hexadecimal numbers
Hierarchy, of operators

I

IEEE-format numbers
IF...THEN...ELSE statements
    description
    GOTO statement, when required
    line labels
INKEY$ function
INP function
INPUT$ function
Input functions
    COMMAND$
    INP
    INPUT$
INPUT # statement
INPUT statement
    description
    FIELD statement
    line editor commands
Input statements
    DATA
    INPUT
    INPUT #
    LINE INPUT
    LINE INPUT #
    READ
    RESTORE
    WAIT
INSTR function
INT function
INT86, INT86X replacements
    CALL INT86OLD statements
    CALL INTERRUPT statements
Integers
    constants
    decimal
    hexadecimal
    octal
    converting to
    division
    FIX function
Intrinsic functions
Invocation error messages
I/O ports
IOCTL$ function
IOCTL statement
Italic text, showing placeholders

J

Joysticks

K

KEY OFF statement
Keyboard scan codes
KEY(n) statements
KILL statement

L

LBOUND function
LCASE$ function
LEFT$ function
LEN function
LET statement
LIB error messages
Line 0, effect on error trapping
Line feed
LINE INPUT # statement
LINE INPUT statement
Line labels
    alphanumeric
    case, significance of
    GOTO statement, use with
    RESUME statement
    use of
Line numbers
    example of
    restrictions
    RESUME statement
    use of
Line printer
LINE statement
Line styling
Line-editor commands
LINK error messages
LOC function
Local constants
Local variables
LOCATE statement
LOCK statement
LOF function
LOG function
Logical operators
    description
    type conversion
Long integers
    constants
    converting to
Loops
LPOS function
LPRINT statement
    description
    SPC function
LPRINT USING statement
LSET statement
LTRIM$ function

M

Main module
Math functions
    ABS
    ATN
    COS
    CVSMBF
    EXP
    LOG
    MKSMBF$, MKDMBF$
    SIN
    SQR
    TAN
MCGA adapter
    COLOR statement
    PALETTE statement
    SCREEN statement
MDPA adapter, PALETTE statement
Memory management
    functions
    FRE
    SETMEM
    statements
    CLEAR
    DEF SEG
    ERASE
    PCOPY
Microsoft Binary format numbers
MID$ function
MID$ statement
Mixed-language programming
    ALIAS, use of
    BYVAL, use of
    CALL, CALLS statement (non-BASIC)
    CDECL, use of
    DECLARE statement (non-BASIC)
    SADD function
    SEG, use of
    variable storage allocation
    VARPTR function
MKD$ function
MKDIR statement
MKI$ function
MKL$ function
MKS$ function
MKSMBF$ function
MOD, module arithmetic operator
Module-level code
Modules
Modulo arithmetic
Modulus operator
MulticolorGraphics Array adapterMCGA
Multiline functions, run-time features, nesting
Music
    background
    macro language

N

NAME statement
Near addresses
NEXT statement
Notational conventions
Numeric constants
Numeric conversions
    CVD function
    CVI function
    CVL function
    CVS function
    double precision
    integer
    single precision
Numeric functions
    CDBL
    CINT
    CLNG
    CSNG
    CVD
    CVI
    CVL
    CVS
    FIX
    INT
    RND
    SGN

O

OCT$ function
Octal conversion
Olivetti
    displays
    OS/2 warning
ON COM statement
ON ERROR statement
    description
    line 0, effect of
    line labels
ON event statements
ON KEY statement
ON PEN statement
ON PLAY statement
ON STRIG statement
ON TIMER statement
ON UEVENT statement
ON...GOSUB statement
ON...GOTO statement
OPEN COM statement
OPEN statement
Operators
    arithmetic
    concatenation
    definition
    functional
    logical
    precedence
    relational
    string
OPTION BASE statement
OUT statement
Output
    functions
    LPOS
    POS
    TAB
    line width
    statements
    BEEP
    CLS
    LPRINT
    OUT
    PRINT
    PRINT #
    PRINT # USING
    PRINT USING
    PUT
    WRITE
    WRITE #
Overflow

P

PAINT statement
PALETTE statement
PALETTE USING statement
Passing arguments
PCOPY statement
PEEK function
PEN function
PEN OFF statement
PEN ON statement
PEN STOP statement
Physical coordinates
    mapping to logical coordinates
    view
Physicalviewport
PLAY function
PLAY OFF statement
PLAY ON statement
PLAY statement
    description
    VARPTR$ function,using
PLAY STOP statement
PMAP function
POINT function
POKE statement
POS function
Precedence of operators
PRESET statement
PRINT # statement
PRINT statement
    description
    SPC function
PRINT # USING statement
PRINT USING statement
Procedures
Program suspension
Program termination
PSET statement
PUBLIC symbol
PUT statements
    FIELD statement
    File I/O
    Graphics

R

Random numbers
Random-access files, statements and functions
    EOF
    FIELD
    GET
    KILL
    LOC
    LOCK
    MKD$, MKI$, MKL$, MKS$
    OPEN
    PUT
    SEEK function
    SEEK statement
    storing data in buffer
RANDOMIZE statement
READ statement
Real numbers
Record elements, reference
Record variables
Records
    arrays of
    variable length
Recursion
REDIM statement
    description
    SHARED attribute
    variables, declaring
Referencing record elements
Register values, INT86OLD, INT86XOLD
Relational operators
REM statement
RESET statement
RESTORE statement
RESUME NEXT statement
RESUME statement
    alphanumeric line labels
    BASICA, differences from
    description
    RESUME 0, effect of
RETURN statement
    description
    EXIT statement, not equivalent to
    GOSUB statement
RIGHT$ function
RMDIR statement
RND function
RSET statement
RTRIM$ function
RUN statement
Run-time error messages

S

SADD function
    described
    movement of variables
Scan codes, keyboard
Scope
SCREEN 10, using
Screen functions
    CSRLIN
    POS
    SCREEN
Screen statements
    CLS
    COLOR
    LOCATE
    PCOPY
    SCREEN
    VIEW PRINT
Screenstatements
    WIDTH
SEEK
    function
    statement
SEG, use in DECLARE statement
SELECT CASE statement
Sequential files, statements and functions
    EOF
    INPUT #
    KILL
    LINE INPUT #
    LOC
    LOF
    OPEN
    PRINT #
    WRITE #
SETMEM function
    described
    movement of variables
SetUEvent routine
SGN function
SHARED statement
    described
    variables
    declaring
    local
    sharing
Shared variables
    among modules
    within a module
Shell escape
SHELL statement
Simple variables
    declaring
    location in memory
SIN function
Sine, SIN function
Single-precision numbers
    converting to
    PRINT, displayed by
    types of constants
SLEEP statement
SOUND statement
Source files
SPACE$ function
SPC function
Special characters
Spiral of Archimedes
SQR function
Statements
¢STATIC arrays
    described
    location in memory
Static arrays, ERASE statement
STATIC keyword
STATIC statement
    description
    variables
    declaring
    local
    STATIC, creating
STICK function
STOP statement
Storage requirements, variables
STR$ function
STRIG function
STRIG OFF statement
STRIG ON statement
STRIG(n) statements
String
    concatenation
    constants
    descriptor length
    functions
    ASC
    CHR$
    DATE$
    HEX$
    INPUT$
    INSTR
    LCASE$
    LEFT$
    LEN
    LTRIM$
    MID$
    RIGHT$
    RTRIM$
    SADD
    SPACE$
    STR$
    STRING$
    UCASE$
    VAL
    operators
    processing
    statements
    LSET
    MID$
    RSET
    variables
STRING$ function
String-space compaction
SUB procedures
    DECLARE statements
    exit from, alternative
    STATIC keyword
    using
SUB statement
Subprograms
    CALL statement
    CALLS statement
    CHAIN statement
    SUB statement
    user library, example
    variables
Subroutines
Subscripts, specifying
    lower bound for
    maximum value for
    number of
SWAP statement
Symbolic constants
    CONST
    use of
Syntax notation
    choices
    optional items
    placeholders
System calls
SYSTEM statement

T

TAB function
TAN function
Tangent, TAN function
Tiling
TIME$ function
TIME$ statement
TIMER function
TIMER OFF statement
TIMER ON statement
TIMER STOP statement
Timing function
Trigonometric functions
    ATN
    COS
    SIN
    TAN
TROFF statement
TRON statement
Type conversion
    logical operators
    rules for
TYPE statements
Typeface
    key names
    keywords
    placeholders
    program
Type-mismatch error message
Typographic conventions

U

UBOUND function
UCASE$ function
UEVENT statement
UNLOCK statement
User-defined data types
User-defined events
User-defined functions

V

VAL function
Variable-length records
Variable-length strings, location in memory
Variables
    array
    automatic
    data type
    definition
    global
    function definitions
    subprograms
    using
    local
    function definitions
    subprograms
    using
    names
    length
    rules
    record
    scope
    shared variables
    STATIC variables
    storage allocation
    storage requirements
    string
    type-declaration suffixes
VARPTR function
    described
    movement of variables
VARPTR$ function
    described
    movement of variables
VARSEG function
    described
    movement of variables
VGA adapter
    COLOR statement
    PALETTE statement
    SCREEN statement
VGAadapter
    COLOR statement
Video GraphicsArray adapterVGA adapter
Video memory
View coordinates
    mapping to physical coordinates
    WINDOW statement
VIEW PRINT statement
VIEW statement

W

WAIT statement
WEND statement
WHILE statement
WIDTH statement
WINDOW statement
WRITE # statement
WRITE statement