Using QuickBASIC

The left side of the Contents screen contains hyperlinks to general topics
about how to use QuickBASIC.

Topic                        Summary
Shortcut Key Summary       A table display of the keystroke combinations
                             QuickBASIC recognizes as commands. Some key
                             combinations are equivalent to QuickBASIC menu
                             commands; others execute commands that are not
                             in the menus.

Limits to QuickBASIC       Displays the maximum and minimum sizes and
                             values of objects that QuickBASIC can handle.

Version 4.5 Differences    Compares the new features built into QuickBASIC
                             4.5 with those in versions 2.0, 3.0, and 4.0.

QB Command Line Options    Displays all the options you can use in the
                             command line when you invoke QuickBASIC.

Survival Guide             Summarizes how to use the keyboard and mouse
                             with QuickBASIC menus, dialog boxes, and windows.
BASIC Programming Language

The right side of the Contents screen contains hyperlinks to information
about the BASIC programming language.

Topic                          Summary

Functional Keyword Lists     Display most of the BASIC keywords in groups
                               according to common programming tasks, such
                               as constructing a loop, defining a procedure,
                               getting input from the keyboard, or writing
                               data to a file.

Syntax Notation              Shows how to read the syntax information that
                               is displayed in the on-line help for BASIC
                               language keywords.

Fundamental Building Blocks  Gives the rules for composing BASIC program
                               lines character by character. Also lists the
                               special meaning of some characters (such as %,
                               !, or #) in a BASIC program line.

Data Types                   Summarizes the advantages and disadvantages of
                               using different data types and data structures
                               in your programs.

Expressions and Operators    Shows how to combine program variables into
                               expressions that calculate values, compare
                               values, and build new screens.

Modules and Procedures       Shows how to combine relatively short,
                               easy-to-understand modules of program text
                               into programs.

Selected Programs            A set of 10- to 20-line program modules that
                               do things programmers often want to do--such
                               as creating and writing to a data file.

ASCII Character Codes        These tables display values that programmers
Keyboard Scan Codes          often need to include in their programs.
  Help on Help   Contents   Index                         ◄Copyright►
──────────────────────────────────────────────────────────────────────────────
                               Copyright

  Information in this document is subject to change without notice and does
  not represent a commitment on the part of Microsoft Corporation. The
  software and/or files described in this document are furnished under a
  license agreement or nondisclosure agreement. The software and/or files
  may be used or copied only in accordance with the terms of the agreement.
  The purchaser may make one copy of the software for backup purposes. No
  part of this on-line help system may be reproduced or transmitted in any
  form or by any means, electronic or mechanical, including photocopying,
  recording, or information storage and retrieval systems, for any purpose
  other than the purchaser's personal use, without the written permission
  of Microsoft Corporation.

  RESTRICTED RIGHTS: Use by the U.S. Government subject to restrictions of
  (c) (1) (ii) of DFARS 252.227-7013.


  (C) Copyright Microsoft Corporation, 1985-1990.
      All rights reserved.
      Simultaneously published in the U.S. and Canada.

  Microsoft(R), MS(R), MS-DOS(R), CodeView(R), and Xenix(R) are registered
  trademarks.

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

  IBM(R) is a registered trademark of the International Business
  Machines Corporation.

  Hercules(R) is a registered trademark and Hercules(R) InColor
  Card(TM) is a trademark of Hercules Computer Technology.

  Intel(R) is a registered trademark of Intel Corporation.

  Olivetti(R) is a registered trademark of Ing. C. Olivetti.

  PC/AT(R), PC/XT(R), and PS/2(R) are registered trademarks of the
  International Business Machines Corporation.

  Tandy(R) is a registered trademark of Tandy Corporation.

  UNIX(R) is a registered trademark of AT&T Bell Laboratories.
  ◄QuickBASIC Command Line►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
QuickBASIC Command Line Options

The full syntax for the QB command is the following:

QB [/RUN [programname]][/B][/G][/H][/NOHI][/C: buffersize][/L [libraryname]]
   [MBF] [/AH] [/CMD string]

These options can be typed on the DOS command line following the QB command
and have the effects described. Use the options in the order listed.

Option              Description

/RUN [programname]  Causes QuickBASIC to load and run programname before
                    displaying it.

programname         Names the file to be loaded when QuickBASIC starts.

/B                  Allows the use of a composite (black-and-white) monitor
                    with a color graphics card. The /B option displays
                    QuickBASIC in black and white if you have a color monitor.

/G                  Sets QuickBASIC to update a CGA screen as fast as
                    possible. The option works only with machines using CGA
                    monitors. If you see snow (dots flickering on the
                    screen) when QuickBASIC updates your screen, then your
                    hardware cannot fully support the /G option. If you
                    prefer a clean screen, restart QuickBASIC without the
                    option.

/H                  Displays the highest resolution possible on your
                    hardware.

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

/C: buffersize      Sets the size of the buffer receiving data. This option
                    works only with an asynchronous communications card.
                    The default buffer size is 512 bytes; the maximum size
                    is 32,767 bytes.

/L [libraryname]    Loads the Quick library that is specified by libraryname.
                    If libraryname is not specified, the default Quick
                    library, QB.QLB, is loaded.

/MBF                Causes the QuickBASIC conversion functions to treat
                    IEEE-format numbers as Microsoft Binary format numbers.

/AH                 Allows dynamic arrays of records, fixed-length strings,
                    and numeric data to be larger than 64K each.

/CMD string         Passes string to the COMMAND$ function. This option
                    must be the last option on the line.
                MDPA, CGA, EGA, or VGA Adapter Boards
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 8 x 8 character box size (8 x 14, 9 x 14, or 9 x 16 with EGA or VGA)
  ■ 16 colors assigned to 2 attributes
  ■ 16 colors assigned to any of 16 attributes (with CGA or EGA)
  ■ 64 colors assigned to any of 16 attributes (with EGA or VGA)
                CGA, EGA, VGA, or MCGA Adapter Boards
SCREEN 1: 320 x 200 graphics
  ■ 40 x 25 text format, 8 x 8 character box
  ■ 16 background colors and one of two sets of 3 foreground colors assigned
    using COLOR statement with CGA
  ■ 16 colors assigned to 4 attributes with EGA or VGA
SCREEN 2: 640 x 200 graphics
  ■ 80 x 25 text format with character box size of 8 x 8
  ■ 16 colors assigned to 2 attributes with EGA or VGA
                        Other Adapter Boards
SCREEN 3: Hercules adapter required, monochrome monitor only
  ■ 720 x 348 graphics
  ■ 80 x 25 text format, 9 x 14 character box
  ■ 2 screen pages (1 only if a second display adapter is installed)
  ■ PALETTE statement not supported
SCREEN 4:
  ■ Supports Olivetti (R) Personal Computers models M24, M240, M28,
    M280, M380, M380/C, M380/T and AT&T (R) Personal Computers 6300
    series
  ■ 640 x 400 graphics
  ■ 80 x 25 text format, 8 x 16 character box
  ■ 1 of 16 colors assigned as the foreground color (selected by the
    COLOR statement); background is fixed at black.
                    EGA and VGA Adapter SCREEN Modes
SCREEN 7: 320 x 200 graphics
  ■ 40 x 25 text format, character box size 8 x 8
  ■ 32K page size, page ranges are 0-1 (64K), 0-3 (128K), or 0-7 (256K)
  ■ Assignment of 16 colors to any of 16 attributes
SCREEN 8: 640 x 200 graphics
  ■ 80 x 25 text format, 8 x 8 character box
  ■ 64K page size, page ranges are 0 (64K), 0-1 (128K), or 0-3 (246K)
  ■ Assignment of 16 colors to any of 16 attributes
SCREEN 9: 640 x 350 graphics
  ■ 80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box size
  ■ 64K page size, page range is 0 (64K);
    128K page size, page range is 0 (128K) or 0-1 (256K)
  ■ 16 colors assigned to 4 attributes (64K adapter memory), or
    64 colors assigned to 16 attributes (more than 64K adapter memory)
     EGA and VGA Adapter SCREEN Mode, Monochrome Monitor Only
SCREEN 10: 640 x 350 graphics, monochrome monitor only
  ■ 80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box size
  ■ 128K page size, page range is 0 (128K) or 0-1 (256K)
  ■ Up to 9 pseudocolors assigned to 4 attributes
                    VGA and MCGA Adapter SCREEN Modes
Screen 11
  ■ 640 x 480 graphics
  ■ 80 x 30 or 80 x 60 text format, character box size of 8 x 16 or 8 x 8
  ■ Assignment of up to 256K colors to 2 attributes
Screen 12
  ■ 640 x 480 graphics
  ■ 80 x 30 or 80 x 60 text format, 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 graphics
  ■ 40 x 25 text format, character box size of 8 x 8
  ■ Assignment of up to 256K colors to up to 256 attributes
◄Search Keys►   Contents   Index
──────────────────────────────────Search Keys─────────────────────────────────
     Search for selected (highlighted) text                     Ctrl+\
     Repeat the last find                                       F3
  ◄Version 4.5 Differences►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Differences from Previous Versions of QuickBASIC

                                          QuickBASIC Version
Feature                        2.0          3.0           4.0          4.5
                            ──────────────────────────────────────────────────

On-line QB Advisor              No           No            No          Yes
(detailed reference)
Selectable right mouse button   No           No            No          Yes
function
Instant Watches for variables   No           No            No          Yes
and expressions
Set default search paths        No           No            No          Yes
User-defined types              No           No            Yes         Yes
IEEE format, math coprocessor   No           Yes           Yes         Yes
support
On-line help                    No           No            Yes         Yes
Long (32-bit) integers          No           No            Yes         Yes
Fixed-length strings            No           No            Yes         Yes
Syntax checking on entry        No           No            Yes         Yes
Binary file I/O                 No           No            Yes         Yes
FUNCTION procedures             No           No            Yes         Yes
CodeView support                No           No            Yes         Yes
Compatibility with other        No           No            Yes         Yes
languages
Multiple modules in memory      No           No            Yes         Yes
ProKey, SideKick, and           No           Yes           Yes         Yes
SuperKey compatibility
Insert/overtype modes           No           Yes           Yes         Yes
WordStar-style keyboard         No           No            Yes         Yes
interface
Recursion                       No           No            Yes         Yes
Error listings during           No           Yes           Yes         Yes
separate compilation
Assembly-language listings      No           Yes           Yes         Yes
during separate compilation

Features New to QuickBASIC 4.5

You can now access on-line help for QuickBASIC's keywords, commands,
and menus, as well as general topics and your own variables. Examples
shown on help screens can be copied and pasted directly into your
own program, reducing development time.

Mouse users can now set the function of the right mouse button with the
Right Mouse command from the Options menu. Use the function that best
suits your needs.

For faster debugging, QuickBASIC now offers an Instant Watch command
for immediately identifying the value of a variable or the condition
(true or false) of an expression.

Version 4.5 also lets you set default search paths to specific types
of files. This lets you organize your files by type and keep them
in separate directories. QuickBASIC will search the correct directory
after you set the new default search path. You can set default paths
for executable, include, library, and help files.
  ◄Fundamental Building Blocks►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Language Elements

Characters from the BASIC character set are put together to form labels,
keywords, variables, and operators. These are combined to form statements
that are combined into a program.

The topics listed below contain additional information on the fundamental
elements of BASIC:

  BASIC Topic                         Summary
  Character Set                     Characters used in BASIC
  Program Line                      Syntax of BASIC program lines
  Statements                        Types and Listing of BASIC Statements
  Fundamental Building Blocks   ◄Character Set►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Character Set

The Microsoft BASIC character set includes alphabetic characters (A-Z, a-z),
numeric characters (0-9 and A-F or a-f for hexadecimal numbers), and
special characters. Some characters have special meanings in BASIC:

     Data type suffixes
     !              Single-precision data type suffix
     #              Double-precision data type suffix
     $              String data type suffix
     %              Integer data type suffix
     &              Long-integer data type suffix

     Math special characters
     *              Multiplication symbol
     +              Plus sign
     -              Minus sign
     .              Decimal point
     /              Division symbol (slash)
     <              Less than
     =              Relational operator or assignment symbol
     >              Greater than
                   Integer division symbol (backslash)
     ^              Exponentiation symbol (up arrow or caret)

     Other characters
     ENTER          Terminates input of a line
     _              Line continuation (underscore)
  Fundamental Building Blocks   ◄Program Line►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
The BASIC Program Line

All BASIC program lines have the following syntax:

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

Line identifier
A line in BASIC may have one line-identifier. BASIC supports two types of
line-identifiers (which may be used in the same program):

  ■ line numbers
       ■ Range 0 to 65,529
       ■ May begin in any column; must be first character in the line

       ■ line numbers (examples):
               200
               300 PRINT"hello"     '300 is the line number

       ■ line numbers (special notes):
            ■ Using 0 is not recommended since it has a special meaning to
              the ON ERROR, ON event, and RESUME statements.

            ■ 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 expect the lines
              to be in numerical order: 5, 10, 100.

  ■ alphanumeric line labels
       ■ 1 to 40 letters and digits.
       ■ Must start with a letter and end with a colon.
       ■ BASIC keywords are not permitted.
       ■ May begin in any column; must be first character in the line.
       ■ Case is not significant (alpha:, AlPHa:  and ALPHA: are equivalent
         line labels).
       ■ Blanks and tabs are allowed between the label and the colon.

       ■ alphanumeric line labels (examples):
               Alpha:
               ScreenSub:

       ■ alphanumeric line labels (special notes):

            ■  May not be used in IF...THEN statements, unless you use a
               GOTO statement:

                    IF A = 10 THEN 500     'correct use of line number

            ■  If the object of the IF...THEN statement is a line label, a
               GOTO statement is required:

                   IF A = 10 THEN GOTO IncomeData

BASIC Line Length

  ■ From within the QuickBASIC editor
     ■ QuickBASIC's built-in editor limits the length to 256 characters
     ■ The underscore character (_) cannot be used for line continuation

  ■ From within your own editor
     ■ You may use the 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 that may
       exceed 256 characters in length

     ■ Underscores cannot be used to continue DATA or REM statements
  Fundamental Building Blocks   ◄Statements►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Language Elements: 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 (for example, to read input,
    write output, add two numbers together and store the result in a
    variable).

  ■ 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 procedures.

    The following BASIC statements are nonexecutable:

         REM or '                      DIM (static arrays only)
         COMMON                        OPTION BASE
         CONST                         SHARED
         DATA                          STATIC
         DECLARE                       TYPE...END TYPE
         DEFtype
  ◄Data Types►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Data Type                 Declaration      Maximum          Minimum
Strings                       $           32,767 chars.    0 chars.
Integers                      %           32,767          -32,768
Long Integers                 &           2,147,483,647   -2,147,483,648
Single (7-digit) precision    !          ±3.402823 E+38    ±1.401298 E-45
Double (15-digit) precision   #          ±1.7976931 D+308  ±4.940656 D-324
User-Defined Data Types

See Also  DEFtype Statement - Set default data type
          Variable-Type Memory Requirements - Memory requirements for
          variable types
          Constants - Predefined values that do not change
          Variables - A name that refers to an object
          Scoping Rules - The range where a variable or constant is defined
          Static and Dynamic Arrays - Storage of arrays
          Automatic and Static Variables - Initialization of variables
          Type Conversion - Converting between BASIC data types
  Data Types   ◄Strings►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Elementary Data Types - Strings

There are two kinds of strings:

  ■ 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 regular ASCII
      (American Standard Code for Information Interchange) characters, and
      from 128-255 for the extended-ASCII characters. See the on-line
      ASCII Character Codes Table for examples of each type.

  ■ Fixed-length string
      A fixed-length string contains a declared number of characters,
      no more than 32,767.
      Like variable-length strings, a fixed-length string contains
      characters with codes ranging from 0-255.
  Data Types   ◄Integers and Long Integers►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Elementary Data Types - Integers and Long Integers

Integers are stored as 16-bit binary numbers (two bytes) ranging in value
from -32,768 to +32,767.

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

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).
  Data Types   ◄Floating-Point Numbers►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Elementary Data Types - Floating-Point Numbers

QuickBASIC uses IEEE-format floating-point numbers rather than the Microsoft
Binary format used in earlier versions. IEEE format gives more accurate
results and makes it possible to use a math coprocessor (for example,
an 8087, 80287, or 80387).

Floating-point values are represented in a different format from integers.
Each floating-point value consists of three parts: the sign, the exponent,
and the mantissa.

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 eight 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.
  Data Types   ◄User-Defined Data Types►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.

  Note: User-defined types cannot include arrays or variable-length
        strings.
  Data Types   ◄Memory Requirements►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
         AS Type              Variable            Size
Suffix   Name      DEFtype    Type                of Data

  %      INTEGER   DEFINT     Integer             2 bytes
  &      LONG      DEFLNG     Long integer        4 bytes
  !      SINGLE    DEFSNG     Single precision    4 bytes
  #      DOUBLE    DEFDBL     Double precision    8 bytes

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

  $      STRING*num           Fixed-length        Takes num bytes
                              string

         Declared user-                           Takes as many bytes as
         defined type                             the individual elements
                                                  require
  Data Types   ◄Constants►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Constants

Constants are predefined values that do not change during program execution.

String Constants

A string constant is a sequence of alphanumeric characters enclosed by
double quotation marks.

These alphanumeric characters can be any of the characters whose ASCII codes
fall within the range 0-255 (except the double quote character (") and
carriage-return/line-feed sequences). This range includes both the actual
ASCII characters (0-127) and the extended characters (128-255).

Numeric Constants

Numeric constants are positive or negative numbers. Numeric constants in
BASIC cannot contain commas. The types and subtypes of constants are
listed below:

Type (subtype)      Description

Integer             One or more decimal digits (0-9), with an optional sign
(decimal)           prefix  (+ or -). The range for integer decimal
                    constants is -32,768 to +32,767.

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

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

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

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

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

Fixed point         Positive or negative real numbers (numbers containing
                    decimal points).

Floating point      Positive or negative numbers represented in exponential
(single precision)  form. 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 exponent). The constant's value is
                    the mantissa multiplied by the power of ten represented
                    by the exponent. Single-precision constants have a
                    range of -3.37E+38 to 3.37E+38.

Floating point      Double-precision floating-point constants have the same
(double precision)  form as 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.

Single-precision constants

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

Double-precision constants

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

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.
  Data Types   ◄Variables►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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:

  ■ A constant value:
      A = 4.5

  ■ The value of another string or numeric variable:
      B$ = "ship of fools"
      A$ = B$
      Profits = NetEarnings

  ■ The value of a record element:
      TYPE EmployeeRec
        FullName AS STRING * 25
        SocSec   AS STRING * 9
      END TYPE
      DIM CurrentEmp AS EmployeeRec
      .
      .
      .
      OutSocSec$=CurrentEmp.SocSec

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

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

In any case, the variable must always match the type of data (numeric or
string) assigned to it.

  Note: 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.

See Also  Variable Names
          Declaring Simple Variables
          Declaring Array Variables
          Variable Storage Allocation
  Variables   ◄Variable Names►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Variable Names

A BASIC variable name may contain up to 40 characters. The characters
allowed in a variable name are letters, numbers, the period (.), 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.

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.

Note: Variable names cannot duplicate procedure (SUB and FUNCTION) names
      or symbolic constant (CONST) names.
  Variables   ◄Declaring Simple Variables►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Declaring Simple Variables

Simple variables can be numeric, string, or record variables. You may
specify simple variable types in three different ways:

  Type-declaration suffix
  AS declaration statement
  DEFtype declaration statement
  Declaring Simple Variables   ◄Suffixes►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Type Declaration Suffixes

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

The dollar sign ($) is the type-declaration character for string variables.
You can assign a string constant to the variable of up to 32,767
characters, as in the example below.

  A$ = "SALES REPORT"

Numeric-variable names can declare integer values (denoted by a % suffix),
long-integer values (denoted by a & suffix), single-precision values
(denoted by a ! suffix), or double-precision values (denoted by a #
suffix).

Single precision is the default for variables without a type suffix.

There is no type declaration character for a user-defined type.
  Declaring Simple Variables   ◄AS Declarations►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
AS Declaration Statements

Declare the variable in a declaration having the form

 declare variablename AS type

where the "declare" can be either DIM, COMMON, REDIM (for arrays), SHARED,
or STATIC, and the "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

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

To refer to individual elements of the new variable, use the format

  variablename.elementname

as in the following example:

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

Note: 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 used in the DIM statement:

        CONST MAXEMPLOYEES = 250
        DIM EmpNames(MAXEMPLOYEES) AS STRING
        COMMON EmpNames() AS STRING
        .
        .
        .
  Declaring Simple Variables   ◄DEFtype Declarations►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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. Remember a DEFtype statement affects all variables starting with
the given letter or range of letters.

            AS Type                      Variable            Size
Suffix      Name         DEFtype         Type                of Data
------      ------       -------         --------            -------
  %         INTEGER      DEFINT          Integer             2 bytes
  &         LONG         DEFLNG          Long integer        4 bytes
  !         SINGLE       DEFSNG          Single precision    4 bytes
  #         DOUBLE       DEFDBL          Double precision    8 bytes

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

  $         STRING*num                   Fixed-length        Takes num bytes.
                                         string

            Declared                                         Takes as many
            user-defined                                     bytes as the
            type                                             individual
                                                             elements
                                                             require.
  Variables   ◄Declaring Array Variables►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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. (Noninteger numeric expressions
used as array subscripts are rounded to integer values.) An array-variable
name 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. 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 the dot notation form
(variablename.elementname):

  CONST MAXEMPLOYEES = 500
  TYPE EmployeeRec
    FullName AS STRING * 25
    SocSec   AS STRING * 9
  END TYPE
  DIM Employees(MAXEMPLOYEES) AS EmployeeRec
  .
  .
  .
  PRINT Employees(I).FullName;" ";Employees(I).SocSec

Note: 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.

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(0 TO 100) AS INTEGER
  DIM Array#(-5 TO 5)

The first array, Array1, has 101 integer elements, so its values take 202
bytes of memory. The second array, Array2, has 11 double-precision
elements, and so its values require 88 bytes of memory.  Because BASIC
must store information about the array along with the array's values,
arrays take slightly more memory than just the space for the values.
  Variables   ◄Variable Storage Allocation►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Variable Storage Allocation

BASIC stores different kinds of variables in different areas in memory. You
only need to worry about where variables are stored if you are doing mixed-
language programming or you are 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.

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.

When doing mixed-language programming, far addresses are preferred. This
ensures that all generated code is independent of the BASIC implementation.

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.

In programs run within the QuickBASIC environment, array variable
storage follows these rules:

  ■ All static arrays in COMMON 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 variables to move in memory:

  ■ A reference to a string literal or expression
  ■ A DEF FN or FUNCTION invocation
  ■ The use of a BASIC string or memory-related function

Because BASIC variables may move, use the results of a VARPTR, VARSEG,
VARPTR$, or SADD function call immediately after the function call.
  Data Types   ◄Scoping Rules►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Scoping Rules

The following list summarizes BASIC's scoping rules:

  ■ A variable declared in a DIM, REDIM, or COMMON statement with the
    SHARED attribute is a global variable to a module. Any SUB or FUNCTION
    procedure within the module 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 explicitly made local in a STATIC statement or are
    formal parameters.

See Also  Scope of Variables and Constants
          Global Variables and Constants
          Local Variables and Constants
          Sharing Variables
          DEF FN Functions
  Scoping Rules   ◄Scope of Variables and Constants►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Scope of Variables and Constants

Any time a variable appears in program text, BASIC follows a set of rules
to determine which object is referred to by the variable. These rules
describe a variable's scope--the range of statements over which the
variable is defined.

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 (that is, 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. This is done by using the SHARED
statement.
  Scoping Rules   ◄Global Variables and Constants►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.

  ■ A symbolic constant is a global constant if it is declared in the
    module-level code using a CONST statement.

  ■ 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. For example, the following program fragment makes TabStops a
    global variable.

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

The SHARED statement (as opposed to the SHARED attribute, used above) allows
particular procedures to share variables with the module-level code. This is
not the same as making the variable global. It is only global for the
module-level code and all procedures with SHARED statements for the variable.
  Scoping Rules   ◄Local Variables and Constants►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.

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. 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.

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.
  Scoping Rules   ◄Sharing Variables►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 add SHARED statements to the
particular procedures you want to share the variable:

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

The SHARED statements indicate that the name TabStops in both procedures
refers to the same variable defined at the module level.
  Scoping Rules   ◄Scoping Rules: DEF FN Functions►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
DEF FN Functions

The DEF FN is an exception to the BASIC scoping rules. Every variable in a
DEF FN function that isn't in its parameter list is part of the module-
level code. In order 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 its improved portability, increased modularity, and more structured
programming style.
  Data Types   ◄Static and Dynamic Arrays►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 when it is
    needed in order to free memory for other uses.

How an array is declared can determine whether the array is static or
dynamic.

  ■ 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 arrays
to be static in a procedure not declared STATIC; in such a procedure all
arrays are dynamic.
  Data Types   ◄Automatic and Static Variables►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.
  Data Types   ◄Type Conversions►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 the following 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.

  ■ 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
  ◄Expressions and Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Expressions and Operators

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:

   Category                Task
  Arithmetic operators   perform calculations
  Relational operators   compare strings and numeric values
  Logical operators      test complex conditions or manipulate individual
                           bits
  Functional operators   supplement simpler operators
  String operators       combine and compare strings

See Also  Hierarchy of Operations - order of precedence table
          Truth Table             - BASIC logical operators truth table
  Expressions and Operators   ◄Hierarchy►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Hierarchy of Operations

When several BASIC operators occur in the same statement, they 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, not -16:

   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:

   1. 6 / 12   (= 0.5)
   2. 0.5 * 3  (= 1.5)
   3. 3 + 1.5  (= 4.5)
   4. 4.5 - 2  (= 2.5)
  Expressions and Operators   ◄Arithmetic Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.

Generally, two consecutive operators must be separated by parentheses.
Exceptions to this rule are * -, * +, ^ -, and ^ +.

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 so
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.

Example

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

  Output

  2             2.5          -3276         -3276.8499


Modulo Arithmetic

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

Example

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

  Output

  2             2


Overflow and Division by Zero

Dividing by zero, raising zero to a negative power, or arithmetic overflow
produce run-time errors. These errors can be trapped by an error-trapping
routine.  The following BASIC statements are useful for error trapping:

        ERROR  - allows user to define error codes
        ON ERROR  - error handling
        RESUME  - continue execution after error-trapping
        ERR, ERL  - error status
  Expressions and Operators   ◄Relational Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Relational Operators

Relational operators are used to compare two values. 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.

  Operator        Relation                    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.
  Expressions and Operators   ◄Logical Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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"

The six logical operators in BASIC, listed in order of precedence, are:

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

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


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.
  Expressions and Operators   ◄Functional Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 function 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.
  Expressions and Operators   ◄String Operators►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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
value FILENAME:

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

  Output

  FILENAME
  NEW FILENAME

Strings can be compared using the following relational operators:

  <>, =, <, >, <=, and >=

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.  The complete list of ASCII
codes is listed in the ASCII chart.
  Expressions and Operators   ◄Truth Table►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Truth Table for Logical Operators

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

     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
  ◄Modules and Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Modules and Procedures

QuickBASIC programs consist of the following:

modules             - source files that can be separately compiled
FUNCTION procedures - used in expressions; returns a single value directly
DEF FN functions    - can only be defined in module-level code
SUB procedures      - not used in expressions; returns multiple values

Finally, two advanced techniques are available in QuickBASIC.
Argument-passing conventions - Arguments may be passed to a procedure
                                 by reference or by value.
Recursion - SUB or FUNCTION procedures can be recursive.
  Modules and Procedures   ◄Modules►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Modules

BASIC programs consist of one or more modules. A module is a source file
that can be separately compiled.

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-handling 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. In the main module,
module-level code corresponds to what is often called the main program.
  Modules and Procedures   ◄FUNCTION Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
FUNCTION Procedures

FUNCTION procedures provide a powerful alternative to DEF FN functions.
FUNCTION procedures, like DEF FN functions, are used in expressions and
directly return a single value.

There are, however, important differences. A FUNCTION procedure
  ■ passes values by reference, so it can return additional values by
    changing variables in its argument list.
  ■ is not part of the module-level code.
  ■ can be used recursively - it can call itself.
  ■ 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

See Also  DEF FN Functions
  Modules and Procedures   ◄SUB Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 the CALL keyword if the SUB is
declared. When you do this, you omit the parentheses that normally
surround the parameter list.

  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.
  Modules and Procedures   ◄DEF FN Functions►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 SUBs or FUNCTIONs. Like
FUNCTION procedures, DEF FN functions return single values and are used
like BASIC built-in 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. The name of a DEF FN function
always begins with FN. In addition, DEF FN functions
  ■ must be defined before they are used
  ■ cannot be called from outside the module in which they are defined.
  ■ cannot be used recursively
  Modules and Procedures   ◄Passing Arguments►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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.
  Modules and Procedures   ◄Recursion►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
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 non-null string is the first character
      ' appended to the reverse of the remaining string.
      Reverse$ = Reverse$(MID$(S$, 2)) + C$
    END IF
  END FUNCTION

  Sample 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.
  ◄Keyboard Scan Codes►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Keyboard Scan Codes

  ESC         01    U            16   | or       2B   F6          40
  ! or 1      02    I            17   Z           2C   F7          41
  @ or 2      03    O            18   X           2D   F8          42
  # or 3      04    P            19   C           2E   F9          43
  $ or 4      05    { or [       1A   V           2F   F10         44
  % or 5      06    } or ]       1B   B           30   NUMLOCK     45
  ^ or 6      07    ENTER        1C   N           31   SCROLL LOCK 46
  & or 7      08    CTRL         1D   M           32   HOME or 7   47
  * or 8      09    A            1E   < or ,      33   UP or 8     48
  ( or 9      0A    S            1F   > or .      34   PGUP or 9   49
  ) or 0      0B    D            20   ? or /      35   -           4A
  _ or -      0C    F            21   RIGHT SHIFT 36   LEFT or 4   4B
  + or =      0D    G            22   PRTSC or *  37   5           4C
  LEFT        0E    H            23   ALT         38   RIGHT or 6  4D
  TAB         0F    J            24   SPACEBAR    39   +           4E
  Q           10    K            25   CAPSLOCK    3A   END or 1    4F
  W           11    L            26   F1          3B   DOWN or 2   50
  E           12    : or ;       27   F2          3C   PGDN or 3   51
  R           13    " or '       28   F3          3D   INS or 0    52
  T           14      or `       29   F4          3E   DEL or .    53
  Y           15    LEFT SHIFT   2A   F5          3F
  ◄Selected Programs►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Selected Programs

There are six sets of example programs, each containing several programs.
Each program is 10 to 20 lines long and carries out a function that is
often used in larger programs. For example, one of the File I/O programs
creates a new sequential data file on disk, accepts input from the keyboard,
and writes that data to the file--all with only 13 program lines.

  Control Flow programs
  File and Device I/O programs
  String Processing programs
  Error and Event Trapping programs
  Graphics programs
  Programs that demonstrate how to construct functions and procedures

These example programs differ from the programming examples that are
available for each BASIC keyword through on-line help. These programs
are more generally useful, and are not written to demonstrate the use
of one statement or function.

They also differ from the sample application programs such as INDEX.BAS and
TERMINAL.BAS. Those programs are much larger and more complex.
  Selected Programs   ◄Control Flow Programs►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Looping and Decision Making

The following programming examples illustrate how to code loops and
decision-making program structures.

Example 1

The following examples illustrate the similarities and differences
between the SELECT CASE and IF...THEN...ELSE statements.

Here is an example of using block IF...THEN...ELSE for a multiple-choice
decision:

  INPUT X
  IF X = 1 THEN
    PRINT "one"
  ELSEIF X = 2 THEN
    PRINT "two"
  ELSEIF X = 3 THEN
    PRINT "three"
  ELSE
    PRINT "must be integer from 1-3"
  END IF

The above decision is rewritten using SELECT CASE below:

  INPUT X
  SELECT CASE X
    CASE 1
      PRINT "one"
    CASE 2
      PRINT "two"
    CASE 3
      PRINT "three"
    CASE ELSE
      PRINT "must be integer from 1-3"
  END SELECT

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

  INPUT X, Y
  IF X = 0 AND Y = 0 THEN
    PRINT "both zero."
  ELSEIF X = 0 THEN
    PRINT "only X is zero."
  ELSEIF Y = 0 THEN
    PRINT "only Y is zero."
  ELSE
    PRINT "neither is zero."
  END IF
  Selected Programs   ◄Example Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Procedures

The following programming examples illustrate how to code and combine
small logical components of programs. There are examples for boths SUBs
and functions.

Programming example 1 - using functions

Corresponding variables must have the same type in both the argument and
parameter lists for a function, as shown in the following example.
In this example, two arguments are passed to the FUNCTION procedure.
The first is an integer specifying the length of the string returned
by the FUNCTION, while the second is a character that is repeated
to make the string.

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

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

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

Sample output

Enter a number (1 to 80): 21
Enter a character: #
#####################
  Selected Programs   ◄I/O Programs►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
File and Device I/O

The following programming examples illustrate how to code file I/O and
device I/O statements.

Example 1 - Sequential File I/O

The following short program creates a sequential file named "Price.Dat,"
then adds data entered at the keyboard to the file. The OPEN statement
in this program both creates the file and readies the file to receive
records. The WRITE # then writes each record to the file. Note that the
number used in the WRITE # statement is the same number given to the
file name Price.Dat in the OPEN statement.

  ' Create a file named Price.Dat
  ' and open it to receive new data:

  OPEN "Price.Dat" FOR OUTPUT AS #1

  DO
    ' Continue putting new records in Price.Dat until the
    ' user presses ENTER without entering a company name:
    '
    INPUT "Company (press <<ENTER>> to quit): ", Company$

    IF Company$ <> "" THEN
      ' Enter the other fields of the record:
      INPUT "Style: ", Style$
      INPUT "Size: ", Size$
      INPUT "Color: ", Clr$
      INPUT "Quantity: ", Qty
      ' Put the new record in the file
      ' with the WRITE # statement:
      WRITE #1, Company$, Style$, Size$, Clr$, Qty
    END IF
  LOOP UNTIL Company$ = ""
  ' Close Price.Dat (this ends output to the file):
  CLOSE #1
  END

Example 2 - Sequential File I/O

The following program opens the Price.Dat file created in
"Example 1 - Sequential File I/O" and reads the records from the
file, displaying the complete record on the screen if the quantity
for the item is less than the input amount.

The INPUT #1 statement reads one record at a time from Price.Dat,
assigning the fields in the record to the variables Company$, Style$,
Size$, Clr$, and Qty. Since this is a sequential file, the records
are read in order from the first one entered to the last one entered.

The EOF (End Of File) function tests whether the last record has been
read by INPUT #. If the last record has been read, EOF returns the value
1 (true), and the loop for getting data ends; if the last record has not
been read, EOF returns the value 0 (false), and the next record is read
from the file.

  OPEN "Price.Dat" FOR INPUT AS #1
  INPUT "Display all items below what level"; Reorder
  DO UNTIL EOF(1)
    INPUT #1, Company$, Style$, Size$, Clr$, Qty
    IF Qty < Reorder THEN
      PRINT  Company$, Style$, Size$, Clr$, Qty
    END IF
  LOOP
  CLOSE #1
  END

Example 3 - Sequential File I/O

The WRITE # statement can be used to write records to a sequential file.
There is, however, another statement you can use to write sequential file
records:

  PRINT #

The best way to show the difference between these two data-storage
statements is to examine the contents of a file created with both. The
following short fragment opens a file Test.Dat then places the same record
in it twice, once with WRITE # and once with PRINT #. After running this
program you can examine the contents of Test.Dat with the DOS TYPE
command:

  OPEN "Test.Dat" FOR OUTPUT AS #1
  Nm$ = "Penn, Will"
  Dept$ = "User Education"
  Level = 4
  Age = 25
  WRITE #1, Nm$, Dept$, Level, Age
  PRINT #1, Nm$, Dept$, Level, Age
  CLOSE #1
  Selected Programs   ◄String Manipulation►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
String Manipulation Programs

The following programming examples demonstrate various ways to manipulate
sequences of ASCII characters known as strings.

Example 1

One of the most common string-processing tasks is searching for a string
inside another string. The INSTR function tells you whether or not
string2 is contained in string1 by returning the position of the first
character in string1 (if any) where the match begins. If no match is
found (that is, string2 is not a substring of string1, INSTR returns
the value 0.

The following programming example demonstrates this:

  String1$ = "A line of text with 37 letters in it."
  String2$ = "letters"
  PRINT "         1         2         3         4"
  PRINT "1234567890123456789012345678901234567890"
  PRINT String1$
  PRINT String2$
  PRINT INSTR(String1$, String2$)

Sample output

         1         2         3         4
1234567890123456789012345678901234567890
A line of text with 37 letters in it.
letters
 24

Example 2

The INSTR(position, string1, string2) variation is useful for finding
every occurrence of string2 in string1, instead of just the first
occurrence of string2 in string1, as shown in the next example:

  String1$ = "the quick basic jumped over the broken saxophone."
  String2$ = "the"
  PRINT String1$
  Start = 1
  NumMatches = 0
  DO
    Match = INSTR(Start, String1$, String2$)
    IF Match > 0 THEN
      PRINT TAB(Match); String2$
      Start = Match + 1
      NumMatches = NumMatches + 1
    END IF
  LOOP WHILE MATCH
  PRINT "Number of matches ="; NumMatches

Sample output

the quick basic jumped over the broken saxophone.
the
                            the
Number of matches = 2
  Selected Programs   ◄Graphics Programs►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Graphics Programs

The following programming examples create shapes, colors, and patterns
on your screen.

Example 1

By making either of the CIRCLE statement start or end arguments negative,
you can connect an arc at its beginning or ending point with the center of
a circle. By making both arguments negative, you can draw shapes ranging
from a wedge that resembles a slice of pie, to the pie itself with the
piece missing. This example draws a pie shape with a piece missing.

  SCREEN 2
  CONST RADIUS = 150, PI = 3.141592653589#
  StartAngle = 2.5
  EndAngle = PI
  ' Draw the wedge:
  CIRCLE (320, 100), RADIUS, , -StartAngle, -EndAngle
  ' Swap the values for the start and end angles:
  SWAP StartAngle, EndAngle
  ' Move the center 10 pixels down and 70 pixels to the
  ' right, then draw the "pie" with the wedge missing:
  CIRCLE STEP(70, 10), RADIUS, , -StartAngle, -EndAngle

Sample output

You'll have to run the program to see the output.
  Selected Programs   ◄Trapping Programs►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Event and Error Trapping

The following program shows how to trap an event that occurs while a
program is running. With event trapping, you can get your program to
detect run-time events such as keystrokes.

Example 1 - Event Trapping

If you use a 101-key keyboard, you can trap any of the keys on the
dedicated keypad by assigning the string

  CHR$(128) + CHR$(scancode)

to any of the keynumber values from 15 to 25.

The next example shows how to trap the LEFT direction keys on both
the dedicated cursor keypad and the numeric keypad.

  ' 128 = keyboard flag for keys on the
  '       dedicated cursor keypad
  '  75 = scan code for LEFT arrow key
  '
  KEY 15, CHR$(128) + CHR$(75)    ' Trap LEFT key on
  ON KEY(15) GOSUB CursorPad      ' the dedicated
  KEY(15) ON                      ' cursor keypad.

  ON KEY(12) GOSUB NumericPad     ' Trap LEFT key on
  KEY(12) ON                      ' the numeric keypad.

  DO
  LOOP UNTIL INKEY$ = "q"          ' Idle loop
  END

  CursorPad:
    PRINT "Pressed LEFT key on cursor keypad."
  RETURN

  NumericPad:
    PRINT "Pressed LEFT key on numeric keypad."
  RETURN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
$INCLUDE - a metacommand that causes QuickBASIC to read in and compile
           other BASIC source files at specific points during compilation

Syntax
  REM $INCLUDE: 'filespec'
  or
  ' $INCLUDE: 'filespec'

See Also  Metacommand Syntax
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
$STATIC and $DYNAMIC - metacommands that control the allocation of
                       dimensioned arrays

Syntax
  REM $STATIC
  or
  ' $STATIC

  REM $DYNAMIC
  or
  ' $DYNAMIC

See Also  Metacommand Syntax
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ - a function that returns a string containing the current date

Syntax
  DATE$
    ■ a ten-character string is returned, in the form
        mm-dd-yyyy
      mm is the month (01-12),
      dd is the day (01-31), and
      yyyy is the year (1980-2099)

See Also  DATE$ statement - which sets the date
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE (Non-BASIC) - 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])]
    ■ name is the name that will be used to call the procedure
    ■ CDECL, aliasname and parameterlist are Details

See Also  CALLS and CALL(Non-BASIC) statements - to see how to call the
                                                 non-BASIC procedure
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GET - a graphics statement that stores graphic images from the screen

Syntax
  GET [STEP](x1,y1)-[STEP](x2,y2),arrayname[(indices)]
    ■ (x1,y1) and (x2,y2) are numeric expressions that are the screen
      coordinates of diagonally opposite corners of the rectangle to store
    ■ STEP enables you to use relative screen coordinates
    ■ arrayname indicates the array where the image will be stored
    ■ indices enable you to start storing the image information in some
      array element other than the first one

See Also  PUT (Graphics)  SCREEN statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT # - a file I/O statement that reads data items from a sequential
          device or file and assigns them to variables
Syntax
  INPUT #filenumber, variablelist
    ■ filenumber is the number of an open sequential file
    ■ variablelist is one or more simple variable names, separated by
      commas, that will be assigned values from the file. Make sure
      the data type of each variable in the list matches the data type
      of the incoming data item.

See Also  INPUT$  LINE INPUT#
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY(n) - an event-trapping statement that start or stops trapping of
         specified keys
Syntax
  KEY(n) ON
  KEY(n) OFF
  KEY(n) STOP
    ■ KEY(n) ON statement enables soft-key or cursor-direction-key event
      trapping by an ON KEY statement.
    ■ 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  KEY - for information on assigning soft-key values
          to function keys.
          ON KEY(n)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT - a device I/O statement that inputs an entire line
             (up to 255 characters) to a string variable, without the
             use of delimiters
Syntax
  LINE INPUT[;] ["promptstring";] stringvariable

    ■ promptstring, a string constant, is displayed on the screen before
      input is accepted. You must explicitly include a '?' if you want one.
    ■ stringvariable will hold all characters input until the program
      operator presses a carriage return
    ■ [;] is a cursor control Detail

See Also  INPUT  INPUT$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT # - a file I/O statement that reads an entire line without
               delimiters from a sequential file to a string variable
Syntax
  LINE INPUT #filenumber,stringvariable
    ■ filenumber is the number of an open sequential file
    ■ stringvariable will hold all characters from the sequential file
      from the current position in the file up to, but not including, the
      next carriage-return-line-feed sequence. No carriage-return-line-feed
      sequences are ever input.

See Also  INPUT#  LINE INPUT  INPUT  INPUT$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ - a string-processing function that returns a substring of a string

Syntax
  MID$(stringexpression,start[,length])
    ■ stringexpression identifies the string the substring is to be
      extracted from
    ■ start, a numeric expression that has an integer value between
      1 and 32,767, specifies the starting character position of the
      substring
    ■ length can be omitted if you want all the characters to the right
      of start

See Also  MID$ statement  LEFT$  RIGHT$  LEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON ERROR - an error-trapping statement that enables error handling
           and specifies the first line of the error-handling routine
Syntax
  ON ERROR GOTO line
    ■ line is the line label or line number of the statement that you want
      to run next after an error occurs during program execution

See Also  RESUME  ERR  ERL  ERROR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON...GOSUB and ON...GOTO - control flow statements that branches to
                           one of several specified lines, depending on
                           the value of an expression
Syntax 1
  ON expression GOSUB line-label-list
Syntax 2
  ON expression GOTO line-label-list
    ■ expression, which will be rounded to an integer if necessary, is an
      index into the list of line labels and line numbers. See Details for
      what happens if the integer value is greater than the number of items
      in the list.
    ■ line-label-list is a set of program line labels and line numbers,
      separated by commas, that identify the branches to be taken. Line
      labels and line numbers can be used in the same list.
See Also  SELECT CASE - to see a more versatile way to code this type of
                          control flow structure
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON UEVENT GOSUB - an error-trapping statement that defines the
                  event-handler for a user-defined event

Syntax
  ON UEVENT GOSUB {linelabel | linenumber}
    ■ linelabel or linenumber is the first line of an event-handling
      subroutine
    ■ See Details for instructions on how to write the code
      for user-defined event-handler modules

See Also  UEVENT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN COM - a device I/O statement that opens and initializes a
           communications channel for I/O
Syntax
  OPEN "COMn: optlist1 optlist2" [FOR mode] AS [#]filenum [LEN=reclen]
    ■ n is either 1 or 2, and identifies the communications port to be opened
    ■ optlist1 has the following syntax
        [speed][,[parity][,[data][,[stop]]]]
      where the defaults are set for the transmission of text (rather than
      numeric) data. See Details if you are transmitting numeric data.
──────────────────────────────────────────────────────────────────────────────
speed   bits per second ("baud rate"),│ data  number of data bits per byte,
        default is 300                │       default is 7
parity  type of error checking,       │ stop  number of stop bits after each
        default is Even               │       data byte, default is 1
──────────────────────────────────────────────────────────────────────────────
    ■ optlist2 can specify up to ten other data communications handshaking
      parameters (see Details).
    ■ filenum, an integer between 1 and 255, is any file number not already
      assigned to an open file
    ■ mode and reclen are Details
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN - a device I/O function that reads the lightpen coordinates

Syntax
  PEN(n)
    ■ n, a numeric expression that has an integer value between 0 and 9,
      indicates what type of information you want returned by the function:
──────────────────────────────────────────────────────────────────────────────
0  whether pen was down since last    │ 4  last-known valid x-coordinate
   function call (-1 = yes, 0 = no)   │ 5  last-known valid y-coordinate
1  x-coordinate of last pen press     │ 6  character row of last pen press
2  y-coordinate of last pen press     │ 7  character column of last pen press
3  current pen switch status          │ 8  character row of last pen position
   (-1 = down, 0 = up)                │ 9  character column of last position
──────────────────────────────────────────────────────────────────────────────
See Also  PEN statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY - an event-trapping function that returns the number of notes
       currently in the background-music queue
Syntax
  PLAY(n)
    ■ n may have any value, it is not used by the PLAY function

See Also  ON PLAY(n)  PLAY  PLAY ON, PLAY OFF, PLAY STOP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY ON, PLAY OFF, and PLAY STOP - event-trapping statements that enable,
                                   disable, and suspend play event trapping
Syntax
  PLAY ON
  PLAY OFF
  PLAY STOP
    ■ PLAY ON enables play-event trapping by an ON PLAY statement.
    ■ PLAY OFF disables the event trap; even if an event takes place,
      it is not remembered.
    ■ PLAY STOP inhibits the event trap; if an event takes place, it is
      remembered and the ON PLAY event-trap will be executed as soon
      as PLAY ON is executed.

See Also  ON PLAY(n)  PLAY  PLAY function
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT USING - a device I/O statement that prints strings or numbers
              using a specified format
Syntax
  PRINT USING formatstring; expressionlist[{,|;}]
    ■ formatstring, a string-expression, specifies the format. Characters in
      formatstring have the following meaning:
───────────────────Characters Used to Format a Numeric Expression─────────────
 #    Digit position                     │ -     Placed after digit positions,
 .    Decimal point position             │       prints trailing sign for
 ,    Placed left of the decimal point,  │       negative numbers only
      prints a comma every third digit   │ $$    Prints leading $
 +    Position of number's sign          │ **    Fills leading spaces with *
^^^^  Prints number in exponential format│ **$   Combines ** and $
────────────────────Characters Used to Format a String Expression─────────────
 &    Prints entire string               │     Prints first 'n' characters,
 !    Prints only the first character    │       where n is the number of
      of the string                      │       blanks between slashes + 2
───────────Characters Used to Print Literal Characters from formatstring──────
 _    Prints the following formatting    │       Any character not in this
      character as a literal             │       table is printed as a literal

    ■ expressionlist contains the items to be printed
    ■ optional "," or ";" at the end of the expressionlist are cursor
      control Details
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT #, PRINT # USING - file I/O statements that write data to a
                         sequential file
PRINT # Syntax
  PRINT #filenumber, [USING formatstring;] expressionlist[{,|;}]
    ■ filenumber is the number of an open sequential file
    ■ expressionlist contains the items to be written to the file. If
      not used, a blank line is written to the file
PRINT # USING Syntax
  PRINT #filenumber, USING formatstring; expressionlist[{,|;}]
    ■ formatstring, a string-expression, specifies the exact format in
      which values are written to the file. Characters in formatstring
      have the following meaning:
───────────────────Characters Used to Format a Numeric Expression─────────────
 #    Digit position                     │ -     Placed after digit positions,
 .    Decimal point position             │       prints trailing sign for
 ,    Placed left of the decimal point,  │       negative numbers only
      prints a comma every third digit   │ $$    Prints leading $
 +    Position of number's sign          │ **    Fills leading spaces with *
^^^^  Prints number in exponential format│ **$   Combines ** and $
────────────────────Characters Used to Format a String Expression─────────────
 &    Prints entire string               │     Prints first 'n' characters,
 !    Prints only the first character    │       where n is the number of
      of the string                      │       blanks between slashes + 2
───────────Characters Used to Print Literal Characters from formatstring──────
 _    Prints the following formatting    │       Any character not in this
      character as a literal             │       table is printed as a literal

See Also  OPEN  WRITE #
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT - a graphics statement that places a graphic image obtained
      by a GET statement onto the screen
Syntax
  PUT [STEP](x, y),arrayname[(indices)][,actionverb]
    ■ (x,y) are the screen coordinates of the upper-left corner of the
      displayed image
    ■ STEP enables you to use relative screen coordinates
    ■ arrayname indicates the array where the image is stored
    ■ indices enable you to start retrieving the image information from
      an array element other than the first one
    ■ actionverb enables you to display the image with special effects,
      and must be one of the following keywords (XOR is the default):

PSET    Draws image as stored, wiping │ XOR   Reverses points in the image
        out any existing image        │       with those in existing image
PRESET  Draws image in reverse colors │       or with background.
        wiping out any existing image │       Used in successive PUT
AND     Merges stored image with      │       statements, with time delays,
        existing image                │       causes stored image to appear
OR      Superimposes stored image on  │       and disappear. With movement
        existing image                │       of image, animation is achieved

See also  GET (Graphics)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SCREEN - a graphics function that reads a character's ASCII value
         or its color from a specified screen location
Syntax
  SCREEN (row,column[,colorflag])
    ■ row is the row number of the screen location
    ■ column is the column number of the screen location
    ■ If colorflag is not used, or has a value of 0, the character's ASCII
      code is returned. Any non-zero numeric value causes the number of
      the color.

See Also  SCREEN statement  ASCII Code Table  COLOR  PALETTE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK - a file I/O  function that returns the current file position

Syntax
  SEEK(filenumber)
    ■ filenumber is the number of an open random-access, sequential, or
      binary file. If random-access, the number returned by the SEEK
      function is a relative record number. If sequential or binary,
      it is a relative byte number

See Also  OPEN  GET(File I/O)  PUT(File I/O)  SEEK statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRIG - a device I/O function that returns the status of a
        specified joystick trigger
Syntax
  STRIG(n)
    ■ n, a numeric expression that has an integer value between 0 and 7,
      indicates what type of information you want returned by the function:
──────────────────────────────────────────────────────────────────────────────
Argument  Button   Joystick   Value Returned
0         lower    A          -1 = pressed since last STRIG(0) call, 0 = not
1         lower    A          -1 = currently down, 0 = not
2         lower    B          -1 = pressed since last STRIG(2) call, 0 = not
3         lower    B          -1 = currently down, 0 = not
4         upper    A          -1 = pressed since last STRIG(4) call, 0 = not
5         upper    A          -1 = currently down, 0 = not
6         upper    B          -1 = pressed since last STRIG(6) call, 0 = not
7         upper    B          -1 = currently down, 0 = not
──────────────────────────────────────────────────────────────────────────────
See Also  ON STRIG(n)  STRIG statements
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ - a function that returns the current time from the operating system

Syntax
  TIME$
    ■ an eight-character string is returned, in the form
        hh:mm:ss
      hh is the hour (00-23),
      mm is the minute (00-59), and
      ss is the second (00-59)

See Also  TIME$ statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER - a function that returns the number of seconds elapsed since
        midnight
Syntax
  TIMER
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VIEW PRINT - a device I/O statement that sets the boundaries
             of the screen text viewport
Syntax
  VIEW PRINT [topline TO bottomline]
    ■ Using no arguments causes the screen text viewport to be the
      entire screen.
    ■ topline, a numeric expression that has an integer value, is the
      top of the new text viewport
    ■ bottomline is the bottom of the new text viewport

See Also  SCREEN statement  WIDTH  CLS  LOCATE  PRINT
          SCREEN function
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE - a device I/O statement that sends data to the screen

Syntax
  WRITE [expressionlist]
    ■ If expressionlist is omitted, a blank line is written
    ■ expressionlist contains one or more expressions to be written,
      separated by commas

See Also  PRINT  PRINT USING
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
$INCLUDE Metacommand Details

The $INCLUDE metacommand instructs the compiler to temporarily switch
from processing one file and instead to read program statements from
the BASIC file named in the argument. When the end of the included
file is reached, the compiler returns to processing the original file.
Because compilation begins with the line immediately following the
line in which $INCLUDE occurred, $INCLUDE should be the last statement
on a line. The following statement is correct:

  DEFINT I-N   ' $INCLUDE: 'COMMON.BAS'

There are two restrictions on using Include files:
  ■ Included files must not contain SUB or GOTO statement
  ■ Included files created with BASICA must be saved with the ,A option.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

The CALL ABSOLUTE statement programming example uses a $INCLUDE metacommand.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
$STATIC and $DYNAMIC Metacommand Details

The $STATIC and $DYNAMIC metacommands tell the compiler how to allocate
memory for arrays. Neither of these metacommands takes an argument:

  'Make all arrays dynamic.
  '$DYNAMIC

$STATIC sets aside storage for arrays during compilation. When the
$STATIC metacommand is used, the ERASE statement reinitializes all array
values to zero (numeric arrays) or the null string (string arrays)
but does not remove the array. The REDIM statement has no effect
on $STATIC arrays.

$DYNAMIC allocates storage for arrays while the program is running.
This means that the ERASE statement removes the array and frees
the memory it took for other uses. You can also use the REDIM statement
to change the size of a $DYNAMIC array.

The $STATIC and $DYNAMIC metacommands affect all arrays except implicitly
dimensioned arrays (arrays not declared in a DIM statement). Implicitly
dimensioned arrays are always allocated as if $STATIC had been used.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the ERASE statement programming example, which demonstrates uses
of the $DYNAMIC and $STATIC commands.
Metacommand Syntax

Metacommands begin with a dollar sign ($) and are always enclosed
in a program comment. More than one metacommand can be given in one
comment. Multiple metacommands are separated by white-space characters:
space, tab, or line feed. Metacommands that take arguments have a
colon between the metacommand and the argument:

  REM $METACOMMAND [:argument]

String arguments must be enclosed in single quotation marks. White-space
characters between elements of a metacommand are ignored. The following
are both valid forms for metacommands:

  REM $STATIC $INCLUDE:  'datadefs.bi'
  REM   $STATIC    $INCLUDE :  'datadefs.bi'
  ' $STATIC $INCLUDE: 'datadefs.bi'
  '     $STATIC    $INCLUDE :  'datadefs.bi'

Note that no spaces appear between the dollar sign and the rest of
the metacommand.

If you want to refer to a metacommand in a description but do not
want it to execute, place a character that is not a tab or space
before the first dollar sign on the line. For example, on the
following line both metacommands are ignored:

  REM x$STATIC $INCLUDE:  'datadefs.bi'
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ABS Function Details

Syntax
  ABS(numeric-expression)

The absolute value function returns the unsigned magnitude of its
argument. For example, ABS(-1) and ABS(1) are both 1.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ABS Function Programming 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
Precision = .0000001#
CLS                               'Clear the screen
INPUT "Enter a value: ", Value    'Prompt for input
'  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
PRINT "The cube root is "; X

Sample Output

Enter a value: 27
The cube root is  2.999999972060323
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ASC Function Details

Syntax
  ASC(stringexpression)

If stringexpression is null, ASC produces a run-time error message
"Illegal function call."
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ASC Function Programming 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
CLS                             'Clear the screen
INPUT "Enter a name: ",Nm$      'Prompt for input
TmpVal = 0
FOR I=1 TO LEN(Nm$)
    ' Convert the string to a number by summing the values
    ' of individual letters.
    TmpVal = TmpVal + ASC(MID$(Nm$,I,1))
NEXT I
    ' Divide the sum by the size of the table.
    HashValue = TmpVal MOD HASHTABSIZE
PRINT "The hash value is "; HashValue

Sample Output

Enter a name: Bafflegab
The hash value is  66
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ATN Function Details

Syntax
  ATN(numeric-expression)

The numeric-expression can be of any numeric type.

ATN is evaluated by default in single precision. If numeric-expression is
a double-precision value, ATN is evaluated in double precision.

The result is given in radians and is in the range -π/2 to π/2 radians,
where π = 3.141593. π/2 radians equals 90 degrees.

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

To convert a radian value to degrees, multiply it by 57.2958.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ATN Function Programming Example

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

CONST PI=3.141592653
PRINT ATN(TAN(PI/4.0)), PI/4.0

Sample Output

 .78539816325  .78539816325
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BEEP Statement Details

Syntax
  BEEP

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

PRINT CHR$(7)
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BEEP Statement Programming Example

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

CLS                ' Clear the screen
DO
   INPUT "Hear a beep (Y or N)"; Response$
   R$ = UCASE$ (MID$ (Response$,1,1))
   IF R$ <> "Y" OR R$ = "N" THEN EXIT DO
   BEEP
LOOP
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BLOAD Statement Details

Syntax
  BLOAD filespec [,offset]

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BLOAD Statement Programming Example

This example uses BLOAD to retrieve and display a drawing of a magenta cube
inside a box. The BSAVE statement programming example shows how the drawing
was created and saved on disk in a file named MAGCUBE.GRH.

'*** Programming example using BLOAD ***
' You must create the file MAGCUBE.GRH using the BSAVE statement
' programming example before you can run this program. This program
' uses MAGCUBE.GRH.
'
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
' Set segment to the array Cube's segment and load
' the graphic file into Cube.
DEF SEG = VARSEG(Cube(1))
BLOAD "MAGCUBE.GRH", VARPTR(Cube(1))
DEF SEG               ' Restore default BASIC segment.
' Put the drawing on the screen.
PUT (80, 10), Cube
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BSAVE Statement Details

Syntax
  BSAVE filespec,offset,length

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BSAVE Statement Programming Example

This example draws a magenta cube inside a white box and then uses BSAVE
to store the drawing in the file MAGCUBE.GRH. The BLOAD statement example
program shows how you can retrieve and display the drawing after you create
it.

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
' Set segment to the array Cube's segment and store the drawing
' in the file MAGCUBE.GRH. Note: 2700 is the number of bytes
' in Cube (4 bytes per array element * 675).
DEF SEG = VARSEG(Cube(1))
BSAVE "MAGCUBE.GRH", VARPTR(Cube(1)), 2700
DEF SEG                 ' Restore default BASIC segment.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL (BASIC Procedures) Statement Details

Syntax
  CALL name[(argumentlist)]

  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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL (BASIC Procedures) Statement Programming Example

CALL_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the CALL statement. To look at the program in the View window and,
optionally, to run it, load CALL_EX.BAS using the File menu's Open Program
command.

The program 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).
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHAIN Statement Details

Syntax
  CHAIN filespec

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.

Difference 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

The COMMON statement programming example illustrates the use of the
CHAIN statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHDIR Statement Details

Syntax
  CHDIR pathspec

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.

  Note: 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"
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHDIR Statement Programming Example

Example 1

' Makes HOMESALES the current directory on the default
' drive.
CHDIR "HOMESALES"

Example 2

' Changes the current directory to USERS on drive B; it does
' not, however, change the default drive to B.
CHDIR "B:USERS"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHR$ Function Details

Syntax
  CHR$(code)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHR$ Function Programming Example

CHR_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the CHR$ function. To look at the program in the View window and,
optionally, to run it, load CHR_EX.BAS using the File menu's Open Program
command.

The program uses CHR$ to display graphics characters in the extended
character set, and uses these characters to draw boxes on the screen.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CINT Function Details

Syntax
  CINT(numeric-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CINT Function Programming 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"

Sample Output

Angle in radians = 1.5708
Angle equals 90 degrees 0 minutes
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CIRCLE Statement Details

Syntax
  CIRCLE [STEP] (x,y),radius[,[color][,[start][,[end][,aspect]]]]

  Argument     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 circle
               or ellipse.
  radius       The radius of the circle or ellipse in the current
               coordinate system.
  color        The attribute of the desired color. The default color is
               the foreground color. See the COLOR statement details and
               the SCREEN statement details for more information on
               how to specify a color in different display screen modes.
  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 -2PI radians to 2PI radians, where
               PI= 3.141593. The default value for start is 0 radians.
               The default value for end is 2PI radians.

               If start or end is negative, then CIRCLE draws a
               radius to that point on the arc and treats the angle
               as if 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
               2PI 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 resolution.
               For example, in screen mode 1, where the resolution
               is 320 x 200, the default for aspect would be:

                 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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CIRCLE Statement Programming 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$=""
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
Details

Syntax
  CLEAR [,,stack]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLEAR Statement Programming Example

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

CLEAR ,,2000
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLNG Function Details

Syntax
  CLNG(numeric-expression)

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."
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLNG Function Programming Example

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

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

Sample Output

 32767  32768
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLOSE Statement Details

Syntax
  CLOSE [[#]filenumber[,[#] filenumber]...]

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 close all files
automatically.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

The CALL statement programming example illustrates a use of the CLOSE
statement.
  QuickSCREEN      ◄Details►     Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLS Command Details

Syntax
   CLS [{0|1|2}]

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLS Statement Programming 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$ <> ""
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COLOR Statement Details

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 11-13

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:

  Mode         Description

  SCREEN 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 (EGA), the IBM
               Video Graphics Array adapter (VGA), and the IBM
               Multicolor Graphics Array adapter (MCGA) do not
               support the border argument.

  SCREEN 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.
               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.

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

  SCREEN 7,    In these modes, no border color can be specified.
         8,    the graphics background is given by the background
         9,    color number, which must be in the range of valid
         10    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.

  SCREEN 11    Use the PALETTE statement to set color in screen
               mode 11. An "Illegal function call" message results if
               COLOR is used in this mode.

  SCREEN 12,   No background color can be specified in these modes.
         13    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.

Arguments 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 for more details.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COLOR Statement Programming Example

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

'*** Programming example for COLOR statement***
SCREEN 0            'text mode only
'foreground = 1 (blue), background = 2 (green), border = 3 (cyan)
'EGA and VGA boards do not support the border argument
COLOR  1, 2, 3
CLS
LOCATE 12,25: PRINT "Press any key to continue..."
DO
LOOP WHILE INKEY$ = ""
SCREEN 1            'set screen to 320 x 200 graphics
'background = 1 (blue), foreground = even palette number (red, green, yellow)
COLOR  1, 0
LINE (20, 20) - (300, 180), 3, B       'draw a box
LOCATE 12,7: PRINT "Press any key to continue..."
DO
LOOP WHILE INKEY$ = ""
'background = 2 (green), foreground = odd palette (white, magenta, cyan)
COLOR  2, 1
LINE (20, 20) - (300, 180), 3, B       'draw a box
LOCATE 12,7: PRINT "Press any key to continue..."
DO
LOOP WHILE INKEY$ = ""
SCREEN 0            'set screen to text mode
'foreground = 7 (white), background = 0 (black), border = 0 (black)
COLOR 7, 0, 0
CLS
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COM(n) Statement Details

Syntax

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

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There are no programming examples for the COM(n) statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMAND$ Function Details

Syntax
  COMMAND$

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMAND$ Function Programming Example

CMD_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the COMMAND$ function. To look at the program in the View window and,
optionally, to run it, load CMD_EX.BAS using the File menu's Open Program
command.

The program 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.

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

Sample Output

Number of arguments =  6
Arguments are:
ONE
TWO
THREE
FOUR
FIVE
SIX
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMON Statement Details

Syntax
  COMMON [SHARED][/blockname/] variablelist

  Argument       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.

  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.

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 mismatched COMMON statements is to place
COMMON declarations in a single "include" file and use the $INCLUDE
metacommand in each program.

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 fragment, 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)
    .
    .
    .
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
    .
    .
    .
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.'
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMON Statement Programming Example

COM1_EX.BAS and COM2_EX.BAS are two program files that illustrate
the use of the COMMON statement. They are in the subdirectory ADVR_EX.
To look at the program text in the View window and, optionally, to run the
programs, load COM1_EX.BAS using the File menu Open Program command.
Be sure COM2_EX.BAS is in the current working directory.

The COMMON statement is used 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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CONST Statement Details

Syntax
  CONST constantname = expression [,constantname = expression]...

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CONST Statement Programming Example

This example uses the CONST statement to declare symbolic constants
for the ASCII values of nonprinting characters such as tab and
line feed. Constants also make programs easier to modify.

  Tip: You must supply a text file when you run this example.
       Use a text file you have already created, create a file
       with a text editor, or specify the README.DOC text file.

' 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

CLS    ' Clear screen
' 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COS Function Details

Syntax
  COS(numeric-expression)

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.

To convert a radian value to degrees, multiply it by 57.2958.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COS Function Programming Example

The following program plots the graph of the polar equation r = nΘ for
values of n from 0.1-1.1. This program uses the conversion factors
x = cos(Θ) and y = sin(Θ) 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSNG Function Details

Syntax
  CSNG(numeric-expression)

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

CSNG rounds the value, if necessary, before converting it.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSNG Function Programming 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#)

Sample Output

975.3421115  975.3421  975.3421555  975.3422
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CDBL Function Details

Syntax
  CDBL(numeric-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CDBL Programming 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#

Sample Output

 .7777778
 .7777777910232544
 .7777777910232544
 .7777777777777778
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSRLIN Function Details

Syntax
  CSRLIN

To return the current column position, use the POS function.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSRLIN Function Programming Example

CSR_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the CSRLIN function. To look at the program in the View window and,
optionally, to run it, load CSR_EX.BAS using the File menu Open Program
command.

The program uses a SUB that prints a message on the screen without
disturbing the current cursor position.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVSMBF and CVDMBF Function Details

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

The CVSMBF and CVDMBF functions help you 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 a 4-byte-string containing a Microsoft Binary
            format number to a single-precision IEEE-format number.

  CVDMBF    Converts an 8-byte-string containing a Microsoft Binary
            format number to a double-precision IEEE-format number.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVSMBF Function Programming 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
'********************************************************************
' This part of the program is an insert whose only function is to
' create a random-access file to be used by the second part of the
' program, which demonstrates the CVSMBF function
'********************************************************************
OPEN "TESTDAT1.DAT" FOR RANDOM AS #1 LEN = LEN(Rec)
CLS
RESTORE
READ NameField$, Score$
I = 0
DO WHILE UCASE$(NameField$) <> "END"
   I = I + 1
   Rec.NameField = NameField$
   Rec.Score = Score$
   PUT #1, I, Rec
   READ NameField$, Score$
   IF NameField$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
  DATA "John Simmons","100"
  DATA "Allie Simpson","95"
  DATA "Tom Tucker","72"
  DATA "Walt Wagner","90"
  DATA "Mel Zucker","92"
  DATA "END","0"
'********************************************************************
' This part of the program demonstrates the CVSMBF function
'********************************************************************
' Open the file for input.
OPEN "TESTDAT1.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
KILL "TESTDAT1.DAT"
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVI, CVS, CVL, and CVD Functions Details

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

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 a 2-byte-string created with MKI$ back to an
            an integer.

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

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

  CVD       Converts an 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVI, CVS, CVL, and CVD Functions Programming Example

The following program illustrates the use of MKS$ and CVS. If you run
this program, you will be prompted to enter an "account #." The account
numbers in the sample data file ACCOUNT.INF are 1, 2, 3, 4, and 5.

After you enter an account number, the program gives you a chance to
update the account balance.

' *** Example program that uses the CVS function ***
'
' Define a user type for the data records.
TYPE Buffer
   AccName AS STRING * 25
   Check   AS STRING * 4
END TYPE
' Define a variable of the variable type
DIM BankBuffer AS Buffer
OPEN "ACCOUNT.INF" FOR RANDOM AS #1 LEN = 29
CLS
RESTORE
READ AccName$, Check
I = 0
DO WHILE UCASE$(AccName$) <> "END"
   I = I + 1
   BankBuffer.AccName = AccName$
   BankBuffer.Check = MKS$(Check)
   PUT #1, I, BankBuffer
   READ AccName$, Check$
   IF AccName$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
   DATA "Bob Hartzell", 300
   DATA "Alice Provan", 150
   DATA "Alex Landow", 75
   DATA "Walt Riley", 50
   DATA "Georgette Gump", 25
   DATA "END", 0

'*******************************************************************
OPEN "ACCOUNT.INF" FOR RANDOM AS #2 LEN = 29
FIELD #2, 25 AS AccName$, 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 "; AccName$
      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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATA Statement Details

Syntax
  DATA  constant[,constant]...

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.

  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 ("").

You may use any number of DATA statements.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATA Statement Programming Examples

Example 1

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$

Example 1 Sample Output

Today is September 21, 1988

Example 2

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

Example 2 Sample Output

abc                     def
 1           0           2
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ Function Details

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).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ Function Programming Example

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

PRINT DATE$

Sample Output

 09-21-1988
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ Statement Details

Syntax
  DATE$ = stringexpression

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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ Statement Programming Example

This example prompts you to supply the month, date, and year, then resets
the system date on your computer.

'  Note: Run this program with caution. If you change the system date,
'        any files you create or revise will be stamped with the new date.
'        Make sure to reset the system date to the current 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$
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE (BASIC Procedure) Statement Details

Syntax
  DECLARE {FUNCTION | SUB } name [([parameterlist])]

  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 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.

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 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE (BASIC Procedure) Statement Programming Example

DECL_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the DECLARE statement for BASIC procedures. To look at the program in the
View window and, optionally, to run it, load the program using the File
menu's Open Program command.

In the program, use of the DECLARE statement allows a SUB to be invoked
without using the CALL keyword.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE (Non-BASIC Procedure) Statement Details

Syntax 1
  DECLARE FUNCTION name [CDECL] [ALIAS "aliasname"][([parameterlist])]

Syntax 2
  DECLARE SUB name [CDECL] [ALIAS "aliasname"][([parameterlist])]

  Argument       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 like 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 clause in the DECLARE, the
                     type-declaration character is removed from the name
                     of the procedure, 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.

  parameterlist  Lists the variables to be passed to the called procedure
                 and 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 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 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.

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE (Non-BASIC Procedure) Statement Programming 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.

'*** Programming example: DECLARE (Non-BASIC procedure) ***
'
' Do not attempt to run this program unless you have already
' separately compiled the C function and placed it in a
' Quick library or linked it to the BASIC program.
'
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);
}
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF FN Statement Details

Single-Line Syntax
  DEF FNname[(parameterlist)] = expression

Block Syntax
  DEF FNname[(parameterlist)]
     [statements]
  FNname = expression
     [statements]
  END DEF

  Argument        Description
  name            legal variable name, up to 40 characters long. 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."

  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.

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 FUNCTION statement 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 the error message "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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF FN Statement Programming Example

DEFFN_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the DEF FN statement. To look at the program in the View window and,
optionally, to run it, load the program using the File menu's Open Program
command.

The program uses a DEF FN function to calculate the factorial of an input
number (for example, the factorial of 3 is 3*2*1).
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF SEG Statement Details

Syntax
  DEF SEG [=address]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF SEG Statement Programming Example

DEFSG_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the DEF SEG statement. To look at the program in the View window and,
optionally, to run it, load DEFSG_EX.BAS using the File menu's Open Program
command.

The program uses DEF SEG, PEEK, and POKE to turn the CAPSLOCK key on and
off.

  Note: The program contains hardware-specific instructions. It works
        correctly on IBM PC, XT, and AT computers.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEFtype Statement Details

Syntax
  DEFINT letterrange [,letterrange]...
  DEFSNG letterrange [,letterrange]...
  DEFDBL letterrange [,letterrange]...
  DEFLNG letterrange [,letterrange]...
  DEFSTR letterrange [,letterrange]...

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEFtype Statement Programming Example

See the ABS function programming example.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DIM Statement Details

Syntax
  DIM [SHARED] variable[(subscripts)][AS type]
               [,variable[(subscripts)][AS type]...

  Argument     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.

  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, the following 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

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DIM Statement Programming 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

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WHILE...WEND Statement Details

Syntax
  WHILE condition
    [statements]
  WEND

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WHILE...WEND Statement Programming Example

This example performs a bubble sort on the array A$. Assigning the
variable Exchange a nonzero value makes it true, forcing 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, Exchange is false (equal to zero), and the program continues
execution with the line following WEND.

' Bubble sort of array A$.
CONST FALSE=0, TRUE=NOT FALSE
DIM A$(4)
A$(1) = "New York"
A$(2) = "Boston"
A$(3) = "Chicago"
A$(4) = "Seattle"
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
CLS
FOR I = 1 TO 4
   PRINT A$(I)
NEXT I
END

Sample Output
Boston
Chicago
New York
Seattle
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DO...LOOP Statement Details

Syntax 1
  DO [{WHILE | UNTIL} booleanexpression]
    [statementblock]
  LOOP

Syntax 2
  DO
    [statementblock]
  LOOP [{WHILE | UNTIL} booleanexpression]

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DO...LOOP Statement Programming Examples

Following are four examples. The first two examples show you how
placement of the condition affects the number of times the block
of statements is executed. The third example shows how a loop can
be used to pause a program until the user presses a key. The fourth
example illustrates testing at the end of a loop and presents
a sort subprogram where an ending test is appropriate.

DO...LOOP Programming Example 1

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

Example 1 Sample Output

Value of I at beginning of loop is  10
Value of I at end of loop is  10

DO...LOOP Programming Example 2

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

Example 2 Sample Output

Value of I at beginning of loop is  10
Value of I at end of loop is 11

DO...LOOP Programming Example 3

In the following example, the DO...LOOP continues testing the length
of Choice$ at the bottom of the loop.  When the user presses a key,
the length of Choice$ becomes greater than zero and the loop terminates.

' DO...LOOP with test at the bottom of the loop.
DO
   Choice$ = INKEY$
LOOP WHILE Choice$ = ""

DO...LOOP Programming Example 4

The following sort program 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.

' Set up a special value to indicate no exchanges.
'
CONST NOEXCH = -1
DIM Exes(12)
FOR I = 1 TO 12
   Exes(I) = 13 - I
NEXT I
Limit = 12
CLS                                  'Clear the screen
PRINT "This is the list of numbers to sort:"
FOR I = 1 TO 12
   PRINT Exes(I);
NEXT I
LOCATE 4,1: INPUT "Press any key to continue", Gar$
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.
'
PRINT
PRINT "Sorting is completed. This is the sorted list:"
FOR I = 1 TO 12
   PRINT Exes(I);
NEXT I
END

Sample Output

This is the list of numbers to sort:
 12  11  10  9  8  7  6  5  4  3  2  1

Press any key to continue

This is the sorted list:
 1  2  3  4  5  6  7  8  9  10  11  12
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DRAW Statement Details

Syntax
  DRAW stringexpression

The DRAW statement combines many of the capabilities of the other
graphics statements into a graphics macro language. 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.

There are three types of macro commands:

  cursor-movement commands
  angle, color, and scale factor commands
  X, the substring command

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, while the second works only within the
environment.

  DRAW "X" + VARPTR$(A$)
  DRAW "XA$"
  Details   ◄Movement►   Angle, Scale, Rotation   X Substrings
──────────────────────────────────────────────────────────────────────────────
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. If no argument is supplied, the cursor is moved one unit.
(S is described in "Angle, Color, and Scale-Factor Commands.")

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.
  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.
  Details   ◄Angle, Color, Scale►   Movement   X Substrings
──────────────────────────────────────────────────────────────────────────────
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
                                FOR D=0 TO 360  STEP 10
                                   DRAW "TA="+VARPTR$(D)+"NU50"
                                NEXT D

  C n                         Set color to n. See the 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, bordercolor   The paintcolor is the paint color for a
                              figure's 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.
  Details   ◄X Substrings►   Movement   Angle, Color Scale
──────────────────────────────────────────────────────────────────────────────
  Substring Command    Description
  X stringexpression   Execute substring. This 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$(string-expression)

                       form of this command. This is different than
                       the BASICA form of the command.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DRAW Statement Programming Examples

Example 1

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.

Example 2

The following example shows how to use the M macro command:
    ■ with absolute and relative movement
    ■ with string- and numeric-variable arguments

SCREEN 2
PRINT "Press any key to continue..."
'Absolute movement
DRAW "M 50,80"
DRAW "M 80,50"
LOCATE 2, 30: PRINT "Absolute movement"
DO
LOOP WHILE INKEY$ = ""
'Relative movement
DRAW "M+40,-20"
DRAW "M-40,-20"
DRAW "M-40,+20"
DRAW "M+40,+20"
LOCATE 3, 30: PRINT "Relative movement"
DO
LOOP WHILE INKEY$ = ""
'Using a string variable.
X$ = "400": Y$ = "190"
DRAW "M" + X$ + "," + Y$
LOCATE 4, 30: PRINT "String variable"
DO
LOOP WHILE INKEY$ = ""
'Using numeric variables (note the two "=" signs).
A = 300: B = 120
DRAW "M=" + VARPTR$(A) + ",=" + VARPTR$(B)
LOCATE 5, 30: PRINT "Numeric variables"

Example 3

DRAW_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the DRAW statement. To look at the program in the View window and,
optionally, to run it, load DRAW_EX.BAS using the File menu's Open Program
command.

The program draws a clock on the screen using the TIME$ function.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
END Statement Details

Syntax
  END [{DEF | FUNCTION | IF | SELECT | SUB | TYPE}]

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
END Statement Programming Example

These examples show how to use END IF and END SELECT forms of the
END statement to terminate IF...THEN...ELSE and SELECT CASE blocks.

Here is an example of using END IF with a block IF...THEN...ELSE
for a multiple-choice decision:

  INPUT X
  IF X = 1 THEN
    PRINT "one"
  ELSEIF X = 2 THEN
    PRINT "two"
  ELSEIF X = 3 THEN
    PRINT "three"
  ELSE
    PRINT "must be integer from 1-3"
  END IF

This example uses the SELECT CASE structure to do the same thing:

  INPUT X
  SELECT CASE X
    CASE 1
      PRINT "one"
    CASE 2
      PRINT "two"
    CASE 3
      PRINT "three"
    CASE ELSE
      PRINT "must be integer from 1-3"
  END SELECT
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON Statement Details

Syntax
  ENVIRON stringexpression

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 semi-colon (";"), 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON Statement Programming Example

This example uses the ENVIRON statement to change the setting of the PATH
environment variable for the current process to the sales and accounting
directories on the A: drive:

' Change value of PATH environment variable.
ENVIRON "PATH=A:SALES;A:\ACCOUNTING"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON$ Function Details

Syntax
  ENVIRON$ (environmentstring)
  ENVIRON$ (n)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON$ Function Programming Example

This example uses the ENVIRON$ function to print the current settings
in the environment-string table:

CLS      ' Clear screen
I = 1
DO WHILE ENVIRON$(I) <> ""
    PRINT ENVIRON$(I)
    I = I + 1
LOOP

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EOF Function Details

Syntax
  EOF(filenumber)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EOF Function Programming Example

This example reads single-precision values from the file DATA.IN into an
array M using a DO LOOP. The loop uses the EOF function to signal the
end of the file. A second DO LOOP displays the contents of M to confirm
that it contains the values from DATA.IN.

This example will not run without a DATA.IN data input file.

DIM M(0 TO 2000)

OPEN "DATA.IN" FOR INPUT AS 1
C = 0
DO WHILE NOT EOF(1) AND C <= 2000
      INPUT #1, M(C)
      C = C + 1
LOOP

CLS    ' Clear screen
D = 0
DO WHILE D < C
      PRINT M(D)
      D = D + 1
LOOP

  Tip: Run the example with a simple DATA.IN data file you create
       with a text editor. For example, create a one-line DATA.IN file with
       the following sequence of numbers:

       10 20 30 40 50 60 70 80 90

       Then run the example program to produce the following sample output.

Sample Output

10
20
30
40
50
60
70
80
90
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERASE Statement Details

Syntax
  ERASE arrayname [,arrayname...]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERASE Statement Programming Example

This example 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERDEV and ERDEV$ Function Details

Syntax
  ERDEV
  ERDEV$

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. ERDEV$ will contain the 8-byte character device name if the
error was on a character device, such as a printer. It will contain the
2-byte block name (A:, B:, etc.) if the device was not a character device.

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 DOS Programmer's Reference for more information about
device-attribute words.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERDEV and ERDEV$ Function Programming Example

This example prints the values of ERDEV and ERDEV$ after the program
generates an error attempting to open the file A:JUNK.DATA. Press
the F4 function key to view the program output.

DEFINT A-Z

' Indicate first line of error handler.
ON ERROR GOTO 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

Sample Output

Running the program with drive A unlatched produces the following
output (2 is the DOS error code for "Drive not ready"):

ERDEV value is  2
Device name is A:
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERL and ERR Function Details

Syntax
  ERR
  ERL

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

The ON ERROR statement programming example uses the ERR function.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERROR Statement Details

Syntax
  ERROR integerexpression

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERROR Statement Programming Example

This example uses an ERROR statement in an error-handling
routine, Handler, to trap a user input error.

  Tip:  You must supply a text file when you run this example.
        Use a text file you have already created, create a file
        with a text editor, or specify the README.DOC text file.

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
    'If program generates run-time error for "file not found,"
    'a special message is printed and the user is prompted to
    'enter a new file specification or end the program.
    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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXIT Statement Details

Syntax
  EXIT {DEF | DO | FOR | FUNCTION | SUB}

  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.

  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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXIT Statement Programming Example

This subprogram is an extended RTRIM$ function 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 the EXIT
FOR statement to jump out of the loop when the first printing character is
found.

See the STATIC statement examples for an example of using the EXIT SUB
statement.
                                ----- Note -----
Do not try to run this subprogram without a main program.
                                ----------------

' 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXP Function Details

Syntax
  EXP(numeric-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXP Function Programming Example

This example uses the EXP function to calculate the growth of a bacterial
colony over a 15-day period. The program prompts you for an initial
population and the rate of growth.

CLS    ' Clear screen
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

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIELD Statement Details

Syntax
  FIELD [#]filenumber, fieldwidth AS stringvariable
                     [,fieldwidth AS stringvariable] ...

  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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIELD Statement Programming 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.

' Example program for the FIELD statement
TYPE Buffer
   FuName AS STRING * 25
   Addr   AS STRING * 25
   City   AS STRING * 10
   State  AS STRING * 2
   Zip    AS STRING * 5
END TYPE
DIM RecBuffer AS Buffer
'********************************************************************
' NOTE: This part of the program creates a random-access
'       file for use by the second part of the program, which
'       demonstrates the FIELD statement
'********************************************************************
OPEN "MAILLIST.DAT" FOR RANDOM AS #1 LEN = LEN(RecBuffer)
CLS
RESTORE
READ FuName$, Addr$, City$, State$, Zip$
I = 0
DO WHILE UCASE$(FuName$) <> "END"
   I = I + 1
   RecBuffer.FuName = FuName$
   RecBuffer.Addr = Addr$
   RecBuffer.City = City$
   RecBuffer.State = State$
   RecBuffer.Zip = Zip$
   PUT #1, I, RecBuffer
   READ FuName$, Addr$, City$, State$, Zip$
   IF FuName$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
   DATA "Bob Hartzell","1200 Liberty St.","Bow","WA","98232"
   DATA "Alice Provan","123 B St.","Bellevue","WA","98005"
   DATA "Alex Landow","14900 123rd","Bothell","WA","98011"
   DATA "Walt Riley","33 Minnow Lake Road","Lyman","WA","98263"
   DATA "Georgette Gump","400 15th W.","Bellevue","WA","98007"
   DATA "END",0,0,0,0,0
'*********************************************************************
'This part of the program demonstrates the use of the FIELD statement
'*********************************************************************
' Define field and record lengths with constants.
CONST FU = 25, AD = 25, CT = 10, ST = 2, ZP = 5
CONST RECLEN = FU + AD + CT + ST + ZP
'
OPEN "MAILLIST.DAT" FOR RANDOM AS #1 LEN = RECLEN
FIELD #1, FU AS FuName$, AD AS Addr$, CT AS City$, ST AS State$, ZP AS Zip$
FIELD #1, RECLEN AS Plist$

GET #1, 1
' Read the file, looking for zip codes in the range 98000 to 98015.
DO WHILE NOT EOF(1)
   Zcheck$ = Zip$
   IF (Zcheck$ >= "98000" AND Zcheck$ <= "98015") THEN
      Info$ = Plist$
      PRINT LEFT$(Info$, 25)
      PRINT MID$(Info$, 26, 25)
      PRINT RIGHT$(Info$, 17)
      PRINT
   END IF
   GET #1
LOOP
CLOSE #1
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILEATTR Function Details

Syntax
  FILEATTR(filenumber,attribute)

  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.

The table below lists the return values and corresponding file modes
when the value of attribute is 1.

  Return Value   Mode
   1             INPUT
   2             OUTPUT
   4             RANDOM
   8             APPEND
  32             BINARY
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILEATTR Function Programming 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

Sample Output

Number Handle Mode
  1       5    8
  2       6    4
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILES Statement Details

Syntax
  FILES [filespec]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILES Statement Programming Examples

The following statements illustrate the use of FILES.
                                ----- Note -----
  Execution halts if you try to run this example without a disk in drive B,
  or if the specified files cannot be found.
                                ----------------

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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIX Function Details

Syntax
  FIX(numeric-expression)

If x is a numeric expression, then 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIX Function Programming Example

The following statements illustrate the differences between INT and FIX:

CLS    ' Clear screen
PRINT INT(-99.8)
PRINT FIX(-99.8)
PRINT INT(-99.2)
PRINT FIX(-99.2)

Output

-100
-99
-100
-99
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FOR...NEXT Statement Details

Syntax
  FOR counter = start TO end [STEP increment]
    [statements]
  NEXT [counter [,counter...]]

  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 the 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 the
correct form:

  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."the value of
        attribute is 1.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FOR...NEXT Statement Programming Example

This 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.

CLS                         ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FRE Function Details

Syntax
  FRE(stringexpression)
  FRE(numeric-expression)

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       The size of the next free block of string
  numeric value   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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FRE Function Programming Example

This example shows some of the values FRE returns before and after
dimensioning an array.

' $DYNAMIC
CLS                 ' Clear screen
PRINT "Before dimensioning arrays:  " FRE(""),FRE(0),FRE(-1)
DIM LARGE%(150,150), BIG$(5000)
PRINT "After dimensioning arrays:   " FRE(""),FRE(0),FRE(-1)

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FREEFILE Function Details

Syntax
  FREEFILE

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FREEFILE Function Programming 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 OUTPUT AS Filenum
PRINT Filename$;" opened as File #"; Filenum

Sample Output

Enter file name: DATA.DAT

DATA.DAT opened as File # 1
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FUNCTION...END FUNCTION Details

Syntax
  FUNCTION name [(parameterlist)][STATIC]
      [statements]
    name = expression
      [statements]
  END FUNCTION

  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 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 using 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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FUNCTION...END FUNCTION Statement Programming Examples

FUNC_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the use of the FUNCTION statement. To look at the program in the View window
and, optionally, to run the program, load FUNC_EX.BAS using the File menu's
Open Program command.

The program uses a recursive function (a function that calls itself) to
find the length of a string.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GET (File I/O) Statement Details

Syntax
  GET [#]filenumber[,[recordnumber][,variable]]

  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.

  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 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 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 INPUT #
        or LINE INPUT # after a GET statement to read characters from
        the random-access file buffer. You may use the EOF function
        after a GET statement to see if the GET went beyond the end
        of the file.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GET (File I/O) Statement Programming Example

The following program opens the file TESTDAT2.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
' Define a variable of the user type.
DIM Rec AS TestRecord
'********************************************************************
' This part of the program is an insert whose only function is to
' create a random-access file to be used by the second part of the
' program, which demonstrates the CVSMBF function
'********************************************************************
OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(Rec)
CLS
RESTORE
READ NameField$, ScoreField
I = 0
DO WHILE UCASE$(NameField$) <> "END"
   I = I + 1
   Rec.NameField = NameField$
   Rec.ScoreField = ScoreField
   PUT #1, I, Rec
   READ NameField$, ScoreField
   IF NameField$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
   DATA "John Simmons", 100
   DATA "Allie Simpson", 95
   DATA "Tom Tucker", 72
   DATA "Walt Wagner", 90
   DATA "Mel Zucker", 92
   DATA "END", 0

'  Open the test data file.
'
DIM FileBuffer AS TestRecord
OPEN "TESTDAT2.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
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GET (Graphics) Statement Details

Syntax
  GET [STEP](x1,y1)-[STEP](x2,y2),arrayname[(indices)]

  Argument      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 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. The table below shows the
number of bits per pixel per plane and the number of planes for each
screen mode.

  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
   9               1                2   (if   64K of EGA  memory)
                                    4   (if > 64K of 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the programming example for BSAVE.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOSUB...RETURN Statement Details

Syntax
  GOSUB {linelabel1 | linenumber1}
  [statements]
  RETURN [linelabel2 | linenumber2]

  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 below.

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.
                         ---------------------
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOSUB...RETURN Statement Programming Example

This example shows the correct use of RETURN linelabel statements.

CLS                              ' Clear screen
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   'Cannot return from here to main
                   'program - only to SUB1.

Sample Output

in module-level code
in subroutine one
in subroutine two
back in subroutine one
back in module-level code
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOTO Statement Details

Syntax
  GOTO {linelabel | linenumber}

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOTO Statement Programming Example

This example calculates the area of a circle after you supply the radius.

CLS      ' Clear screen
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

Sample Output

Input 0 to end.
? 5
Area = 78.5
? 0
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
HEX$ Function Details

Syntax
  HEX$(expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
HEX$ Function Programming Example

This example displays the hexadecimal value of a decimal number
you supply.

CLS          ' Clear screen
INPUT X
A$ = HEX$(X)
PRINT X; "decimal is "; A$; " hexadecimal"

Sample Output

? 32
 32 decimal is 20 hexadecimal
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
Block IF...THEN...ELSE Details

  IF booleanexpression1 THEN
     [statementblock-1]
  [ELSEIF booleanexpression2 THEN
     [statementblock-2]
  . . .
  [ELSE
     [statementblock-n]]
  END IF

  Part                                     Description

  booleanexpression1, booleanexpression2   Any expression that
                                           evaluates to true (nonzero)
                                           or false (zero)

  statementblock-1, statementblock-2,      One or more BASIC
  statementblock-n                         statements on one or more
                                           lines

In executing a block-form IF, QuickBASIC tests the first Boolean
expression (booleanexpression1). 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 want 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.

The block form of the IF...THEN command provides several advantages over
the single-line form:

  ■ 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
  ■ 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.


Single-line IF...THEN...ELSE

Syntax
  IF booleanexpression THEN thenpart [ELSE elsepart]

The single-line form of the statement is best used for short,
straightforward tests where only one action is taken.

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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IF...THEN Statement Programming Example

These examples show the use of single-line and block IF...THEN...ELSE
statements.

Here is the single-line form:

CLS    ' Clear screen
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"


Here is the block form, which is easier to read and more powerful:

CLS    ' Clear screen
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"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INKEY$ Function Details

Syntax
  INKEY$

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.

See Keyboard Scan Codes Table and the
ASCII Character Codes Table for a complete list
of these 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 the following:

  ■ 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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INKEY$ Function Programming Example

This example shows a common use of INKEY$. The program pauses until
the user presses a key:

PRINT "Press any key to continue..."
DO
LOOP WHILE INKEY$=""
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INP Function Details

Syntax
  INP(port)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the OUT statement programming example, which uses both the INP and
the OUT statements.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT Statement Details

Syntax
  INPUT[;]["promptstring"{;|,}]variablelist

  Argument       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 an error message which reads "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 commands, INPUT statement

  CTRL+ or RIGHT     Moves cursor one character to the right.

  CTRL+] or LEFT      Moves cursor one character to the left.

  CTRL+F or           Moves cursor one word to the right.
  CTRL+RIGHT

  CTRL+B or           Moves cursor one word to the left.
  CTRL+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, characters above and 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).

  DEL                 Deletes the character at the cursor.

  CTRL+H or           Deletes the character to the left of the
  BACKSPACE           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       Terminates input (exits compiled program).
  CTRL+C
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT Statement Programming Example

This example uses INPUT to calculate the area of a circle from a
radius you supply. It prompts you for a new radius until you enter 0.

CLS
PI = 3.141593 : R = -1
DO WHILE R
    PRINT "Enter radius (or 0 to quit)."
    INPUT ; "If radius = ", R
    IF R > 0 THEN
        A = PI * R ^ 2
        PRINT ", the area of the circle ="; A
    END IF
    PRINT
LOOP

Sample Output

Enter radius (or 0 to quit).
If radius = 3, the area of the circle = 28.27434

Enter radius (or 0 to quit).
If radius = 4, the area of the circle = 50.26549

Enter radius (or 0 to quit).
If radius = 0
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT # Statement Details

Syntax
  INPUT #filenumber, variablelist

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 line feed (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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT # Statement Programming Example

This example reads a series of test scores from a sequential file
and calculates the average score.

' NOTE: Before you run this program, create a one-line data file
'       CLASS.DAT made up of a series of test scores -- 97 84 63 89 100.

DEFINT A-Z
CLS    ' Clear screen
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

Sample Output

1  97
2  84
3  63
4  89
5  100

Total students: 5  Average score: 86.6
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT$ Function Details

Syntax
  INPUT$(n[,[#]filenumber])

The n is the number of characters (bytes) to read from the file. The
filenumber is the number used to open 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT$ Function Programming Example

This example prints a file on the screen using INPUT$ to read
one character at a time, then converting the character as
necessary and displaying it.

  Tip: You must supply a text file when you run this example.
       Use a text file you have already created, create a file
       with a text editor, or specify the README.DOC text file.

'ASCII codes for tab, and line feed.
CONST HTAB = 9, LFEED = 10

CLS    ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INSTR Function Details

Syntax
  INSTR([start,]stringexpression1,stringexpression2)

  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 the following conditions:

  Condition                           Value Returned
  stringexpression2 found in          The position at which the
  stringexpression1                   match is 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INSTR Function Programming Example

This example uses INSTR and UCASE$ to determine a person's sex from
their courtesy title (Mr., Mrs., or Ms.).

' Get a name.
CLS    ' Clear screen
DO
   INPUT "Enter name including courtesy title (Mr., Mrs., or Ms.): ", 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 determine sex, query user.
    DO
        INPUT "Enter sex (M/F): ", Sex$
        Sex$ = UCASE$(Sex$)
    LOOP WHILE Sex$ <> "M" AND Sex$ <> "F"
END IF
' Print result
PRINT "Sex is "; Sex$

Sample Output

Enter name: Ms. Elspeth Brandtkeep
Sex is F

Enter name: Dr. Richard Science
Enter sex (M/F): M
Sex is M
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INT Function Details

Syntax
  INT(numeric-expression)

The INT function removes the fractional part of its argument.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INT Function Programming Example

This example compares output from INT, CINT, and FIX, the three
functions that convert numeric data to integers.

CLS                ' Clear screen
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


Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL$ Function Details

Syntax
  IOCTL$([#]filenumber)

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.

  Note: BASIC devices ( LPT1:, COM1:, COM2:, SCRN:, CONS:) and
        DOS block devices ( A: through Z:) do not support IOCTL.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL$ Function Programming Example

This example shows how to communicate with a device driver using a
hypothetical device driver named ENGINE. The IOCTL statement sets the
data mode in the driver and the IOCTL$ function tests the data mode.

'   Note: The IOCTL$ function works only if the device driver is
'         installed and states that it processes IOCTL strings, and
'         if BASIC performs an OPEN statement on the device. Do not
'         run this example in its current form.
'
OPEN "DEVENGINE" 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL Statement Details

Syntax
  IOCTL [#]filenumber, string

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL Statement Programming Example

See the IOCTL$ function programming example, which shows how both the
IOCTL statement and IOCTL$ function are used with a device driver.

  Note: Any use of the IOCTL statement is device-driver dependent.
        The IOCTL statement uses string arguments that are only
        documented in the driver manual.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY Statement Details

Syntax                   Use
  KEY n, stringexpression      Assigns soft-key string values
  KEY LIST                     Displays soft-key string values
  KEY {ON|OFF}                 Turns on and off the soft-key display line
                               at the bottom of the screen

Assigning Strings to Function Keys

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.

Displaying Soft Key Assignments

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY Statement Programming Example

These examples show how to assign values to soft keys.

Here is an example of assigning and disabling a soft key. KEY LIST
displays key values after KEY 4 has been assigned and again after
it has been disabled:

CLS                       ' Clear screen
KEY 4, "MENU" + CHR$(13)  'Assigns to soft key 4 the string
                          '"MENU" followed by a carriage return.
KEY LIST
KEY 4, ""                 'Disables soft key 4.
KEY LIST

Here is an example of using KEY statements to set up one-key
equivalents of menu selections. For example, pressing F1
is the same as entering the string "Add":

CLS                       ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY(n) Statement Details

Syntax
  KEY(n) ON
  KEY(n) OFF
  KEY(n) STOP

The argument n is the number of a FUNCTION key, a cursor-direction
key, or a user-defined key. See the KEY statements 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 the table below.

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.

  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            CAPSLOCK    3A
  @ 0r 2    03            S           1F            F1          3B
  # 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            tilde~ or `  29            NUMLOCK     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
  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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY(n) Statement Programming 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", trap CTRL+SHIFT and CTRL+CAPS-LOCK+s.

     Note: Do not run this example with the NumLock key depressed.

I = 0
CLS    ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KILL Statement Details

Syntax
  KILL filespec

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.
                           -------------------
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KILL Statement Programming Examples

These examples show how to use KILL to delete files.

Example 1

Here is an example of using wild-card characters with KILL.
This example will not run unless the specified files are found:

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.

Example 2

Here is an example program that deletes the file specified on
the command line:

' Make sure you have selected Full Menus from the Options menu,
' then select Modify COMMAND$ from the Run menu to specify a file.
' Specify any file, but be sure it's one you want to delete.
DEFINT A-Z
CLS    ' Clear screen
ON ERROR GOTO Errorhandle 'Set up error handling.
FileName$ = COMMAND$      'Get file name.
KILL FileName$
PRINT FileName$ " deleted"
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LBOUND Function Details

Syntax
  LBOUND(array[,dimension])

The LBOUND function is used with the UBOUND function to determine the
size of an array.

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LBOUND Function Programming Example

See the UBOUND function programming example, which uses both the LBOUND
and UBOUND functions.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LCASE$ Function Details

Syntax
  LCASE$(stringexpression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LCASE$ Function Programming Example

This example converts uppercase characters in a string to lowercase.

' Program to convert to lowercase.
CLS                ' Clear screen
READ Word$
PRINT LCASE$(Word$);
DATA "THIS IS THE STRING in lower case."

Sample Output

this is the string in lower case.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEFT$ Function Details

Syntax
  LEFT$(stringexpression,n)

The argument stringexpression can be any string variable, string constant,
or 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEFT$ Function Programming Example

This example prints the leftmost five characters of A$.

CLS                ' Clear screen
A$="BASIC LANGUAGE"
B$=LEFT$(A$, 5)
PRINT B$

Sample Output

BASIC
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEN Function Details

Syntax
  LEN(stringexpression)
  LEN(variable)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEN Function Programming Example

This example prints the length of a string and the size in bytes of several
types of variables.

CLS    ' Clear screen
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 "A string:" LEN("A string.")
PRINT "Integer:" LEN(A)
PRINT "Long:" LEN(B)
PRINT "Single:" LEN(C)
PRINT "Double:" LEN(D)
PRINT "EmpRec:" LEN(E)
END

Sample Output

A string: 9
Integer: 2
Long: 4
Single: 4
Double: 8
EmpRec: 22
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LET (Assignment) Statement Details

Syntax
  [LET] variable=expression

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LET (Assignment) Statement Programming Example

This example shows the use of the optional LET keyword.

CLS    ' Clear screen
LET D = 12
LET E = 12 - 2
LET F = 12 - 4
LET SUM = D + E + F
PRINT D E F SUM

The following program lines perform the same function, without using
the LET keyword.

CLS    ' Clear screen
D = 12
E = 12 - 2
F = 12 - 4
SUM = D + E + F
PRINT D E F SUM

Sample Output

12 10 8 30
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE Statement Details

Syntax
  LINE [[STEP] (x1,y1)]-[STEP] (x2,y2) [,[color][,[B[F]][,style]]]

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

  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 COLOR statement details and the SCREEN statement details for
information about how to specify a color number in different screen
modes.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE Statement Programming Example

This example uses LINE statements to display a series of screens
with different line graphics. To run this example, your screen must
be 320 pixels wide by 200 pixels high and support CGA screen mode.

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.
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
LINE(0, 0)-(319, 199)             'Draws a diagonal line across
                                  'the screen (downward).
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
LINE(0, 100)-(319, 100)           'Draws a horizontal line
                                  'across the screen.
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
LINE(10, 10)-(20, 20), 2          'Draws a line in color 2.
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
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.
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
LINE (0, 0)-(100, 100),, B        'Draws a box in the fore-
                                  'ground color (note that the
                                  'color is not included).
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
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).
DO
LOOP WHILE INKEY$ = ""            'Press any key to continue
CLS    ' Clear screen
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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT Statement Details

Syntax
  LINE INPUT[;] ["promptstring";] stringvariable

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT Statement Programming 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT # Statement Details

Syntax
  LINE INPUT #filenumber,stringvariable

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE INPUT # Statement Programming Example

This example uses LINE INPUT # to echo data input to a file:

'*** Programming example for LINE INPUT # statement***
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

Sample 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"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOC Function Details

Syntax
  LOC(filenumber)

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 be read.

The LOC function cannot be used on the SCRN:, KYBD:, or LPTn: devices.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOC Function Programming Example

This example stops the program if the current file position
is beyond 50.

                                ----- Note -----
This example is incomplete. Do not run this example in its current form.
                                ----------------

IF LOC(1) > 50 THEN STOP
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCATE Statement Details

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

  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 must be
             a numeric expression returning an integer.

You may omit any argument from the statement. 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 less than stop, LOCATE produces
a two-part cursor. If the start line is given, stop must also be
specified.

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.
  QuickSCREEN      Details      ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCATE Statement Programming Examples

These examples show how to use the LOCATE statement to move the cursor
and select items from a menu.

Here is an example that shows the effects on the cursor of different
LOCATE statements:

CLS                       'Clear screen
LOCATE 5, 5               'Moves cursor to row 5, column 5
PRINT "C"
DO
LOOP WHILE INKEY$ = ""    'Press any key to continue
LOCATE 1,1                'Moves cursor to upper-left corner of the screen.
PRINT "C"
DO
LOOP WHILE INKEY$ = ""    'Press any key to continue
LOCATE,,1                 'Makes the cursor visible; position remains
                          'unchanged.
PRINT "C"
DO
LOOP WHILE INKEY$ = ""    'Press any key to continue
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.
PRINT "C"
DO
LOOP WHILE INKEY$ = ""    'Press any key to continue
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.
PRINT "C"
DO
LOOP WHILE INKEY$ = ""    'Press any key to continue


Here is part of a program that 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:

                                ----- Note -----
This program is incomplete. Do not try to run it in its current form.
                                ----------------

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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCK...UNLOCK Statement Details

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

These statements are used in networked environments where several
processes might need access to the same file.

  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"
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCK...UNLOCK Statement Programming Examples

These example statements show how LOCK and UNLOCK are used in
networked environments, where several processes might need access
to the same file. These examples assume a random-access file.

                           ----- Note -----
These examples are incomplete. Do not run them in their current form.
                           ----------------

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"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOF Function Details

Syntax
  LOF(filenumber)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the GET (File I/O) statement programming example which uses the LOF
function.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOG Function Details

Syntax
  LOG(numeric-expression)

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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOG Function Programming Example

This example prints the value of e and then prints the natural logarithms
of e taken to the first, second, and third powers.

CLS                    ' Clear screen
PRINT EXP(1),
FOR I = 1 TO 3
    PRINT LOG(EXP(1) ^ I),
NEXT

Sample Output

2.718282       1       2       3
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPOS Function Details

Syntax
  LPOS(n)

The argument n is the index of the printer being tested:

  ■ LPT1: would be tested with LPOS(1) or LPOS(0)
  ■ LPT2: would be tested with LPOS(2)
  ■ LPT3: would be tested with LPOS(3)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPOS Function Programming Example

This example 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.

CLS                                ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPRINT and LPRINT USING Details

Syntax 1
  LPRINT [expressionlist][{;|,}]
Syntax 2
  LPRINT USING formatstring; expressionlist[{;|,}]

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

If you do LPRINT CHR$(13), BASIC actually outputs LPRINT CHR$(13) and
LPRINT CHR$(10). This feature was created to provide compatibility
between Microsoft BASIC and IBM BASICA.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPRINT and LPRINT USING Programming Example

See the LPOS function programming example, which uses the LPRINT command.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LSET Statement Details

Syntax
LSET {stringvariable=stringexpression | stringexpression1=stringexpression2}

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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LSET Statement Programming Example

The following statement would convert the single-precision numeric variable
AMT to a 4-byte string and stores that string in A$,left-justified:

LSET A$ = MKS$(AMT)

In contrast, the following statement would convert the integer numeric
variable COUNT% to a 2-byte string and stores that string in D$,
right-justified:

RSET D$ = MKI$(COUNT%)

  Note: To see the LSET statement used in a full example program, see
        the CVS function programming example
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LTRIM$ Function Details

Syntax
  LTRIM$(stringexpression)

The stringexpression can be any string expression.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LTRIM$ Function Programming Example

This example copies a file to a new file, removing all leading and
trailing spaces.
                                ----- Note -----
To run this example, you must supply the name of an existing text file.
                                ----------------

CLS                          ' Clear screen
' 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ Function Details

Syntax
  MID$(stringexpression,start[,length])

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ Function Programming Example

This example converts a binary number to a decimal number. The
program uses the MID$ function to extract digits from the binary
number (input as a string).

CLS    ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ Statement Details

Syntax
  MID$(stringvariable,start[,length])=stringexpression

  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, string constant, or 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ Statement Programming Example

This example uses the MID$ statement to replace string characters.

CLS                        ' Clear screen
Test$ = "Paris, France"
PRINT Test$
MID$(Test$, 8)="Texas "    ' Starting at position 8, replace
                           ' characters in Test$ with Texas
PRINT Test$

Sample Output

Paris, France
Paris, Texas
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKDIR Statement Details

Syntax
  MKDIR pathspec

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKDIR Statement Programming Example

This example creates a subdirectory and creates or copies a file
in that directory:

CLS                     ' Clear screen
PRINT "This program creates a subdirectory named MONTHS,"
PRINT "then creates or copies a file in that directory."
PRINT
MKDIR "MONTHS"
INPUT "Filename"; File$
IF File$ = "" THEN END
OPEN "MONTHS" + File$ FOR OUTPUT AS #1
PRINT "You have created "; File$; " in directory MONTHS."
CLOSE #1
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKSMBF$ and MKDMBF$ Functions Details

Syntax
  MKSMBF$(single-precision-expression)
  MKDMBF$(double-precision-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKSMBF$ and MKDMBF$ Functions Programming 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 a name and a score, separated by a comma."
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKD$, MKI$, MKL$, and MKS$ Functions Details

Syntax
  MKI$(integerexpression)
  MKS$(single-precision-expression)
  MKL$(long-integer-expression)
  MKD$(double-precision-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the programming example for the CVI, CVS, CVL, CVD statements,
which uses the MKS$ function.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
NAME Statement Details

Syntax
  NAME oldfilename AS newfilename

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 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 that reads
"File already open." You must close an open file before renaming it.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
NAME Statement Programming Example

This example shows how to use NAME to rename your README.DOC file.

CLS    ' Clear screen
'Change README.DOC to READMINE.DOC
NAME "README.DOC" AS "READMINE.DOC"
FILES  ' Display the files in your directory to confirm name change
PRINT
PRINT "README.DOC is now called READMINE.DOC"
PRINT "Press any key to continue"
DO
LOOP WHILE INKEY$ = ""
'Change name back to README.DOC and confirm by displaying files
NAME "READMINE.DOC" AS "README.DOC"
FILES
PRINT
PRINT "README.DOC is back to its original name"

  Tip: You can also use NAME to move a file from one directory to
       another. You can move README.DOC to the directory MYDIR
       with the following statement:

           NAME "README.DOC" AS "MYDIRREADME.DOC"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OCT$ Function Details

Syntax
  OCT$(numeric-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OCT$ Function Programming Example

This example displays the octal version of several decimal numbers.

PRINT "The octal representation of decimal 24 is " OCT$(24)
PRINT "The octal representation of decimal 55 is " OCT$(55)
PRINT "The octal representation of decimal 101 is " OCT$(101)

Sample Output

The octal representation of decimal 24 is 30
The octal representation of decimal 55 is 67
The octal representation of decimal 101 is 145
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON...GOSUB and ON...GOTO Statement Details

Syntax 1
  ON expression GOSUB {line-number-list | line-label-list}

Syntax 2
  GOTO {line-number-list | line-label-list }

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   Control drops to the next BASIC
  than number of items in list   statement.

  Negative number or             An error message appears that reads
  number greater than 255        "Illegal function call."


You may mix line numbers and labels in the same list.

  Note: 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON...GOSUB Statement Programming Example

This example causes program control to branch to one of three
subroutines, depending on the value of Chval:

CLS    ' Clear screen
Attend = 20
Fees = 5 * Attend
PRINT "1  Display attendance at workshops"
PRINT "2  Calculate total registration fees paid"
PRINT "3  End program"
PRINT : PRINT "What is your choice?"
Choice:
    DO
       ch$ = INKEY$
    LOOP WHILE ch$ = ""
    Chval = VAL(ch$)
    IF Chval > 0 AND Chval < 4 THEN
        ON Chval GOSUB Shop, Fees, Progend
    END IF
END
Shop:
    PRINT "ATTENDANCE IS", Attend
    RETURN Choice
Fees:
    PRINT "REGISTRATION FEES ARE $"; Fees
    RETURN Choice
Progend:
    END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON ERROR Statement Details

Syntax
  ON ERROR GOTO line

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 block of
code marked by a line label or line number.

SUB and FUNCTION procedures and DEF FN functions can contain their own
error handlers. The error handler must be located after the last
executable statement but before the END SUB, END FUNCTION, or END DEF
statement. To keep the error handler from executing when there is no
error, the procedure or function must terminate with an EXIT SUB, EXIT
FUNCTION, or EXIT DEF statement immediately ahead of the error
handler, as in the following example:

SUB InitializeMatrix (var1, var2, var3, var4)
      .
      .
      .
   ON ERR GOTO ErrorHandler
      .
      .
      .
   EXIT SUB

   ErrorHandler:
      .
      .
      .
   RETURN

END SUB

  Note: Errors occurring within an error-handling routine are not
        trapped. These errors halt program execution after printing
        an error message.
  QuickSCREEN      Details     ◄Example►      Contents    Index
──────────────────────────────────────────────────────────────────────────────
ON ERROR Statement Programming 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 = 53

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
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON event - Event trapping statements that indicate the first line
           of an event-trapping subroutine
Syntax
  ON event GOSUB {linenumber | linelabel}
    ■ event is a keyword that identifies the event to trap
    ■ linelabel or linenumber is the first line of an event-handling
      subroutine
  ON event Statement           Type of Event Trapped
  ON COM(n)                  Characters received at communications port n
  ON KEY(n)                  Keystroke on key n
  ON PEN                     Lightpen activity
  ON PLAY(n)                 Less than n notes in background music buffer
  ON STRIG(n)                Activity on joystick trigger n
  ON TIMER(n)                Elapsed time event

See Also  COM(n) ON  KEY(n) ON  PEN ON  PLAY ON
          STRIG ON  TIMER ON
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON event Statements Details

The ON event statement lets you specify a subroutine that is executed
whenever an event occurs on a specified device.

Syntax
  ON event GOSUB {linenumber | linelabel}

  Argument     Description
  event        A keyword that specifies the event that causes a branch to
               the event-trapping subroutine. An event is a condition on a
               specific device:

                 COM    characters received at a communications port
                 KEY    a designated keystroke
                 PEN    lightpen activated
                 PLAY   too few notes in background music queue
                 STRIG  joystick trigger pressed
                 TIMER  time interval has elapsed

  linenumber   The number or label of the first line in the event-
  or           trapping subroutine. This line must be in the module-
  linelabel    level code.

      Note: A linenumber of 0 disables event trapping and does not
            specify line 0 as the start of the subroutine.

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.

  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.

  For specific information about each of these statements, see the
    COM statement,
    KEY statement,
    PEN statement,
    PLAY (event) statement,
    STRIG statement, or
    TIMER statement.

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."
  ■ if an event occurs in a procedure, a RETURN linenumber or
    RETURN linelabel statement cannot get back into the procedure
    because the line number or label must be in the module-level code.

Differences from BASICA

If you use BC from the DOS prompt and a program contains ON event
statements, you must use /V or /W. These options allow the compiler
to function correctly when event-trapping subroutines are included
in a program. BASICA does not require additional options.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON event Statements Programming Examples

The following programming examples show how to integrate ON event statements,
statements that enable traps, and event-handling subroutines into a working
program:
  ON PLAY(n) statement programming example
  ON TIMER(n) statement programming example
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON COM(n) - Event trapping statement that specifies a subroutine to
            branch to when characters are received at communications port n
Syntax
  ON COM(n) GOSUB {linelabel | linenumber}
    ■ n, an integer expression, indicates one of the serial ports,
      either 1 or 2
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine

See Also  COM(n) ON
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON KEY(n) - Event trapping statement that specifies a subroutine to
            branch to when key n is pressed
Syntax
  ON KEY(n) GOSUB {linelabel | linenumber}
    ■ n, an integer expression, is the number of a function key, direction
      key, or user-defined key
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine

See Also  KEY(n) ON  KEY(n)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON PEN - Event trapping statement that specifies a subroutine to branch
         to when the lightpen is activated
Syntax
  ON PEN GOSUB {linelabel | linenumber}
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine

See Also  PEN ON
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON PLAY(n) - Event trapping statement that specifies a subroutine to
             branch to when there are too few notes in the music queue
Syntax
  ON PLAY(queuelimit) GOSUB {linelabel | linenumber}
    ■ queuelimit, an integer expression, is the minimum number of notes
      to maintain in the background music queue (between 1 and 32)
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine to branch to when the number of notes in the music
      buffer goes from queuelimit to queuelimit - 1

See Also  PLAY ON, PLAY OFF, PLAY STOP  PLAY
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON STRIG(n) - Event trapping statement that specifies a subroutine to
              branch to when joystick trigger n is pressed
Syntax
  ON STRIG(n) GOSUB {linelabel | linenumber}
    ■ n, an integer expression, is the trigger number:
      0 = lower button, first joystick    2 = lower button, second joystick
      4 = upper button, first joystick    6 = upper button, second joystick
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine to branch to when the trigger is pressed

See Also  STRIG ON
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON TIMER(n) - Event trapping statement that specifies a subroutine to
              branch to when n seconds have elapsed
Syntax
  ON TIMER(n) GOSUB {linelabel | linenumber}
    ■ n, an integer expression with a value between 1 and 86,400, is the
      number of seconds in the time interval
    ■ linelabel or linenumber is the first line of the event-handling
      subroutine to branch to when the time elapses

See Also  TIMER ON
  QuickSCREEN      ◄Details►      Example      Contents    Index
──────────────────────────────────────────────────────────────────────────────
ON COM(n) Statement Details

Syntax
  ON COM(n) GOSUB {linelabel | linenumber}

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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON KEY(n) Statement Details

Syntax
  ON KEY(n) GOSUB {linelabel | linenumber}

Keys are processed in the following order:

  1. The line printer's echo-toggle key is processed first. Defining
     this key as 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.

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.
  QuickSCREEN      ◄Details►      Example      Contents    Index
──────────────────────────────────────────────────────────────────────────────
ON PEN Statement Details

Syntax
  ON PEN GOSUB {linelabel | linenumber}

Any activation of the lightpen will be trapped.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON PLAY(n) Statement Details

Syntax
  ON PLAY(queuelimit) GOSUB {linelabel | linenumber}

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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON STRIG(n) Statement Details

Syntax
  ON STRIG(n) GOSUB {linelabel | linenumber}

Following are the integer values for each joystick trigger:
  0 = lower button, first joystick
  2 = lower button, second joystick
  4 = upper button, first joystick
  6 = upper button, second joystick
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON TIMER(n) Statement Details

Syntax
  ON TIMER(n) GOSUB {linelabel | linenumber}

The maximum number of seconds that can be specified for the time interval,
n, is the number of seconds in a 24-hour day (86,400).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON COM(n) Statement Programming Example

There is no programming example for the ON COM(n) statement.

The following programming examples show how to integrate ON event statements,
statements that enable traps, and event-handling subroutines into a working
program:
  ON PLAY(n) statement programming example
  ON TIMER(n) statement programming example
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON KEY(n) Statement Programming Example

See the Selected Event-Trapping Programming Example 1, which
uses the ON KEY(n) statement.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON PEN Statement Programming Example

There is no programming example for the ON PEN statement.

The following programming examples show how to integrate ON event statements,
statements that enable traps, and event-handling subroutines into a working
program:
  ON PLAY(n) statement programming example
  ON TIMER(n) statement programming example
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON PLAY(n) Statement Programming Example

Here is a program that plays continuous music by calling an event-handling
subroutine when 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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON STRIG(n) Statement Programming Example

There is no programming example for the ON STRIG(n) statement.

The following programming examples show how to integrate ON event statements,
statements that enable traps, and event-handling subroutines into a working
program:
  ON PLAY(n) statement programming example
  ON TIMER(n) statement programming example
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON TIMER(n) Statement Programming Example

Here is a program that 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON UEVENT GOSUB Statement Details

Syntax
  ON UEVENT GOSUB { linenumber | linelabel }

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.

When the interrupt 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 EVENT 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 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ON UEVENT Statement Programming Example

The following example illustrates the use of ON UEVENT GOSUB:

ON UEVENT GOSUB Event1
UEVENT ON
INPUT "Enter a number"; a
IF a = 5 THEN CALL Setuevent
END
'
Event1:
PRINT "Got to the event handler"
RETURN
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN (File I/O) Statement Details

Syntax
  OPEN file [FOR mode1] [ACCESS access] [lock] AS [#]filenum [LEN=reclen]

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.

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

  OPEN mode2,[#]filenum,file[,reclen]

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 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. 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN (File I/O) Statement Programming Examples

These example program lines show different uses of the OPEN (File I/O)
statement.

                            ----- Note -----
Do not run these examples without the specified files and devices.
                            ----------------

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 "DEVROBOT" 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"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN (Communications) Statement Details

Syntax
  OPEN "COMn: optlist1 optlist2" [FOR mode] AS [#]filenum [LEN=reclen]

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 and 9600.
  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, tabs are
           expanded to spaces, carriage returns are forced at the
           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.
  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.
  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 for ten
           seconds. 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.
  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."
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN (Communications) Statement Programming 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPTION BASE Statement Details

Syntax
  OPTION BASE n

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: 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPTION BASE Statement Programming Example

This example shows the use of OPTION BASE to override the default
base array subscript value of 0. Subscripts in array A range from
1 to 20 rather than 0 to 19.

CLS                     ' Clear screen
OPTION BASE 1
DIM A(20)
PRINT "The base subscript in array A is"; LBOUND(A)
PRINT "The upper bound subscript in array A is"; UBOUND(A)

Sample Output

The base subscript in array A is 1
The upper bound subscript in array A is 20
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OUT Statement Details

Syntax
  OUT port, data

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OUT Statement Programming Example

OUT_EX.BAS is a program file in the subdirectory ADVR_EX that uses the
OUT and INP statements to control the timer and speaker to produce a note.
To look at the program in the View window and, optionally, to run it, use
the File menu's Open Program command.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PAINT Statement Details

Syntax
  PAINT [STEP] (x,y)[,[paint] [,[bordercolor] [,background]]]

  Argument      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 used to paint
                the area. If you do not specify paint, the foreground
                color attribute is used. For information about valid
                colors, numbers, and attributes see the following:
                  COLOR statement details,
                  SCREEN statement details, and
                  PALETTE statement details.
                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 bordercolor is not specified, the
                paint argument is 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" 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PAINT Statement Programming Example

This example uses PAINT to create a magenta fish with a cyan tail.

CONST PI = 3.1415926536
CLS    ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PALETTE Statement Details

Syntax
  PALETTE [attribute,color]
  PALETTE USING array-name [(array-index)]

  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 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.

The table below lists attribute and color ranges for various adapter
types and screen modes.

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:

  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.


  Screen Color and Attribute Ranges

  SCREEN   Monitor             Adapter   Attribute   Color
  Mode     Attached            Range     Range

   0       Monochrome          MDPA      0-15        N/A
           Monochrome          EGA       0-15        0-2
           Color               CGA       0-15        N/A
           Color/Enhanced(b)   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(b)   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(b)   EGA       0-1         0-15
           N/A                 VGA       0-1         0-15
           N/A                 MCGA      0-1         N/A
   7       Color/Enhanced(b)   EGA       0-15        0-15
           N/A                 VGA       0-15        0-15
   8       Color/Enhanced(b)   EGA       0-15        0-15
           N/A                 VGA       0-15        0-15
   9       Enhanced(b)         EGA(c)    0-3         0-63
           Enhanced(b)         EGA(d)    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(e)
           N/A                 MCGA      0-1         0-262,143(e)
  12       N/A                 VGA       0-15        0-262,143(e)
  13       N/A                 VGA       0-255       0-262,143(e)
           N/A                 MCGA      0-255       0-262,143(e)
  ____________________________________________________________________
  N/A = Not Applicable
  (b) With 64K of EGA memory
  (c) With more than 64K of EGA memory
  (d) IBM Enhanced Color Display
  (e) Display colors are not numbered from 0 to 262,143. See above.

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PALETTE Statement Programming Example

This example shows the different forms of the PALETTE and PALETTE USING
statements.

                                ----- Note -----
This is not a complete program. Do not run this example in its
current form.
                                ----------------

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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PCOPY Statement Details

Syntax
  PCOPY sourcepage, destinationpage

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PCOPY Statement Programming Example

This example copies the contents of page 1 to page 2.

                                ----- Note -----
This is not a complete program. Do not run this example in its current form.
                                ----------------

PCOPY 1,2
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEEK Statement Details

Syntax
  PEEK(address)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the DEF SEG statement programming example, which uses the PEEK
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN Function Details

Syntax
  PEN(n)

The argument n indicates what value is to be returned. It is a numeric
expression in the range 0-9.

  Note: 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
  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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN Function Programming Example

This example produces an endless loop to print the current pen-switch
status (UP/DOWN). Press CTRL+BREAK to exit the loop.

                                ----- Note -----
          Do not run this example if your mouse driver is enabled.
                                ----------------
' You will have to press CTRL+BRK to exit this loop
COLOR 0,7
CLS                ' Clear screen
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
COLOR 7,0
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN Statements Details

Syntax
  PEN ON
  PEN OFF
  PEN STOP

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN Statements Programming Example

See the PEN function programming example, which uses the PEN statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY Statement Details

Syntax
  PLAY commandstring

The commandstring is a string expression containing one or more music
commands. The PLAY statement uses a concept similar to DRAW in that it
embeds a music macro language in one statement. A set of commands, used
as part of the PLAY statement, specifies a particular action.

  Octave and Tone Commands
  Duration and Tempo Commands
  Foreground/Background Operation Commands
  Execute Substring Command

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)
  Details   ◄Octave and Tone►   Duration   Operation   Substrings
──────────────────────────────────────────────────────────────────────────────
Octave and Tone Commands

  Octave     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       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.

  Suffixes   Action
  # or +     Follows a specified note and turns it into a sharp.
  -          Follows a specified note and turns it into a flat.
  Details   ◄Duration and Tempo►   Tone   Operation   Substrings
──────────────────────────────────────────────────────────────────────────────
Duration and Tempo Commands

  Duration   Action
  L n        Sets the length of each note. L 4 is a quarter note,
             L 1 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. For example,
               A 16 can be equivalent to L 16 A.
  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      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 L 4 quarter notes in one
             minute. The range for n is 32-255. The default for n is 120.

    Note: Because of the slow clock-interrupt rate, some notes will not
          play at higher tempos (L 64 at T 255, for example).

  .          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. For example,
               ■ 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.
             Periods can appear after a pause (P). In this case, the pause
             length is scaled in the same way notes are scaled.
  Details   ◄Operation►   Duration   Octave and Tone   Substrings
──────────────────────────────────────────────────────────────────────────────
Foreground/Background Operation

  Operation   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.
  Details   ◄Substrings►   Duration   Operation   Octave and Tone
──────────────────────────────────────────────────────────────────────────────
The X Command

  Substring               Action
  "X" + VARPTR$(string)   Executes a substring.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY Statement Programming Example

These examples use PLAY to play scales and a familiar melody.

Example 1

This 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

Example 2

This example plays the first few notes of Beethoven's Fifth Symphony:

LISTEN$ = "T180 o2 P2 P8 L8 GGG L2 E-"
FATE$ = "P24 P8 L8 FFF L2 D"
PLAY LISTEN$ + FATE$
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY(n) Function Details

Syntax
  PLAY(n)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY(n) Function Programming Example

There is no programming example for the PLAY(n) function.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY ON, PLAY OFF, and PLAY STOP Statements Details

Syntax
  PLAY ON
  PLAY OFF
  PLAY STOP

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY ON, PLAY OFF, PLAY STOP Statements Programming Example

See the ON PLAY(n) statement programming example, which uses the PLAY ON
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PMAP Statement Details

Syntax
  PMAP (expression, function)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PMAP Statement Programming Example

This example uses PMAP to convert coordinate values from view to screen
coordinates and from screen coordinates to view coordinates.
                                ----- Note -----
This is not a complete program. Do not run this example in its current form.
                                ----------------
SCREEN 2
'Coordinates of upper-left corner of window defined in following
'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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POINT Function Details

Syntax
  POINT (x,y)
  POINT (number)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POINT Function Programming Example

This example redraws an 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POKE Statement Details

Syntax
  POKE address,byte

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.
                           -------------------
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POKE Statement Programming Example

See the DEF SEG statement programming example, which uses the POKE
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POS Function Details

Syntax
  POS(0)

The leftmost cursor position is numbered 1. To return the current
vertical-line position of the cursor, use the CSRLIN function.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POS Function Programming Example

This example uses POS to start a new line after every 40 characters.

CLS                       ' Clear screen
PRINT "This program starts a new line after every 40"
PRINT "characters you type. 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRESET Statement Details

Syntax
  PRESET [STEP](x,y)[,color]

PRESET works exactly like PSET, except that if the color is not specified,
the background color is selected.

  Argument      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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRESET Statement Programming Example

This example uses PSET and PRESET to draw a line 20 pixels long, then
move the line 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT Statement Details

Syntax
  PRINT [expressionlist][{,|;}]

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 displayed 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT Statement Programming Examples

These examples show the use of commas and semicolons with PRINT.

Example 1

Here is an example of using commas in a PRINT statement to print each
value at the beginning of the next print zone:

CLS                ' Clear screen
X = 5
PRINT X + 5, X - 5, X * (-5), X ^ 5
END

Sample Output

 10            0            -25            3125

Example 2

In this 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

CLS                ' Clear screen
DO
   INPUT "Input X (type 0 to quit): ", 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

Sample Output

Input X (type 0 to quit): 9
 9 squared is 81 and 9 cubed is 729

Input X (type 0 to quit): 21
 21 squared is 441 and 21 cubed is 9261

Input X (type 0 to quit): 0

Example 3

In this example, the semicolons in the PRINT statement print each
value immediately after the preceding value. Note that a space
always follows a number and precedes a positive number:

CLS                ' Clear screen
FOR X = 1 TO 5
  J = J + 5
  K = K + 10
  PRINT J; K;
NEXT X

Sample Output

 5  10  10  20  15  30  20  40  25  50
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT USING Statement Details

Syntax
  PRINT USING formatstring; expressionlist [{,|;}]

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).
              Numbers are rounded as necessary.
  +           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 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 (^^^^ 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.

  Note: 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."
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT USING Statement Programming Examples

These examples show the use of string- and numeric-formatting
characters with PRINT USING.

Example 1

Here is an example of using string-formatting characters:

CLS    ' Clear screen
A$ = "LOOK" : B$ = "OUT"
PRINT USING "!"; A$; B$            'First characters of A$ and B$.
PRINT USING "  "; A$; B$         'Two spaces between backslashes,
                                   'prints four characters from A$.
PRINT USING "   "; A$; B$; "!!"  'Three spaces, prints A$ and
                                   'a blank.
PRINT USING "!"; A$;               'First character from A$ and
PRINT USING "&"; B$                'all of B$ on one line.

Sample Output

LO
LOOKOUT
LOOK OUT  !!
LOUT

Example 2

Here is an example showing the effects of different combinations
of numeric formatting characters:

'Format and print numeric data.
CLS    ' Clear screen
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

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT # Statement Details

Syntax
  PRINT # filenumber, [USING stringexpression;] expressionlist [{,|;}]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT # Statement Programming Example

This example shows the effects of using data delimiters with PRINT #.

CLS                                    ' Clear screen
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 print.
   INPUT #1, First$, Second$, Third$
   PRINT First$; TAB(30); Second$; TAB(60); Third$ : PRINT
NEXT
CLOSE #1

Sample Output

CAMERA                  AUTOFOCUSSeptember 20           198542

CAMERA, AUTOFOCUS       September 20, 1985              42
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PSET Statement Details

Syntax
  PSET [STEP](xcoordinate,ycoordinate) [,color]

  Argument      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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PSET Statement Programming Example

This example draws a line from (0,0) to (100,100), then erases the 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
LOCATE 16,2: INPUT "Press any key to erase the line ", Gar$
' Now erase the line.
PSET (I-1, I-1), 0
FOR I = 0 TO 100
   PSET STEP (-1, -1), 0
NEXT I
LOCATE 16,2: PRINT "                                    "
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT (File I/O) Statement Details

Syntax
  PUT [#]filenumber[,[recordnumber][,variable]]
  or
  PUT [#]filenumber[,{recordnumber|recordnumber,variable|,variable}]

  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 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.

                 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 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."
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT (File I/O) Statement Programming Example

This example reads names and test scores from the console and stores them
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.

CLS    ' Clear screen
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT (Graphics Statement) Statement Details

Syntax
  PUT [STEP](x, y),arrayname[(indices)][,actionverb]

  Argument     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
                 PUT STEP (10,5),Ball
               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.

The different values for actionverb are described in the following
list. The default 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 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
           complex background twice, the background is restored. This
           allows you to move an object around the screen without
           erasing the background.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT (Graphics) Statement Programming Example

This example creates a moving white ball that ricochets off the sides
of the screen until you press a key.

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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RANDOMIZE Statement Details

Syntax
  RANDOMIZE [expression]

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 the 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RANDOMIZE Statement Programming Example

This example uses RANDOMIZE to simulate rolling a pair of dice.

' 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.
   CLS    ' Clear screen
   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

Sample 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
READ Statement Details

Syntax
  READ variablelist

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.

A single READ statement may use one or more DATA statements (they will be
used in order), or 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
READ Statement Programming Example

This example shows how you can use a READ statement to read information
into the user-defined type Employee.

TYPE Employee
   EmpName AS STRING * 35
   SocSec AS STRING * 11
   JobClass AS INTEGER
END TYPE

CLS                ' Clear screen
DIM ThisEmp AS Employee
DATA "Julia Magruder","300-32-3403",3
DATA "Amelie Reeves Troubetzkoy","777-29-3206",7

' Read first data input line and verify by printing data
READ ThisEmp.EmpName, ThisEmp.SocSec, ThisEmp.JobClass
PRINT "Employee is "; ThisEmp.EmpName
PRINT "Employee's social security number is "; ThisEmp.SocSec
PRINT "Employee's job class is"; ThisEmp.JobClass
PRINT    ' Print blank line

' Read second data input line and verify
READ ThisEmp.EmpName, ThisEmp.SocSec, ThisEmp.JobClass
PRINT "Employee is "; ThisEmp.EmpName
PRINT "Employee's social security number is "; ThisEmp.SocSec
PRINT "Employee's job class is"; ThisEmp.JobClass

Sample Output

Employee is Julia Magruder
Employee's social security number is 300-32-3403
Employee's job class is 3

Employee is Amelie Reeves Troubetzkoy
Employee's social security number is 777-29-3206
Employee's job class is 7
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REDIM Statement Details

Syntax
  REDIM [SHARED] variable(subscripts)[AS type]
                 [,variable(subscripts)[AS type]]...

  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 details for more information about using the
TO keyword.

The REDIM statement changes the space allocated to an array that has been
declared $DYNAMIC.

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.

  Note: 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REDIM Statement Programming Example

This example shows how to use REDIM to allocate an array of records and
then how to free the memory that the records use.

TYPE KeyElement
   Word AS STRING * 20
   Count AS INTEGER
END TYPE

' Make arrays dynamic.
' $DYNAMIC
CLS                          ' Clear screen
' Allocate an array of records when you need it.
REDIM Keywords(100) AS KeyElement
Keywords(99).Word = "ERASE"
Keywords(99).Count = 2
PRINT "Keyword 99 is "; Keywords(99).Word
PRINT "Count is"; Keywords(99).Count
' Free the space taken by Keywords when you're finished.
ERASE Keywords
END

Sample Output

Keyword 99 is ERASE
Count is 2
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REM Statement Details

Syntax
  REM remark
  ' remark

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.

  Note: Do not use the single quotation form of the REM statement
        in a DATA statement because it will be considered valid data.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REM Statement Programming Example

This example shows two equivalent remark statements. Note that
you must precede a REM statement at the end of a line with a colon.

                                ----- Note -----
    This is not a complete program. Do not run this example in its
    current form.
                                ----------------

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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESET Statement Details

Syntax
  RESET

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There are no programming examples for the RESET statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESTORE Statement Details

Syntax
  RESTORE [{linelabel | linenumber}]

After executing a RESTORE statement without a specified linelabel or
linenumber, 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 label must be in the module-level code. (Note that in the QuickBASIC
environment, DATA statements are automatically moved to the module-level
code.)
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESTORE Statement Programming Example

QCARDS.BAS, the program used in the QuickBASIC tutorial, uses the RESTORE
statement extensively. It is included on the Setup distribution diskette.
To look at the QCARDS.BAS program text and see how the RESTORE statement
is used, load it using the File menu's Open Program command. To run
QCARDS.BAS, you must follow the instructions in the tutorial.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESUME Statement Details

Syntax
  RESUME [0]
  RESUME NEXT
  RESUME {linelabel | linenumber}

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 that was used.
                      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 that was used.
                      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.
  RESUME linelabel    At linelabel
  RESUME linenumber   At linenumber

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 { linelabel | linenumber } statement
must be defined at the module level. As a rule, avoid using a line
label with a RESUME statement. Omitting the line label 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESUME Statement Programming Example

This example has an error-handling routine starting at line 900 which
traps negative arguments to the SQR function.

5 CLS
10 ON ERROR GOTO 900
20 FOR I = 4 TO -2 STEP -1
30     PRINT I, 1 - SQR(I)
40 NEXT
50 END

900 'Error-handling routine
910     PRINT "No negative arguments"
920 RESUME NEXT

Sample Output

4      -1
3      -.7320509
2      -.4142136
1       0
0       1
-1      No negative arguments
-2      No negative arguments
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RETURN Statement Details

Syntax
  RETURN [{linelabel | linenumber}]

Without a line label, 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 label can be used anywhere in a
program, but the GOSUB and corresponding RETURN must be at the same level.

The linelabel or linenumber 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 better structured alternative
        to GOSUB subroutines.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the GOSUB statement programming example, which uses the RETURN
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RIGHT$ Function Details

Syntax
  RIGHT$(stringexpression,n)

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).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RIGHT$ Function Programming Example

This example converts names input in the form "Firstname [Middlename]
Lastname" to the form "Lastname, Firstname [Middlename]".

CLS                                  ' Clear screen
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$                        'Only a last name was input.
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RMDIR Statement Details

Syntax
  RMDIR pathspec

The pathspec is the name of the directory which is to be deleted. The
pathspec 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. However, the syntax in
BASIC cannot be shortened to RD, as in DOS.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RMDIR Statement Programming Example

This example shows how to use RMDIR to remove a subdirectory.

                           ----- Note -----
Do not run this example unless you have a TEMP subdirectory in a directory
SALES, and you want to remove that subdirectory.
                           ----------------

CHDIR "C:SALESTEMP"     'Move to TEMP subdirectory in SALES.
KILL "*.*"                'Remove all files in TEMP.
CHDIR ".."                'Move back up to SALES.
RMDIR "TEMP"              'Remove TEMP subdirectory.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RND Function Details

Syntax
  RND[(n)]

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

  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 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

The following programming examples use the RND function:

  the RANDOMIZE statement programming example, and
  the TYPE...END TYPE statement programming example.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RSET Statement Details

Syntax
  RSET stringvariable=stringexpression

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RSET Statement Programming Example

This example shows the effects of using RSET to assign values to
fixed- and variable-length strings.

DIM TmpStr2 AS STRING * 10
CLS    ' Clear screen
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

Sample Output

         1         2         3
123456789012345678901234567890

             Another
   Another
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RTRIM$ Function Details

Syntax
  RTRIM$(stringexpression)

The stringexpression can be any string expression.

The RTRIM$ function works with both fixed- and variable-length string
variables.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RTRIM$ Function Programming Example

This example shows the effects of RTRIM$ on fixed- and variable-length
strings.

DIM FixStr AS STRING * 10
CLS    ' Clear screen
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*
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RUN Statement Details

Syntax
  RUN [{linenumber | filespec}]

  Argument      Description
  linenumber    The numeric label of the line where execution begins.
                If no argument is given, execution begins at the first
                executable line.
  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 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. QuickBASIC assumes
the .EXE extension for 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 in 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 commandline 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. (The
R option keeps all open data files open.) If you want to run a different
program, but leave open files open, use the CHAIN statement.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RUN Statement Programming Example

This 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

Sample Output

9       7       5       4
0       7       5       4
0       0       5       4
0       0       0       4
0       0       0       0
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SADD Function Details

Syntax
  SADD(stringvariable)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SADD Function Programming 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.

'*** Programming example: SADD function ***
'
' Do not attempt to run this program unless you have already
' separately compiled the C function and placed it in a
' Quick library or linked it to the BASIC program.
'
' Pass a string to a C function using SADD and LEN.
DEFINT A-Z
' Declare the function;
DECLARE FUNCTION MyAsc CDECL(BYVAL A AS INTEGER, BYVAL B AS INTEGER, _
BYVAL C AS INTEGER)

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. */
}

Sample Output

Enter a character position (1-26). Enter -1 to Quit.
? 24
ASCII value:  120 Character: x
? -1
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SCREEN Function Details

Syntax
  SCREEN (row,column[,colorflag])

  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.

If the character at (10,10) is A, in the following examples, then the
function would return 65, the ASCII code for A:

  X=SCREEN(10,10)
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SCREEN Function Programming Example

The following example returns the color attribute of the character in the
upper-left corner of the screen:

X=SCREEN(1,1,1)
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SCREEN Statement Details

Syntax
  SCREEN [mode][,[colorswitch]][,[apage]][,[vpage]]

  Argument      Description
  mode          An integer constant or expression indicating the
                screen mode. See Screen Mode Summary for a list of
                the valid mode numbers.
  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 meaning of the colorswitch argument 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.
                See Adapters and Displays for the number of pages
                available for each graphics adapter.
  vpage         A numeric expression that is the number of the screen
                page being displayed.
See Also
  Screen Mode Summary             Lists capabilities of each screen mode
  Adapters and Displays           Lists the screen modes for specific
                                  combinations of adapters and displays
  Color Numbers and Attributes    Lists the default color attributes for
                                  different screen modes
  Details      ◄Screen Modes►      Adapters      Color Attributes
──────────────────────────────────────────────────────────────────────────────
Summary of Screen Modes

The following table briefly summarizes 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 Graphics Card, Graphics Card Plus and InColor adapters are
supported, but only with monochrome monitors.

  Note: Many screen modes support more than one combination of rows and
        columns on the screen. See the WIDTH statement details for
        more information about changing the number of rows and columns
        on the display.

────────────────────MDPA, CGA, EGA, or VGA Adapter Boards─────────────────────
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 8 x 8 character box size (8 x 14, 9 x 14, or 9 x 16 with EGA or VGA)
  ■ 16 colors assigned to 2 attributes
  ■ 16 colors assigned to any of 16 attributes (with CGA or EGA)
  ■ 64 colors assigned to any of 16 attributes (with EGA or VGA)

─────────────────── CGA, EGA, VGA, or MCGA Adapter Boards─────────────────────
SCREEN 1: 320 x 200 graphics
  ■ 40 x 25 text format, 8 x 8 character box
  ■ 16 background colors and one of two sets of 3 foreground colors assigned
    using COLOR statement with CGA
  ■ 16 colors assigned to 4 attributes with EGA or VGA
SCREEN 2: 640 x 200 graphics
  ■ 80 x 25 text format with character box size of 8 x 8
  ■ 16 colors assigned to 2 attributes with EGA or VGA

──────────────────────────Other Adapter Boards────────────────────────────────
SCREEN 3: Hercules adapter required, monochrome monitor only
  ■ 720 x 348 graphics
  ■ 80 x 25 text format, 9 x 14 character box
  ■ 2 screen pages (1 only if a second display adapter is installed)
  ■ PALETTE statement not supported
SCREEN 4:
  ■ Supports Olivetti (R) Personal Computers models M24, M240, M28,
    M280, M380, M380/C, M380/T and AT&T (R) Personal Computers 6300
    series
  ■ 640 x 400 graphics
  ■ 80 x 25 text format, 8 x 16 character box
  ■ 1 of 16 colors assigned as the foreground color (selected by the
    COLOR statement); background is fixed at black.

Warning: Olivetti personal computers running 3XBOX under OS/2 should avoid
         this screen mode.

──────────────────────────EGA and VGA Adapters────────────────────────────────
SCREEN 7: 320 x 200 graphics
  ■ 40 x 25 text format, character box size 8 x 8
  ■ 32K page size, page ranges are 0-1 (64K), 0-3 (128K), or 0-7 (256K)
  ■ Assignment of 16 colors to any of 16 attributes
SCREEN 8: 640 x 200 graphics
  ■ 80 x 25 text format, 8 x 8 character box
  ■ 64K page size, page ranges are 0 (64K), 0-1 (128K), or 0-3 (246K)
  ■ Assignment of 16 colors to any of 16 attributes
SCREEN 9: 640 x 350 graphics
  ■ 80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box size
  ■ 64K page size, page range is 0 (64K);
    128K page size, page range is 0 (128K) or 0-1 (256K)
  ■ 16 colors assigned to 4 attributes (64K adapter memory), or
    64 colors assigned to 16 attributes (more than 64K adapter memory)

───────────────EGA and VGA Adapters, Monochrome Monitor Only──────────────────
SCREEN 10: 640 x 350 graphics, monochrome monitor only
  ■ 80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box size
  ■ 128K page size, page range is 0 (128K) or 0-1 (256K)
  ■ Up to 9 pseudocolors assigned to 4 attributes

──────────────────────────VGA and MCGA Adapters───────────────────────────────
Screen 11
  ■ 640 x 480 graphics
  ■ 80 x 30 or 80 x 60 text format, character box size of 8 x 16 or 8 x 8
  ■ Assignment of up to 256K colors to 2 attributes
Screen 12
  ■ 640 x 480 graphics
  ■ 80 x 30 or 80 x 60 text format, 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 graphics
  ■ 40 x 25 text format, character box size of 8 x 8
  ■ Assignment of up to 256K colors to up to 256 attributes
  Details      ◄Adapters►      Modes      Color Attributes
──────────────────────────────────────────────────────────────────────────────
Screen Modes, Adapters, and Displays

Scroll through the tables in this topic, which list the screen modes
available for each adapter. If the display device is also a factor in
choosing a screen mode, it is listed.

MDPA Screen Modes

The IBM Monochrome Display and Printer Adapter (MDPA) can be used only with
a monochrome display. Only SCREEN 0, text mode, can be used with the MDPA.

         Rows and
  Mode   Columns    Attributes   Colors   Resolution   Pages

  0      80x25      16           3        720x350      1


Hercules Adapter Screen Modes

         Rows and
  Mode   Columns    Attributes   Colors   Resolution   Pages

  0      80x25      16           1        720x348      2
  3      80x25      16           1        720x348      2

CGA Screen Modes

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.

        Rows and
  Mode  Columns         Colors  Resolution      Pages

  0     40x25           16      320x200         8
        80x25           "       640x200         4

  1     40x25           4       320x200         1

  2     80x25           2       640x200         1


EGA Screen Modes

The IBM Enhanced Graphics Adapter (EGA) may be used with either the IBM
Color Display or the Enhanced Color Display. In 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).

Mode 9 takes full advantage of the capabilities of the Enhanced Color
Display. Mode 9 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.

The table below summarizes the screen modes that can be used with an
EGA.

        Rows and                                 Page
  Mode  Columns  Display(a)  Attributes  Colors  Resolution Size Pages

  0     40x25    C           16          16      320x200    N/A  8
        40x25    E            "          64      320x350    "    "
        40x43    E            "          64      320x350    "    "(b)
        80x25    C            "          16      640x200    "    "(b)
        80x25    E            "          64      640x350    "    "(b)
        80x25    C            "          16      640x200    "    "(b)
        80x25    M            "           3      720x350    "    "(b)
        80x43    E            "          64      640x350    "    4(b)
        80x43    M            "           3      720x350    "    4(b)
  1     40x25    N/A          4          16      320x200    16K  1
  2     80x25    N/A          2          16      640x200    16K  "
  7     40x25    N/A         16          16      320x200    32K  (c)
  8     80x25    N/A         16          16      640x200    64K  (c)
  9(d)  80x25    E            4          64      640x350    64K  1
        80x43    E            4          64      640x350    64K  1
        80x25    E           16          64      640x350   128K  (c)
        80x43    E           16          64      640x350   128K  (c)
 10     80x25    M            4           9      640x350    64K  (e)
        80x43    M            4           9      640x350    64K  (e)
  ___________________________________________________________________
  (a)  Color display,
  E    Enhanced color display,
  M    Monochrome display,
  N/A  Not applicable (either color display or enhanced color display)
  (b)  Pages=Screen memory divided by page size. Eight page maximum,
       one page minimum.
  (c)  Pages=Screen memory divided by 2 divided by page size. Eight
       page maximum, one page minimum.
  (d)  Number of pages is halved with 64K.
  (e)  The first two entries under mode 9 are for an EGA with 64K
       of screen memory. The next two entries assume more than 64K
       of screen memory.

EGA and VGA Adapters with Monochrome Display: SCREEN 10

Only the EGA and VGA can be paired with the IBM Monochrome Display
to run programs in 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.

Default Attributes: SCREEN 10, Monochrome Display

  Attribute     Displayed
  Value         Pseudocolor

  0             Off
  1             On, normal intensity
  2             Blink
  3             On, high intensity


Color Values: SCREEN 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


VGA Screen Modes

The IBM Video Graphics Array (VGA) adapter offers significantly enhanced
text and graphics in all modes.

        Rows and                      Page
  Mode  Columns   Attributes  Colors  Resolution  Size  Pages

  0     40x25     16          64      360x400     N/A   8
        40x43      "           "      320x350     "     "
        40x50      "           "      320x400     "     4
        80x25      "           "      720x400     "     8
        80x43      "           "      640x350     "     4
        80x43      "           3      720x350     "     "
        80x50      "          64      640x400     "     "
        80x50      "           3      720x400     "     "
  1     40x25      4          16      320x200     16K   1
  2     80x25      2           "      640x200     "     "
  7     40x25     16           "      320x200     32K   (a)
  8     80x25      "           "      640x200     64K   (a)
  9     80x25      "          64      640x350    128K   (a)
        80x43      "           "         "        "     (a)
 10     80x25      4           9         "        64K   (b)
        80x43      "           "         "        "     (b)
 11     80x30      2         256K     640x480     "     1
        80x60      "           "         "        "     "
 12     80x30     16           "         "       256K   "
        80x60      "           "         "        "     "
 13     40x25    256            "     320x200     64K   "

_____________________________________________________________________
  (a)   Pages=Screen memory divided by page size. Eight page maximum.
  (b)   Pages=Screen memory divided by 2 divided by page size. Eight
        page maximum.

See the PALETTE statement details for a description of how the VGA
calculates color values.

MCGA Screen Modes

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.

        Rows and                      Page
  Mode  Columns   Attributes  Colors  Resolution  Size  Pages

   0    40x25     16          N/A     320x400     N/A   8
        80x25      "          "       640x400     "     "
   1    40x25      4          "       320x200     16K   1
   2    80x25      2          "       640x200     "     "
  11    80x30      "          256K    640x480     64K   "
        80x60      "          "          "        "     "
  13    40x25    256          "       320x200     "     "


The MCGA uses the same color values as the VGA. For a description of how
the MCGA calculates color values, see the PALETTE statement details.
  Details      ◄Colors►      Modes      Adapters
──────────────────────────────────────────────────────────────────────────────
Attributes and Colors

For various screen modes and display hardware configurations, different
attribute and color settings exist. (See the PALETTE statement details
for a discussion of attribute and color number.) The majority of these
attribute and color configurations are summarized in the tables below.

Default Attributes and Colors for SCREEN Modes 1 and 9(a)

  Attributes  Color                      Monochrome
              Display                    Display
              Number(b)  Color           Number(c)  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
  ___________________________________________________________________
  (a)  EGA with video memory <= 64K.
  (b)  EGA color numbers. VGA and MCGA use color numbers that
       produce visually equivalent colors.
  (c)  Only for mode 0 monochrome.


Default Attributes and Colors for SCREEN Modes 2 and 11

  Attributes    Color                      Monochrome
                Display                    Display
                Number(a)  Color           Number(b)   Color

  0              0         Black           0           Off
  1             15         High-intensity  0           Off
                           white
  ___________________________________________________________________
  (a)  EGA color numbers. VGA and MCGA use color numbers that produce
       visually equivalent colors.
  (b)  Only for mode 0 monochrome.


Default Attributes and Colors for SCREEN Modes 0, 7, 8, 9(a), 12, and 13

  Attributes    Color                      Monochrome
                Display                    Display
                Number(b)  Color           Number(c)    Color

   0             0         Black           0            Off
   1             1         Blue                         Underlined(d)
   2             2         Green           1            On(d)
   3             3         Cyan            1            On(d)
   4             4         Red             1            On(d)
   5             5         Magenta         1            On(d)
   6             6         Brown           1            On(d)
   7             7         White           1            On(d)
   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
  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
  ____________________________________________________________________
  (a)   For VGA. Also for EGA with video memory > 64K.
  (b)   EGA color numbers. VGA and MCGA use color numbers that produce
        visually equivalent colors.
  (c)   Only for mode 0 monochrome.
  (d)   Off when used for background.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See any of the following example programs, which use the SCREEN statement:

  the CIRCLE statement programming example,
  the DRAW statement programming example, or
  the LINE statement programming example.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK Function Details

Syntax
  SEEK(filenumber)

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.

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
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK Function Programming Example

See the SEEK statement programming example, which uses both the SEEK
function and the SEEK statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK Statement Details

Syntax
  SEEK [#]filenumber,position

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.

A SEEK to a negative or zero position produces an error message that reads
"Bad record number." Performing a file write after doing a SEEK beyond the
end of a file extends the file.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK Statement Programming Example

The following program uses a combination of the SEEK function and SEEK
statement to move the file position exactly one record back and rewrite
the record if a variable is true (nonzero).

'*** Programming example for the SEEK function and statement
'
CONST FALSE=0, TRUE=NOT FALSE
'  Define record fields.
TYPE TestRecord
   NameField  AS STRING * 20
   ScoreField AS SINGLE
END TYPE
' Define a variable of the user type.
DIM RecordVar AS TestRecord
'********************************************************************
' This part of the program is an insert whose only function is to
' create a random-access file to be used by the second part of the
' program, which demonstrates the CVSMBF function
'********************************************************************
OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(Rec)
CLS
RESTORE
READ NameField$, ScoreField
I = 0
DO WHILE UCASE$(NameField$) <> "END"
   I = I + 1
   RecordVar.NameField = NameField$
   RecordVar.ScoreField = ScoreField
   PUT #1, I, RecordVar
   READ NameField$, ScoreField
   IF NameField$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
  DATA "John Simmons", 100
  DATA "Allie Simpson", 95
  DATA "Tom Tucker", 72
  DATA "Walt Wagner", 90
  DATA "Mel Zucker", 92
  DATA "END", 0

'  Open the test data file.
'
DIM FileBuffer AS TestRecord
OPEN "TESTDAT2.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
   IF FileBuffer.NameField = "Tom Tucker" THEN
      ReWriteFlag = TRUE
      EXIT FOR
   END IF
NEXT I
'
IF ReWriteFlag = TRUE THEN
   ' Back up file by the length of the record variable that
   ' is used to write to the file.
   FileBuffer.ScoreField = 100
   SEEK #1, SEEK(1) - LEN(RecordVar)
   PUT #1 , , RecordVar
END IF
'
CLOSE #1
KILL "TESTDAT2.DAT"
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SELECT Statement Details

Syntax
  SELECT CASE testexpression
  CASE expressionlist1
    [statementblock-1]
  [CASE expressionlist2
    [statementblock-2]] ...

  [CASE ELSE
    [statementblock-n]]
  END SELECT

  Argument            Description
  testexpression      Any numeric or string expression.

  statementblock-1,   The elements statementblock-1 to
  statementblock-2,   statementblock-n consist of any number of
  statementblock-n    statements on one or 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
                        testexpression.

  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

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 testexpresssion 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.
Lower-case letters have larger ASCII values than upper-case, therefore

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SELECT Statement Programming Examples

There are two SELECT CASE programming examples.

Example 1

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

Sample 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

Example 2

In the following program, the SELECT CASE statement is used to take
different actions based on the ASCII value of a character.

' Function and control key constants
CONST ESC = 27, DOWN = 80, UP = 72, LEFT = 75, RIGHT = 77
CONST HOME = 71, ENDKEY = 79, PGDN = 81, PGUP = 73

DO
    ' Get a function or ASCII key
    DO
        Choice$ = INKEY$
    LOOP WHILE Choice$ = ""

    IF LEN(Choice$) = 1 THEN
        ' Handle ASCII keys
        SELECT CASE ASC(Choice$)
            CASE ESC
                PRINT "Escape key"
                END
            CASE IS < 32, 127
                PRINT "Control code"
            CASE 30 TO 29
                PRINT "Digit: "; Choice$
            CASE 65 TO 90
                PRINT "Uppercase letter: "; Choice$
            CASE 97 TO 122
                PRINT "Lowercase letter: "; Choice$
            CASE ELSE
                PRINT "Punctuation: "; Choice$
        END SELECT

    ELSE
        ' Convert 2-byte extended code to 1-byte ASCII code and handle
        Choice$ = RIGHT$(Choice$, 1)

        SELECT CASE Choice$
            CASE CHR$(DOWN)
                PRINT "DOWN arrow key"
            CASE CHR$(UP)
                PRINT "UP arrow key"
            CASE CHR$(PGDN)
                PRINT "PGDN key"
            CASE CHR$(PGUP)
                PRINT "PGUP key"
            CASE CHR$(HOME)
                PRINT "HOME key"
            CASE CHR$(ENDKEY)
                PRINT "END key"
            CASE CHR$(RIGHT)
                PRINT "RIGHT arrow key"
            CASE CHR$(LEFT)
                PRINT "LEFT arrow key"
            CASE ELSE
                BEEP
        END SELECT
    END IF

LOOP
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SETMEM Function Details

Syntax
  SETMEM(numeric-expression)

The numeric-expression indicates the number of bytes to increase or
decrease the far heap.
  ■ If the numeric-expression is negative, SETMEM decreases the far heap
    by the indicated number of bytes.
  ■ If 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.

  Note: 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SETMEM Function Programming 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 must be 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.


'*** Programming example: SETMEM function ***
'
' Do not attempt to run this program unless you have already
' separately compiled the C function, using the large memory model,
' and placed it in a Quick library or linked it to the BASIC program.
'
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);
}
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SGN Function Details

Syntax
  SGN(numeric-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SGN Function Programming Example

The following program calculates and prints the solution for the input
quadratic (or 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

Sample Output

This equation has two solutions:  .6666667      -.25
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHARED Statement Details

Syntax
  SHARED variable [AS type] [,variable [AS type]]...

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHARED Statement Programming Example

SHARE_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the SHARED statement. To look at the program in the View window and,
optionally, to run it, load the program using the File menu's Open Program
command.

The 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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHELL Statement Details

Syntax
  SHELL [commandstring]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHELL Statement Programming Examples

Example 1

The following example shows how a single SHELL statement starts up a
new COMMAND.COM:

SHELL   'Get a new COMMAND.COM.

Sample 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>

Example 2

SHELL_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the SHELL statement. To look at the program in the View window and,
optionally, to run it, load the program using the File menu's Open Program
command.

The program copies all files modified on a certain date from a specified
directory.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SIN Function Details

Syntax
  SIN(numeric-expression)

The SIN function is calculated with double-precision accuracy when x is a
double-precision value. When x is not double precision, SIN is calculated
with single-precision accuracy.

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

To convert a radian value to degrees, multiply it by 57.2958.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SIN Function Programming 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.

'***Programming example for the SIN function***
CLS
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
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SLEEP Statement Details

Syntax
  SLEEP [seconds]

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 has elapsed.
  ■ A key is pressed.
  ■ An enabled event occurs.

If seconds is zero, or not specified, the program is suspended
indefinitely. Only a keystroke or an enabled event 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SLEEP Statement Programming 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.

CLS                               'Clear the screen
PRINT "Taking a 10 second nap..."
SLEEP 10
PRINT "Awake!"
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SOUND Statement Details

Syntax
  SOUND frequency,duration

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SOUND Statement Programming Example

This program produces a rising and descending glissando:

CLS
FOR I = 440 TO 1000 STEP 5
   SOUND I, I/1000
NEXT
FOR I = 1000 TO 440 STEP -5
  SOUND I, I/1000
NEXT
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPACE$ Function Details

Syntax
  SPACE$(n)

The expression n is rounded to an integer and must be in the range 0-32,767.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPACE$ Function Programming Example

CLS                    ' clear the screen
FOR I=1 TO 5
   X$=SPACE$(I)
   PRINT X$;I
NEXT I

Sample Output

1
 2
  3
   4
    5
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPC Function Details

Syntax
  SPC(n)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPC Function Programming Example

CLS                               'Clear the screen
PRINT "OVER";SPC(15) "THERE"

Sample Output

OVER               THERE
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SQR Function Details

Syntax
  SQR(numeric-expression)

The argument n must be >= 0.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SQR Function Programming Example

The following program plots the graphs of
y = √-x for -9 <= x <  0, and
y = √x  for  0 <= x <= 9:

'*********************************************************************
' Example program for SQR function.
'*********************************************************************
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STATIC Statement Details

Syntax
  STATIC variablelist

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STATIC Statement Programming Examples

STAT_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the STATIC statement. To look at the program in the View window and,
optionally, to run it, load the program using the File menu's Open Program
command.

The program searches for every occurrence of a certain string expression
in a file and replaces that string with another string. 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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STICK Function Details

Syntax
  STICK(n)

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).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STICK Function Programming Example

The following program prints the coordinates of joystick B:

'*** Programming example for STICK function ***
' Do not attempt to run this program unless a joystick is installed
TEMP = STICK(0)
PRINT STICK(2), STICK(3)
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STOP Statement Details

Syntax
  STOP

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There is no programming example for the STOP statement. To see the various
ways QuickBASIC can stop or suspend program execution, look at help
for the Run and Debug Keys topic.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STR$ Function Details

Syntax
  STR$(numeric-expression)

If numeric-expression is positive, the string returned by the STR$ function
contains a leading blank.

The VAL function complements STR$.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STR$ Function Programming Example

The following example uses the STR$ function to convert a number to its
string representation and strips out the leading and trailing blanks that
BASIC ordinarily prints with numeric output.

'*** STR$ function programming example ***
CLS                            ' clear the screen
PRINT "Enter 0 to end."
DO
    INPUT "Find cosine of: ",Num
    IF Num = 0 THEN EXIT DO
    X$ = STR$(Num)
    NumRemBlanks$ = LTRIM$(RTRIM$(X$))
    PRINT "COS(" NumRemBlanks$ ") = " COS(Num)
LOOP

Sample Output

Enter 0 to end.
Find cosine of: 3.1
COS(3.1) = -.9991351
Find cosine of: 0
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRIG Function Details

Syntax
  STRIG(n)

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          -1 if the lower button on joystick A was pressed since
             the last STRIG(0) call, 0 if not

  1          -1 if the lower button on joystick A is currently down,
             0 if not

  2          -1 if the lower button on joystick B was pressed since
             the last STRIG(2) call, 0 if not

  3          -1 if the lower button on joystick B is currently down,
             0 if not

  4          -1 if the upper button on joystick A was pressed since
             the last STRIG(4) call, 0 if not

  5          -1 if the upper button on joystick A is currently down,
             0 if not

  6          -1 if the upper button on joystick B was pressed since
             the last STRIG(6) call, 0 if not

  7          -1 if the upper button on joystick B is currently down,
             0 if not

You can also use event trapping to get information from the joystick
by using the ON STRIG 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRIG Function Programming Example

The following example illustrates STRIG:

' *** STRIG function programming example ***
' Do not attempt to run this program without a joystick installed
'
' 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRIG Statements Details

Syntax
  STRIG(n) ON
  STRIG(n) OFF
  STRIG(n) STOP

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.  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
re-enabled.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There is no programming example for the STRIG event-trapping statements.

See the following event-trapping programming examples and apply the
techniques there to joystick event-trapping:

  a keystroke event trapping program example, or
  a background-music queue event trapping program example.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRING$ Function Details

Syntax
  STRING$(m,n)
  STRING$(m,stringexpression)

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRING$ Function Programming Examples

Example 1

The following example uses STRING$ to create part of a report
heading:

Dash$ = STRING$(10,45)
PRINT Dash$;"MONTHLY REPORT";Dash$

Sample Output

----------MONTHLY REPORT----------


Example 2

The following program uses STRING$ to generate a bar graph:

PRINT TAB(7);"Daily Mean Temperature in Seattle"
'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

Sample Output

Daily Mean Temperature in Seattle

Jan +*****
    |
Mar +***********
    |
May +*********************
    |
Jul +*******************************
    |
Sep +**************************
    |
Nov +***********
    |
    +----+----+----+----+----+----+----+
    35   40   45   50   55   60   65   70
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SUB...END SUB Statement Details

Syntax
  SUB globalname[parameterlist][STATIC]
    [statements]
  [EXIT SUB]
    [statements]
  END SUB

  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,
unlike a FUNCTION, a SUB cannot be used in an expression.

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.

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.

Any subprogram variables or arrays are considered local to that sub-
program, 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SUB...END SUB Statement Programming Examples

SUB_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the SUB...END SUB statement. To look at the program in the View window and,
optionally, to run it, load the program using the File menu's Open Program
command.

The main program calls a subprogram which searches for a given string in
each line of input from a file. When the subprogram finds the string in a
line, it prints the line, along with the number of the line. Notice that
the value of a line number counter is saved between calls because the
STATIC keyword is used on the SUB statement.

Below is sample output from the program:

Pattern to search for? SUB
Line # 9 : SUB Linesearch(Test$,P$) STATIC
Line # 13 : END SUB
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SWAP Statement Details

Syntax
  SWAP variable1,variable2

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 a "Type mismatch" error.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SWAP Statement Programming Example

The following program sorts the elements of a string array in descending
order using a Shell sort. It uses SWAP to exchange array elements that are
out of order.

' Sort the word list using a Shell sort.
Num% = 4
Array$(1) = "New York"
Array$(2) = "Boston"
Array$(3) = "Chicago"
Array$(4) = "Seattle"
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
CLS
FOR I% = 1 TO Num%
    PRINT Array$(I%)
NEXT I%
END

This program could be converted into a useful SUB, which would sort a
string array of any size, by using the SUB...END SUB statements as shown
below:

' 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SYSTEM Statement Details

Syntax
  SYSTEM

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There are no programming examples for the SYSTEM statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAB Function Details

Syntax
  TAB(column)

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. 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAB Function Programming Example

Example 1

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

Sample Output

NAME                    AMOUNT

G.T. JONES              $25.00
H.L. STEVENS            $32.25


Example 2

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"

Sample Output

      one
              two
three
123456789012345678901234567890
                   four
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAN Function Details

Syntax
  TAN(numeric-expression)

TAN is calculated with single-precision accuracy, unless the argument
x is a double-precision value; in that case TAN is calculated with
double-precision accuracy.

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

To convert a radian value to degrees, multiply it by 57.2958.

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).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAN Function Programming 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$=""
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ Function Details

Syntax
  TIME$

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ Function Programming 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$

Sample Output

The time is 11:26:31 AM
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ Statement Details

Syntax
  TIME$=stringexpression

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ Statement Programming Example

The following example sets the current time to 8:00 AM:

'*** TIME$ statement programming example ***
' Do not run this program unless you want to set
' your system clock to 8 a.m.
'
TIME$="08:00:00"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER Function Details

Syntax
  TIMER

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER Function Programming 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.

'*** Programming example for the TIMER function
'
DEFINT A-Z
CONST UNMARK = 0, MARKIT = NOT UNMARK
DIM Mark(10000)
CLS                     'Clear the screen
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

Sample Output

Program took .1601563 seconds to find the 1228 primes
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER Statements Details

Syntax
  TIMER ON
  TIMER OFF
  TIMER STOP

TIMER ON enables timer event trapping by an ON TIMER statement. 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER Statements Programming Example

The following example displays the time of day on line 1, and updates
the display once every three seconds:

'*** Programming example: TIMER statement ***
'To stop the program, press any key
'
TIMER ON
ON TIMER(3) 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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TRON and TROFF Statements Details

Syntax
  TRON
  TROFF

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. See the Debugging Keys        for more
        information.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

There is no programming example for the TRON and TROFF statements. See
the QB Advisor help about the Debugging Keys to see how to trace the flow
of program execution using QuickBASIC 4.50.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TYPE Statement Details

Syntax
  TYPE usertype
    elementname AS typename
    [elementname AS typename]
    .
    .
    .
  END TYPE

  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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TYPE Statement Programming Example

TYPE_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the TYPE...END TYPE statement. To look at the program in the View window
and, optionally, to run it, load the program using the File menu's Open
Program command.

The program 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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UBOUND Function Details

Syntax
  UBOUND(array[,dimension])

The argument dimension is an integer from 1 to the number of dimensions in
the 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UBOUND Function Programming Example

UBO_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the UBOUND and LBOUND functions. To look at the program in the View window
and, optionally, to run it, load the program using the File menu's Open
Program command.

The program shows how LBOUND and UBOUND can be used together in a SUB to
determine the size of an array passed to the SUB by a calling program.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UCASE$ Function Details

Syntax
  UCASE$(string-expression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
─────────────────────────────────────────────────────────────────────────────
UCASE$ Function Programming Example

UCASE_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the UCASE$ function. To look at the program in the View window and,
optionally, to run it, load it using the File menu's Open Program command.

The program contains a FUNCTION, YesQues, that returns a Boolean value
depending on how the user responds. The FUNCTION YesQues uses UCASE$
to make a case-insensitive test of the user's response.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UEVENT Statement Details

Syntax
  UEVENT ON
  UEVENT OFF
  UEVENT STOP

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the ON UEVENT statement programming example, which uses the UEVENT
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UNLOCK Statement Details

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

The UNLOCK statement is used only after a LOCK statement. See the
LOCK statement details for more information.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the LOCK statement programming examples, which use the UNLOCK
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VAL Function Details

Syntax
  VAL(stringexpression)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VAL Function Programming Example

The following program prints the names and addresses of people with
specific telephone area codes.

' Example program for the VAL function
'
' ***This part of the program builds a sample data file
'
OPEN "PHONE.DAT" FOR OUTPUT AS #1
CLS
RESTORE
READ FuName$, ACPhone$
I = 0
DO WHILE UCASE$(FuName$) <> "END"
   I = I + 1
   WRITE #1, FuName$, ACPhone$
   READ FuName$, ACPhone$
   IF FuName$ = "END" THEN EXIT DO
LOOP
CLOSE #1
'
   DATA "Bob Hartzell ","206-378-3223"
   DATA "Alice Provan ","213-884-9700"
   DATA "Alex Landow ","213-456-3111"
   DATA "Walt Riley ","503-248-0048"
   DATA "Georgette Gump ","213-222-2222"
   DATA "END",0,0,0,0,0
'
' *** This part of the program demonstrates the VAL function
'
INPUT "Search for which area (206, 213, or 503): ", Targetarea
OPEN "PHONE.DAT" FOR INPUT AS #1
DO WHILE NOT EOF(1)
   INPUT #1, Nm$, Phonenum$
   'VAL reads everything up to the first non-numeric
   'character ("-" in this case).
   Area = VAL(Phonenum$)
   IF Area = Targetarea THEN
      PRINT
      PRINT Nm$;
      PRINT Phonenum$
   END IF
LOOP
CLOSE
KILL "PHONE.DAT"
END
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VARPTR and VARSEG Functions Details

Syntax
  VARPTR(variablename)
  VARSEG(variablename)

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 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.

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

  Note: 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.

The VARSEG function, combined with VARPTR, replaces the PTR86
subprogram used in previous versions of QuickBASIC.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VARPTR and VARSEG Functions Programming Example

For examples of how to use the VARPTR and VARSEG functions with other
statements, see

  the BSAVE and BLOAD programming examples,
  the CALL ABSOLUTE programming example, or
  the CALL INTERRUPT programming example.

This example program illustrates how to use the VARPTR and VARSEG
functions in a CALL statement to pass a BASIC array to a C function.

'*** Programming example: VARPTR and VARSEG with CALL ***
'
' Do not attempt to run this program unless you have already
' separately compiled the C function with the large-model (/AL)
' switch and placed the object module in a Quick library or linked
' it to the BASIC main program.
'
' BASIC main program passing an array to C function.
'
DEFINT A-Z
'
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]++;
}
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VARPTR$ Function Details

Syntax
  VARPTR$(variablename)

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the following programming examples that use the VARPTR$ function:
  DRAW statement example 2
  PLAY statement example
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VIEW (Graphics) Statement Details

Syntax
  VIEW [[SCREEN] (x1,y1)-(x2,y2) [,[color][,border]]]

  Argument          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 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VIEW (Graphics) Statement Programming Examples

You may use multiple VIEW statements. If the newly described viewport
is not wholly within the previous viewport, the screen can be
re-initialized 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"
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VIEW PRINT Statement Details

Syntax
  VIEW PRINT [topline TO bottomline]

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. For more information,
see the WIDTH statement details.

Statements and functions that operate within the defined text viewport
include CLS, LOCATE, PRINT, and the SCREEN function.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the CLS statement programming example, which uses the VIEW PRINT
statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WAIT Statement Details

Syntax
  WAIT portnumber,and-expression[,xor-expression]

  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.
                         -------------------

The following example program line illustrates the syntax of the WAIT
statement:

WAIT  HandShakePort, 2

This statement will cause QuickBASIC to do an AND operation on the
bit pattern received at DOS I/O port HandShakePort with the bit
pattern represented by 2 (00000010).
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WAIT Statement Programming Example

There is no executable programming example for the WAIT statement.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WIDTH Statement Details

Syntax
  WIDTH [columns][,lines]
  WIDTH {#filenumber | device},width
  WIDTH LPRINT width

Both files and devices can be assigned an output-line width.

  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 the display adapter
                            used and the screen mode (see the SCREEN
                            statement help topic for more information).
                            The number of lines displayed when the program
                            started will determine the default value.

  WIDTH #filenumber,width   Sets the line width of an output device opened
                            as a file (for 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 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.

  WIDTH LPRINT width        Sets to width the line width of the line
                            printer, for use by subsequent LPRINT
                            statements.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WIDTH Statement Programming Example

In the following example, the record width for file #1 (the printer) is set
to different widths:

'*** Programming example that uses WIDTH ***
OPEN "LPT1:" FOR OUTPUT AS #1
Test$ = "1234567890"
WIDTH #1, 3
PRINT #1, Test$
WIDTH #1, 4
PRINT #1, Test$
CLOSE

Sample Output (On a printer)

123
456
789
0
1234
5678
90
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WINDOW Statement Details

Syntax
  WINDOW [[SCREEN] (x1,y1)-(x2,y2)]

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

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WINDOW Statement Programming Example

WINDO_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates
the WINDOW statement. To look at the program in the View window and,
optionally, to run it, load it using the File menu's Open Program command.

The program 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.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE Statement Details

Syntax
  WRITE [expressionlist]

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-line-feed.

The WRITE statement writes numeric values without leading or trailing spaces.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE Statement Programming Example

The following example shows the difference between the PRINT and WRITE
statements:

'*** Example program that uses WRITE ***
CLS                          'clear the screen
A=80 : B=90 : C$="That's all." : D=-1.0E-13
WRITE A,B,C$,D
PRINT A,B,C$,D

Sample Output

80,90,"That's all.",-1E-13
 80            90           That's all.  -1E-13
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE# Statement Details

Syntax
  WRITE #filenumber[,expressionlist]

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE# Statement Programming 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.DAT" FOR OUTPUT AS #1            'Open PRICES.DAT 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

Sample Output

Use the QuickBASIC editor to see what the contents of the file PRICES.DAT
looks like:

  1. From the File menu, choose the Open Program command.
  2. Specify the file name PRICES.DAT in the dialog box.
  3. After you are prompted to save the program, the contents of PRICES.DAT
     will be displayed in the View window:

VCR, remote control         $399.00
"VCR, remote control","$399.00"

  4. To clear the View window, choose the New Program command from the
     File menu.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL or CALLS (Non-BASIC Procedures) Details

Syntax

There are three different forms that can be used to perform this
function:

  CALL name [( call-argumentlist )]
  name [ call-argumentlist ]
  CALLS name [( calls-argumentlist )]

  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 and 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 a
             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 the
        CALL (BASIC) statement for the other syntax.

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.

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.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────

See the VARPTR function programming example, which uses a CALL statement
to invoke a C procedure.
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL ABSOLUTE Statement Details

Syntax
  CALL ABSOLUTE([argumentlist,]integervariable)

  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.

        Also, 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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL ABSOLUTE Statement Programming 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.
AsmBytes:
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
  QuickSCREEN      ◄Details►      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL INTERRUPT Statement Details

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

  Argument       Description
  interruptnum   The DOS interrupt number. It is an integer between
                 0 and 255. See your DOS documentation for informa-
                 tion 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.

CALL INTERRUPT and CALL INTERRUPTX are shipped in a Quick Library
(QB.QLB) and in a conventional library (QB.LIB) on the QuickBASIC
Utilities 1 distribution disk. There is also a header file (QB.BI)
on the disks with the necessary declarations for using these procedures.

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. For information on how to do this, see the
QB command line options table.

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.
  QuickSCREEN      Details     ◄Example►      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL INTERRUPT Statement Programming Example

This example uses INT86OLD to open a file and place some text in it.

' Note:  To use CALL INTERRUPT, you must load the Quick library QB.LIB
'        with QuickBASIC. The program also uses the QB.BI header file.

' 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.
  ◄Shortcut Keys►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
     ┌ Inserting ───────────────────────┐ ┌ Copying ───────────────────┐
     │ Toggle insert/overtype       INS │ │ Selected text     CTRL+INS │
     │ Line above           HOME CTRL+N │ └────────────────────────────┘
     │ Line below             END ENTER │ ┌ Finding ───────────────────┐
     │ From clipboard         SHIFT+INS │ │ Selected text       CTRL+ │
     └──────────────────────────────────┘ │ Repeat find             F3 │
     ┌ Selecting ───────────────────────┐ └────────────────────────────┘
     │ Characters/lines     SHIFT+ARROW │ ┌ Debugging ─────────────────┐
     │ Words           SHIFT+CTRL+ARROW │ │ View output screen      F4 │
     └──────────────────────────────────┘ │ Continue                F5 │
     ┌ Deleting ────────────────────────┐ │ Execute to cursor       F7 │
     │ Current line (save)       CTRL+Y │ │ Toggle breakpoint       F9 │
     │ To end of line (save)   CTRL+Q Y │ │ Single step             F8 │
     │ Selected text (save)   SHIFT+DEL │ │ Procedure step         F10 │
     │ Selected text (no save)      DEL │ │ Instant Watch     SHIFT+F9 │
     └──────────────────────────────────┘ └────────────────────────────┘
  ◄Editing Keys►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Editing Keys

The QuickBASIC smart editor recognizes key stroke combinations familiar to
users of other Microsoft programs, such as Microsoft Word, as well as
WordStar key combinations. In the editing keys tables, the WordStar
equivalent keys are listed in the right column.

      Cursor-movement keys
      Text scrolling keys
      Keys that select text to be changed by next command
      Keys that insert and copy text
      Keys that delete text
  Editing Keys   ◄Cursor Movement►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Character left                             LEFT                CTRL+S
 Character right                            RIGHT               CTRL+D
 Word left                                  CTRL+LEFT           CTRL+A
 Word right                                 CTRL+RIGHT          CTRL+F
 Line up                                    UP                  CTRL+E
 Line down                                  DOWN                CTRL+X
──────────────────────────────────────────────────────────────────────────────
 First indentation level of current line    HOME
 Beginning of current line                                      CTRL+Q+S
 Beginning of next line                     CTRL+ENTER          CTRL+J
 End of line                                END                 CTRL+Q+D
──────────────────────────────────────────────────────────────────────────────
 Top of window                                                  CTRL+Q+E
 Bottom of window                                               CTRL+Q+X
──────────────────────────────────────────────────────────────────────────────
 Beginning of module/procedure              CTRL+HOME           CTRL+Q+R
 End of module/procedure                    CTRL+END            CTRL+Q+C
──────────────────────────────────────────────────────────────────────────────
 Set place marker number 'n' (where n = 0-3)                    CTRL+K+n
 Move to place marker number 'n'                                CTRL+Q+n
──────────────────────────────────────────────────────────────────────────────
  Editing Keys   ◄Scrolling►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
     Line up                              CTRL+UP               CTRL+W
     Line down                            CTRL+DOWN             CTRL+Z
     Page up                              PGUP                  CTRL+R
     Page down                            PGDN                  CTRL+C
──────────────────────────────────────────────────────────────────────────────
     Left one window                      CTRL+PGUP
     Right one window                     CTRL+PGDN
──────────────────────────────────────────────────────────────────────────────
  Editing Keys   ◄Select Text►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
     Character left                          SHIFT+LEFT
     Character right                         SHIFT+RIGHT
     Word left                               SHIFT+CTRL+LEFT
     Word right                              SHIFT+CTRL+RIGHT
──────────────────────────────────────────────────────────────────────────────
     Current line                            SHIFT+DOWN
     Line above                              SHIFT+UP
     Screen up                               SHIFT+PGUP
     Screen down                             SHIFT+PGDN
     To beginning of module/procedure        SHIFT+CTRL+HOME
     To end of module/procedure              SHIFT+CTRL+END
──────────────────────────────────────────────────────────────────────────────
  Editing Keys   ◄Insert and Copy►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Keyboard insert mode on or off                     INS            CTRL+V
──────────────────────────────────────────────────────────────────────────────
 Copy selected text to the Clipboard, keeping it    CTRL+INS
──────────────────────────────────────────────────────────────────────────────
 Copy selected text to Clipboard, deleting it       SHIFT+DEL
 Copy current line to Clipboard, deleting it                       CTRL+Y
 Copy to end of line to Clipboard, deleting it                     CTRL+Q+Y
──────────────────────────────────────────────────────────────────────────────
 Insert contents of Clipboard                       SHIFT+INS
 Insert blank line below                            END ENTER
 Insert blank line above                                           HOME+CTRL+N
──────────────────────────────────────────────────────────────────────────────
  Editing Keys   ◄Delete►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Delete character to left of cursor                 BKSP           CTRL+H
 Delete character at cursor                         DEL            CTRL+G
 Delete rest of word cursor is on                                  CTRL+T
──────────────────────────────────────────────────────────────────────────────
 Delete selected text                               DEL            CTRL+G
 Delete leading spaces from selected lines          SHIFT+TAB
──────────────────────────────────────────────────────────────────────────────
  ◄Debugging Keys►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Start program execution from beginning                    SHIFT+F5
 Continue program execution from current statement         F5
 Execute program to current cursor position                F7
──────────────────────────────────────────────────────────────────────────────
 Execute next program statement as a single step           F8
 Single step, tracing around a procedure call              F10
 Trace execution history backward                          SHIFT+F8
 Trace execution history forward                           SHIFT+F10
──────────────────────────────────────────────────────────────────────────────
 Toggle the Debug menu Breakpoint command                  F9
 Instant Watch                                             SHIFT+F9
 (with mouse, the Instant Watch shortcut is SHIFT+Right mouse button)
──────────────────────────────────────────────────────────────────────────────
  ◄View Keys►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Toggle display of the output screen and the View window           F4
──────────────────────────────────────────────────────────────────────────────
 Display a list of loaded SUBs, modules, and files                 F2
 Display the next procedure                                        SHIFT+F2
 Display the previous procedure                                    CTRL+F2
──────────────────────────────────────────────────────────────────────────────
 Make the next window the active window                            F6
 Make the previous window the active window                        SHIFT+F6
──────────────────────────────────────────────────────────────────────────────
 Toggle between multiple windows and full screen active window     CTRL+F10
 Increase size of active window                                    ALT+PLUS
 Decrease size of active window                                    ALT+MINUS
──────────────────────────────────────────────────────────────────────────────
  ◄Help Keys►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Look at help on the item where the cursor is located       F1 (or click right
                                                                mouse button)
 Clear help from the screen                                 ESC
──────────────────────────────────────────────────────────────────────────────
 Look at Help on Help                                       SHIFT+F1
 Look at help through Help menu commands                    ALT+H
──────────────────────────────────────────────────────────────────────────────
 Move cursor to next hyperlink                              TAB
 Move cursor to previous hyperlink                          SHIFT+TAB
 Move cursor to next hyperlink with starting character      character
 Move cursor to previous hyperlink with starting character  SHIFT+character
 Look at previous hyperlink topic (repeat up to 20 times)   ALT+F1
──────────────────────────────────────────────────────────────────────────────
 Look at help topic stored next in the Help file            CTRL+F1
 Look at help topic stored previously in the Help file      SHIFT+CTRL+F1
──────────────────────────────────────────────────────────────────────────────
  ◄Limits to QuickBASIC►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Limits to QuickBASIC

There are certain limits to the maximum and minimum sizes and values of
program objects in QuickBASIC.

  Limits Topic                         Maximum and Minimum
  Names, Strings, and Numbers        Variable name length, string length,
                                       numeric values.
  Arrays                             Size, number of dimensions,
                                       subscript values.
  Procedures and Files               Size, number of arguments, number of
                                       records, error message numbers.
  Editing                            Number of characters in various text
                                       boxes, number of lines in various
                                       windows.
  Limits to QuickBASIC   ◄Names, Strings and Numbers►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Limits to QuickBASIC - Names, Strings, and Numbers
                                       Maximum                 Minimum
Variable name length                   40 characters           1 character
String length                          32,767 characters       0 characters
Integers                               32,767                 -32,768
Long Integers                          2,147,483,647          -2,147,483,648
Single precision numbers (positive)    3.402823 E+38           1.401298 E-45
Single precision numbers (negative)   -1.401298 E-45          -3.402823 E+38
Double precision numbers (positive)
                          Maximum:     1.797693134862315 D+308
                          Minimum:     4.940656458412465 D-324
Double precision (negative)
                          Maximum:    -4.940656458412465 D-324
                          Minimum:    -1.797693134862315 D+308
  Limits to QuickBASIC   ◄Arrays►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Limits to QuickBASIC - Arrays

                                       Maximum                 Minimum
Array size (all elements)
  Static                               65,535 bytes (64 K)     1
  Dynamic                              Available memory
Number of dimensions allowed           60                      1
Dimensions allowed if unspecified      8                       1
Array subscript value                  32,767                 -32,768

  Note: The maximum range between array subscript values is 32,767
  Limits to QuickBASIC   ◄Files and Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Limits to QuickBASIC - Procedures and Files
                                       Maximum                 Minimum
Procedure size (interpreted)           65,535 bytes (64 K)     0
Number of arguments passed             60 interpreted          0
Nesting of include files               5 levels                0
Module size (compiled)                 65,535 bytes (64 K)     0
Data file numbers                      255                     1
Data file record number                2,147,483,647           1
Data file record size (bytes)          32,767 bytes (32 K)     1 byte
Data file size                         Available disk space    0
Path names                             127 characters          1 character
Error message numbers                  255                     1
  Limits to QuickBASIC   ◄Editing►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Limits to QuickBASIC - Editing
                                       Maximum                 Minimum
Text box entry                         127 characters          0 characters
Search for string                      79 characters           1 character
Change to string                       39 characters           0 characters
Place markers                          4                       0
Watchpoints and/or watch expressions   8                       0
Number of lines in Immediate window    10                      0
Characters in View window on one line  255                     0
Length of COMMAND$ string              124 characters          0 characters
  ◄Syntax Notation►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
How to Read On-line Help Syntax Notation

KEYWORDS               Items in capital letters indicate BASIC keywords.
                       Keywords are a required part of the statement syntax,
                       unless they are enclosed in brackets. You must spell
                       keywords correctly.
placeholders           Items in lowercase are placeholders for information
                       you must supply in the statement, such as a filename.
[optional item]        Items inside square brackets do not need to be used
                       in the statement.
{choice1 | choice2}    Braces and a vertical bar indicate a choice between
                       two or more items.  You must use one of the items in
                       the statement unless the braces are enclosed in
                       square brackets.

IMPORTANT:  The uppercase and lowercase syntax notation conventions are
            used to help you read the syntax rules for a statement, and
            are NOT capitalization rules you must type in.

One other notation convention that is used is the three-dot ellipsis:

   item, item, ...      Means more of the preceding items can be used
                        in a single-line statement.
   beginning KEYWORD
   .                    used to describe multi-line statements
   .                    (or block-structured statements).  Means
   .                    that other statements can be used between
   ending KEYWORD       the beginning and the end of the block.


Here is an example of using the PRINT command syntax:

  Syntax:
    PRINT [expressionlist][{,|;}]

  Given the syntax rule above, these are all syntactically correct
  PRINT statements:
    PRINT
    PRINT x
    PRINT x, y + 1
    PRINT x,
    PRINT x;
    PRINT x + y + z, a - 1, b / 2;

  And there are many, many more.
  ◄Programming Tasks►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Programmer's Task List of BASIC Statements and Functions

Programming Task                        Example Keywords in this List
Build loops and decision structures   FOR...NEXT, DO...LOOP, IF...THEN,
                                        SELECT
Define and call procedures            DECLARE, FUNCTION...END FUNCTION,
                                        SUB...END SUB, CALL
Device input/output                   PRINT, PRINT USING, LPRINT, INPUT$
File input/output                     OPEN, WRITE #, INPUT #, GET, PUT, EOF
Manipulate and transform strings      LEFT$, MID$, RIGHT$, LEN, INSTR
Display graphic images                SCREEN, DRAW, COLOR, PALETTE, PAINT
Set traps for events and errors       ON KEY GOSUB, ON ERROR GOTO, RESUME
  Programming Tasks   ◄Control Flow►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements Used in Looping and Decision Making

Task               Statement            Action

Looping            FOR...NEXT        Repeats statements between FOR and
                                     NEXT a specific number of times

                   EXIT FOR          Provides an alternative way to
                                     exit a FOR...NEXT loop

                   DO...LOOP         Repeats statements between DO and
                                     LOOP, either until a given condition
                                     is true (DO...LOOP UNTIL condition),
                                     or while a given condition is true
                                     (DO...LOOP WHILE condition)

                   EXIT DO           Provides an alternative way to exit
                                     a DO...LOOP loop

                   WHILE...WEND      Repeats statements between WHILE and
                                     WEND while a given condition is true
                                     (similar to DO WHILE condition...LOOP)

Making decisions   IF...THEN...ELSE  Conditionally executes or branches to
                                     different statements

                   SELECT CASE       Conditionally executes different
                                     statements
  Programming Tasks   ◄Procedures►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements Used to Define, Call and Share Data Between Procedures

Task              Statement                Action

Defining a        FUNCTION...END FUNCTION  Mark the beginning and end,
procedure                                  respectively, of a FUNCTION
                                           procedure

                  SUB...END SUB            Mark the beginning and end,
                                           respectively, of a SUB procedure

Calling a         CALL                     Transfers control to a BASIC
procedure                                  SUB procedure, or to a procedure
                                           written in another programming
                                           language and compiled separately.
                                           (The CALL keyword is optional.)

Exiting from      EXIT FUNCTION            Provides an alternative way to
a procedure                                exit a FUNCTION procedure

                  EXIT SUB                 Provides an alternative way to
                                           exit a SUB procedure

Referencing       DECLARE                  Declares a FUNCTION or SUB and,
a procedure                                optionally, specifies the number
before it is                               and type of its parameters
defined

Sharing           COMMON                   Shares variables among separate
variables                                  modules. When used with the
among modules,                             SHARED attribute, it shares
procedures,                                variables among different
or programs                                procedures in the same module.
                                           Also, passes variable values from
                                           current program to new program
                                           when control is transferred with
                                           the CHAIN statement.

                  SHARED                   When used with the COMMON, DIM,
                                           or REDIM statement summary
                                           statements at the module level
                                           (for example, DIM SHARED),
                                           shares variables with every
                                           SUB or FUNCTION in a single
                                           module.
                                           When used by itself within a
                                           procedure, shares variables
                                           between that procedure and
                                           the module-level code.

Preserving        STATIC                   Forces variables to be local
variable                                   to a procedure or DEF FN function
values                                     and preserves the value stored
                                           in the variable if the procedure
                                           or function is exited, then
                                           called again

Defining a        DEF FN...END DEF         Mark the beginning and end,
multiline                                  respectively, of a multiline
function                                   DEF FN function. (This is the
                                           old style for functions in
                                           BASIC - FUNCTION procedures
                                           provide a powerful alternative.)

Exiting from      EXIT DEF                 Provides an alternative way to
a multiline                                exit a multiline DEF FN function
function

Calling a         GOSUB                    Transfers control to a specific
BASIC                                      line in a module. Control is
subroutine                                 returned from the subroutine to
                                           the line following the GOSUB
                                           statement with a RETURN statement
                                           (This is the old style for
                                           subroutines in BASIC - SUB
                                           procedures provide a powerful
                                           alternative.)

Transferring      CHAIN                    Transfers control from current
to another                                 program in memory to another
program                                    program; use COMMON to pass
                                           variables to the new program
  Programming Tasks   ◄Device I/O►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements and Functions Used for Device I/O

                            Statement or
Task                        Function         Action

Printing text (ASCII        PRINT            Outputs text to the screen
characters) on the
screen

                            PRINT USING      Outputs formatted text to
                                             the screen

Changing the width          WIDTH            Changes the width of the
of the output line                           screen to either 40 columns
                                             or 80 columns; and, on
                                             computers with an EGA or VGA,
                                             controls the number of lines
                                             on the screen (25 or 43)

                            WIDTH "SCRN:"    Assigns a maximum length to
                                             lines output to the screen
                                             when used before an OPEN
                                             "SCRN:" statement

Getting input from          INKEY$           Reads a character from the
the keyboard                                 keyboard

                            INPUT$           Reads a specified number of
                                             characters from the keyboard
                                             and stores them in a single
                                             string variable

                            INPUT            Reads input from the keyboard
                                             and stores it in a list of
                                             variables

                            LINE INPUT       Reads a line of input from
                                             the keyboard and stores it
                                             in a single string variable

Positioning the cursor      LOCATE           Moves the cursor to a given
on the screen                                row and column

                            SPC              Skips spaces in printed output

                            TAB              Displays printed output in a
                                             given column

Getting information about   CSRLIN           Tells which row the cursor
the cursor's location                        is in

                            POS(n)           Tells which column the cursor
                                             is in

Creating a text viewport    VIEW PRINT       Sets the top and bottom rows
                                             for displaying text output
  Programming Tasks   ◄File I/O►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements and Functions Used for File I/O

                            Statement or
Task                        Function         Action

Creating a new file or      OPEN             Opens a file for retrieving
accessing an existing                        or storing records (I/O)
file

Closing a file              CLOSE            Ends I/O to a file

Storing data in a file      PRINT #          Stores a list of variables as
                                             record fields in a previously
                                             opened sequential file

                            PRINT USING #    Similar to PRINT #, except
                                             PRINT USING # formats the
                                             record fields

                            WRITE #          Stores a list of variables as
                                             record fields in a previously
                                             opened sequential file

                            WIDTH            Specifies a standard length
                                             for each record in a
                                             sequential file

                            PUT              Stores the contents of a
                                             user-defined variable in a
                                             previously opened binary or
                                             random-access file

Retrieving data             INPUT #          Reads fields from a record
from a file                                  and assigns each field in the
                                             record to a program variable
                                             (sequential files)

                            INPUT$           Reads a string of characters
                                             from a file

                            LINE INPUT #     Reads a record from a
                                             sequential file and stores it
                                             in a single string variable

                            GET              Reads data from a binary or
                                             random-access file and
                                             assigns the data to elements
                                             of a user-defined variable

Managing files on disk      FILES            Prints a listing of the files
                                             in a specified directory

                            FREEFILE         Returns the next available
                                             file number

                            KILL             Deletes a file from the disk

                            NAME             Changes a file's name

Getting information         EOF              Tests whether all of the data
about a file                                 have been read from a file

                            FILEATTR         Returns the number assigned
                                             by the operating system to an
                                             open file and a number that
                                             indicates the mode in which
                                             the file was opened (INPUT,
                                             OUTPUT, APPEND, BINARY, or
                                             RANDOM)

                            LOC              Gives the current position
                                             within a file. With binary
                                             access, this is the byte
                                             position. With sequential
                                             access, this is the byte
                                             position divided by 128.
                                             With random access, this
                                             is the record number of the
                                             last record read or written.

                            LOF              Gives the number of bytes
                                             in an open file

                            SEEK (function)  Gives the location where the
                                             next I/O operation will take
                                             place. With random access,
                                             this is the number of the
                                             next record to be read or
                                             written. With all other kinds
                                             of file access, this is the
                                             byte position of the next byte
                                             to be read or written.

Moving around in a file     SEEK (statement) Sets the byte position for
                                             the next read or write
                                             operation in an open file
  Programming Tasks   ◄String Manipulation►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements and Functions Used for String Manipulation

                        Statement or
Task                    Function                        Action

Getting part of         LEFT$              Returns a given number of
a string                                   characters from the left side
                                           of a string

                        RIGHT$             Returns a given number of
                                           characters from the right side
                                           of a string

                        LTRIM$             Returns a copy of a string with
                                           leading blank spaces stripped
                                           away

                        RTRIM$             Returns a copy of a string with
                                           trailing blank spaces stripped
                                           away

                        MID$(function)     Returns a given number of
                                           characters from anywhere in a
                                           string

Searching strings       INSTR              Searches for a string within
                                           another string

Converting to           LCASE$             Returns a copy of a string with
uppercase or                               all uppercase letters (A-Z)
lowercase                                  converted to lower-case letters
letters                                    (a-z); leaves lowercase letters
                                           and other characters unchanged

                        UCASE$             Returns a copy of a string with
                                           all lowercase letters (a-z)
                                           converted to upper-case letters
                                           (A-Z); leaves uppercase letters
                                           and other characters unchanged

Changing strings        MID$(statement)    Replaces part of a string with
                                           another string

                        LSET               Left justifies a string within
                                           a fixed-length string

                        RSET               Right justifies a string within
                                           a fixed-length string

Converting numbers to   STR$               Returns the string representation
strings, and strings                       of the value of a numeric
to numbers                                 expression

                        VAL                Returns the numeric value of a
                                           string expression

Converting numbers      CVtype             Changes numbers stored as strings
to data-file strings                       back to Microsoft Binary format
and data-file strings                      numbers in programs working with
to numbers                                 random-access files created with
                                           older versions of BASIC

                        CVtypeMBF          Changes numbers stored as
                                           Microsoft Binary format strings
                                           to IEEE-format numbers

                        MKtype$            Changes Microsoft Binary format
                                           numbers to strings suitable for
                                           storing in random-access files
                                           created with older versions of
                                           BASIC

                        MKtypeMBF$         Changes IEEE-format numbers to
                                           Microsoft Binary format strings

Creating strings of     SPACE$             Returns a string of blank
repeating characters                       characters

                        STRING$            Returns a string consisting of
                                           one repeated character

Getting the length      LEN                Tells how many characters are
of a string                                in a string

Working with            ASC                Returns the ASCII value of the
ASCII values                               given character

                        CHR$               Returns the character with the
                                           given ASCII value
  Programming Tasks   ◄Graphics►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements and Functions Used for Displaying Graphics Images

                        Statement or
Task                    Function                        Action

Setting                 SCREEN        Specifies a BASIC screen mode, which
screen-display                        determines screen characteristics such
characteristics                       as resolution and ranges for color
                                      numbers

Plotting or erasing     PSET          Gives a pixel on the screen a specified
a single point                        color using the screen's foreground
                                      color by default

                        PRESET        Gives a pixel on the screen a specified
                                      color using the screen's background
                                      color by default, effectively erasing
                                      the pixel

Drawing simple          LINE          Draws a straight line or a box
shapes on the
screen                  CIRCLE        Draws a circle or ellipse

                        DRAW          Combines many of the features of
                                      other BASIC graphics statements
                                      (drawing lines, moving the graphics
                                      cursor, scaling images) into an
                                      all-in-one graphics macro language

Defining screen         VIEW          Specifies a rectangle on the screen
coordinates                           (or viewport) as the area for
                                      graphics output

                        WINDOW        Allows the user to choose new view
                                      coordinates for a viewport on the
                                      screen

                        PMAP          Maps physical pixel coordinates to
                                      view coordinates specified by the user
                                      in the current window, or vice versa

                        POINT(number) Returns the current physical or view
                                      coordinates of the graphics cursor,
                                      depending on the value for number

Using color             COLOR         Sets the default colors used in
                                      graphics output

                        PALETTE       Assigns different colors to color
                                      numbers. Works only on systems
                                      equipped with an EGA or VGA.

                        POINT(x,y)    Returns the color number of a
                                      single pixel whose screen coordinates
                                      are x and y

Painting enclosed       PAINT         Fills an area on the screen with
shapes                                a color or pattern

Animating               GET           Copies a rectangular area on the
                                      screen by translating the image to
                                      numeric data and storing the data
                                      in a numeric array

                        PUT           Displays an image on the screen
                                      that was previously copied with
                                      GET

                        PCOPY         Copies one screen page to another
  Programming Tasks   ◄Trapping►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
Statements and Functions Used for Trapping Events and Errors

Task               Statement or Function                Action

Trapping errors    ON ERROR GOTO line       Causes a program to branch to
while a program                             the given line where line
is running                                  refers either to a line number
                                            or line label. Branching takes
                                            place whenever an error occurs
                                            during execution.

                   RESUME                   Returns control to the program
                                            after executing an error-handling
                                            routine. The program resumes at
                                            either the statement causing the
                                            error (RESUME [0]), the statement
                                            after the one causing the error
                                            (RESUME NEXT), or the line iden-
                                            tified by line (RESUME line).

Getting            ERR                      Returns the code for an error
error-status                                that occurs at run time
data
                   ERL                      Returns the number of the line
                                            on which an error occurred
                                            (useful only if program has
                                            line numbers)

                   ERDEV                    Returns a device-specific error
                                            code for the last device (such
                                            as a printer) for which DOS
                                            detected an error

                   ERDEV$                   Returns the name of the last
                                            device for which DOS detected
                                            an error

Defining your      ERROR                    Simulates the occurrence of
own error codes                             a BASIC error; can also be used
                                            to define an error not trapped
                                            by BASIC

Trapping events    ON event GOSUB line      Causes a branch to the
while a program                             subroutine starting with line,
is running                                  where line refers either to a
                                            line number or line label,
                                            whenever the given event occurs
                                            during execution.

                   event ON                 Enables trapping of the given
                                            event

                   event OFF                Disables trapping of the given
                                            event

                   event STOP               Suspends trapping of the given
                                            event

                   RETURN                   Returns control to the program
                                            after executing an event-handling
                                            subroutine. The program resumes
                                            at the statement immediately
                                            following the place in the
                                            program where the event occurred
                                            (RETURN), or the line that is
                                            identified by line (RETURN line).
           Regular ASCII Chart (character codes 0 - 127)
000   (nul)  016 ► (dle)  032 sp  048 0  064 @  080 P  096 `  112 p
001 ☺ (soh)  017 ◄ (dc1)  033 !   049 1  065 A  081 Q  097 a  113 q
002 ☻ (stx)  018 ↕ (dc2)  034 "   050 2  066 B  082 R  098 b  114 r
003 ♥ (etx)  019 ‼ (dc3)  035 #   051 3  067 C  083 S  099 c  115 s
004 ♦ (eot)  020 ¶ (dc4)  036 $   052 4  068 D  084 T  100 d  116 t
005 ♣ (enq)  021 § (nak)  037 %   053 5  069 E  085 U  101 e  117 u
006 ♠ (ack)  022 ▬ (syn)  038 &   054 6  070 F  086 V  102 f  118 v
007 • (bel)  023 ↨ (etb)  039 '   055 7  071 G  087 W  103 g  119 w
008 ◘ (bs)   024 ↑ (can)  040 (   056 8  072 H  088 X  104 h  120 x
009   (tab)  025 ↓ (em)   041 )   057 9  073 I  089 Y  105 i  121 y
010   (lf)   026   (eof)  042 *   058 :  074 J  090 Z  106 j  122 z
011 ♂ (vt)   027 ← (esc)  043 +   059 ;  075 K  091 [  107 k  123 {
012 ♀ (np)   028 ∟ (fs)   044 ,   060 <  076 L  092   108 l  124 |
013   (cr)   029 ↔ (gs)   045 -   061 =  077 M  093 ]  109 m  125 }
014 ♫ (so)   030 ▲ (rs)   046 .   062 >  078 N  094 ^  110 n  126 ~
015 ☼ (si)   031 ▼ (us)   047 /   063 ?  079 O  095 _  111 o  127 ⌂

            Extended ASCII Chart (character codes 128 - 255)
128 Ç      144 É      160 á    176 ░    192 └    208 ╨    224 α   240 ≡
129 ü      145 æ      161 í    177 ▒    193 ┴    209 ╤    225 ß   241 ±
130 é      146 Æ      162 ó    178 ▓    194 ┬    210 ╥    226 Γ   242 ≥
131 â      147 ô      163 ú    179 │    195 ├    211 ╙    227 π   243 ≤
132 ä      148 ö      164 ñ    180 ┤    196 ─    212 ╘    228 Σ   244 ⌠
133 à      149 ò      165 Ñ    181 ╡    197 ┼    213 ╒    229 σ   245 ⌡
134 å      150 û      166 ª    182 ╢    198 ╞    214 ╓    230 µ   246 ÷
135 ç      151 ù      167 º    183 ╖    199 ╟    215 ╫    231 τ   247 ≈
136 ê      152 ÿ      168 ¿    184 ╕    200 ╚    216 ╪    232 Φ   248 °
137 ë      153 Ö      169 ⌐    185 ╣    201 ╔    217 ┘    233 Θ   249 ∙
138 è      154 Ü      170 ¬    186 ║    202 ╩    218 ┌    234 Ω   250 ·
139 ï      155 ¢      171 ½    187 ╗    203 ╦    219 █    235 δ   251 √
140 î      156 £      172 ¼    188 ╝    204 ╠    220 ▄    236 ∞   252 ⁿ
141 ì      157 ¥      173 ¡    189 ╜    205 ═    221 ▌    237 φ   253 ²
142 Ä      158 ₧      174 «    190 ╛    206 ╬    222 ▐    238 ε   254 ■
143 Å      159 ƒ      175 »    191 ┐    207 ╧    223 ▀    239 ∩   255
QuickBASIC has stopped doing an item-by-item translation
of the program line at the highlighted item. The error
is ordinarily to the left of the item. You could

  a. Substitute one of the items suggested in the dialog
     box, immediately to the left of the highlighted item

  b. Correct any misspelled keywords to the left of the
     highlighted item.

  c. If you need to compare the structure of the problem
     statement with the correct structure, move the cursor
     to a keyword in the statement and press F1. The
     correct structure (or syntax) will appear in the
     Help window.
  ■ Press ESC to enter the QuickBASIC programming
    environment.

  ■ Press ENTER to look at the QuickBASIC Survival Guide
    before you enter the programming environment. It
    shows you how to perform various actions in the
    QuickBASIC environment with the mouse and keyboard.
    For example, how to
      - pull down a menu,
      - choose a command, or
      - use on-line help

  Tip: The Survival Guide is also available from the
       Help menu Contents command.
Use to
    ■ Create new programs
    ■ Load and save programs or parts of programs
    ■ Print files or partial files
    ■ Use DOS file commands
    ■ Exit QuickBASIC
Use to
    ■ Delete (or "cut") text
    ■ Copy text
    ■ Move ("cut and paste") text

With Full menus, you can also
    ■ Reverse (or "undo") your last edit
    ■ Erase text without adding it to the "clipboard"
    ■ Create new SUB and FUNCTION procedures
Use to view
    ■ SUB and FUNCTION procedures
    ■ Include files
    ■ The output screen
Use to search for text within
    ■ The active window only
    ■ The entire module currently displayed
    ■ All loaded modules
Use to
    ■ Execute a loaded program
    ■ Continue a suspended program
    ■ Clear variables from memory before running
    ■ Create an executable (.EXE) file
    ■ Define the main module of a multimodule program.

 Tip: Use the Debug menu first to set up useful conditions
      such as watches, then use the Run menu.
Use to help get your programs running correctly by
    ■ Opening a Watch window that shows how variables'
      values change as your program runs
    ■ Setting breakpoints that suspend program execution
      so you can see variables' values

 Tip: Use the shortcut keys SHIFT+F9 to create an Instant
      Watch and F9 to toggle a breakpoint on and off.
Use when debugging a program with procedure calls to
    ■ Review the procedures your program executed before
      stopping because of an error, a breakpoint or
      watchpoint, or your pressing CTRL+BREAK
    ■ View the program text for any named procedure by
      choosing its name from the menu

Procedures are displayed in the order executed, with the
most recently called on top.
The Calls menu shows the last eight procedure calls executed
prior to an untrapped error, a breakpoint or watchpoint, or
your pressing CTRL+BREAK.

The called procedures are arranged in the order of
execution, with the most recent on top. To view the program
text for any listed procedures, choose the procedure name
from the menu.

Tip: You can use the list of procedures in the Calls
     menu to control further program  execution, gradually
     "backing out" of the execution stack:

1. Choose a procedure name from Calls.
2. When the program text is displayed, the cursor will be on
   the line following the call that led to the point
   execution halted.
3. Press F7 to restart execution from that point to the
   cursor location.
4. Use the Watch window to look at variable values
   returned from procedures lower in the stack.
Use to control
    ■ The appearance of screen displays
    ■ The search paths used to find files
    ■ The function of the right mouse button
    ■ The toggling of the Full Menus and Syntax Checking
      options.

Options settings are saved and remain in effect the next
time you start QuickBASIC.
Use to get
    ■ Help on BASIC language keywords
    ■ General information on QuickBASIC programming
    ■ Context-sensitive help based on the current cursor
      location
    ■ More instructions on how to use help

To use these commands now
    1. Press ESC to return to the Help menu
    2. Use the DIRECTION keys to select a command
    3. Press ENTER
Use to clear memory before starting to write a new program.
A dialog box may appear if a program is already in memory.
Then
    ■ Choose <Yes> to save the program
    ■ Choose <No> to clear without saving
    ■ Choose <Cancel> if you change your mind

 Tip: Use the Open Program command to clear memory and load
      an existing program.
Use to clear memory and load an existing program from disk
so you can run it or make changes to it.

 Tip: Use the New Program command to clear memory before
      typing in a completely new program.
Use to clear memory and load an existing program from disk.
┌──────────Open Program───────────┐ To load a program from
│                                 │ the current directory:
│ File Name: ▒▒▒▒▒▒▒▒ ◄─────────────────┐
│                                 │     │
│ C:MYPROGS ◄──current directory │   Type a file name
│                                 │   here, or
│      Files          Dirs/Drives │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │   Select a file
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │   name here.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │     │
│        ▲                        │     │
│        └──────────────────────────────┘
└─────────────────────────────────┘   Then choose <OK>.

The Dirs/Drives box provides access to other directories.
Note that the current directory for the Open Program
command can vary from the current DOS directory used
by other QuickBASIC commands.

To open a program in another directory
┌──────────Open Program───────────┐
│                                 │   Type a directory
│ File Name: ▒▒▒▒▒▒▒▒ ◄────────────── and file name here,
│                                 │   or
│ C:XXXX ◄──current directory    │
│                                 │
│      Files         Dirs/Drives  │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒ ◄─── Select a directory
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒  │   name here, then
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒  │   select a file name
│        ▲                        │   here.
│        └──────────────────────────────┘
└─────────────────────────────────┘   Then choose <OK>

To look at the contents of other directories
┌──────────Open Program───────────┐
│                                 │  Type a wildcard
│ File Name: ▒▒▒▒▒▒▒▒ ◄───────────── file name (such as
│                                 │  *.BAS or *.BI) here.
│ C:XXXX ◄──current directory    │
│                                 │
│      Files         Dirs/Drives  │     Select a directory
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒ ◄───── name here.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒  │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒  │     Look at the file
│        ▲                        │     names here.
│        └───────────────────────────────┘
└─────────────────────────────────┘ Then choose <Cancel>.
Use to insert the contents of a file saved in text format
into the currently loaded file.

Note that a file saved in QuickBASIC format cannot be
merged into a loaded file. Merge such a file by first
saving it in text format.
Use to insert the contents of a text file into the
currently loaded file. To use Merge
┌───────────────Merge─────────────┐
│                                 │  Place the cursor
│ File Name: ▒▒▒▒▒▒▒▒ ◄──text box │  where you want to
│                                 │  insert the file.
│ C:MYPROGS ◄──current directory │
│                                 │  Choose Merge.
│      Files          Dirs/Drives │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │  Select a text file,
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │  using the list boxes.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │
│        ▲                 ▲      │  Choose <OK>.
│        └────list boxes───┘      │
└─────────────────────────────────┘
Use to copy the contents of the file currently displayed
in the active view window to disk.

If the file has not been named, the Save command will ask
you for a name and format. If a disk file has the same
name as the file being saved, the disk file will be
overwritten.

 Tip:  The Save As command in the File menu always asks
       for a new file name.
Use to copy the file currently displayed in the active view
window from memory to disk. The file remains in memory.

With Save As you can save to a different file than the one
you loaded your program from, preserving the original
version.

Tip: Save (Full Menus only) is faster than Save As, but
     Save always overwrites the disk file from which the
     current file was loaded. Save All (Full Menus only) is
     used when you are working on multiple-module programs.
Use to save all changed module files when working with a
multiple-module program.

Save All prompts you for a name and format when the main
module is unnamed.

Save All creates and uses a special file with the main
module's base name and the .MAK extension. A .MAK file
contains the names of all the modules that make up a
program.
Use to select a name and format for saving the current file.
┌─────────────Save As────────────┐
│                                │ Accept this file name
│ File Name: ▒▒▒▒▒▒▒▒ ◄─────────── or type a new name here.
│                                │
│ C:MYPROGS ◄────────────────────── File will be saved
│                                │   in this directory.
│ Dirs/Drives         Format     │
│ ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒ QuickBASIC◄── Normal program format.
│ ▒▒▒▒▒▒▒▒▒▒▒                    │
│ ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒ Text◄───────── Use for include files,
│      ▲                         │  document files, or other
└──────│─────────────────────────┘  text files.
Use Dirs/Drives to change to different a directory or drive.
Use to begin entering a new file for a multiple-module
program. This can be
    ■ A program module
    ■ An include file
    ■ A document file

The new file will become part of the currently loaded
program.

 Tip: Create File can be used when no program is loaded
      as an alternative to the File menu's New Program
      command to create a new main program module.
Before you can create a new file, QuickBASIC needs to know
its file name and type.

┌────────── Create File ──────────┐  Type the file name
│ Name: ▒▒▒▒▒▒▒▒▒▒▒  ◄────────────── here.
│                                 │
│ ▒ Module  ▒ Include  ▒ Document◄── Select a file type
└─────────────────────────────────┘  here

Selecting the Document file type turns off the Smart Editor
functions.
Use to load files from disk so you can
  ■ Build a multiple-module program
  ■ Prepare to make a Quick library
Use to load a file into memory. Files already loaded remain
in memory.
┌──────────  Load File ───────────┐  Type the file name in
│ File Name: ▒▒▒▒▒▒▒  ◄───────────── the text box, or
│ C:XXX ◄── current directory    │
│              ┌────────────────────  Select the file
│      Files   ▼      Dirs/Drives │   name here.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │   Change the current
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒◄─── directory here.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒ │
│Load as:                         │
│ ▒ Module  ▒ Include  ▒ Document◄── Select a file type
└─────────────────────────────────┘  here.
The Document option loads the file as text and turns off
the QuickBASIC Smart Editor functions.
Use when creating a multiple-module program to delete an
unwanted module from memory, but keep it on disk.

QuickBASIC will display a list of currently loaded modules.
Select the one you want to unload.
The list box shows all the modules currently loaded in
memory. Choose the one you want to remove. If you remove
the main module of a multiple-module program, the
Choose New Main Module dialog box will appear.
Use to get a copy on paper of text in memory.

You can print out
  ■ Selected text only
  ■ The contents of the active window
  ■ The current module (including procedures)
  ■ All of the modules of a multiple-module program

Tip: The Print command always transmits the text through
     the DOS port LPT1.
Make sure the printer attached to DOS port LPT1 has power
and is on-line.
┌────────Print────────┐
│                     │  Select (highlight) some text
│ ▒▒▒ Selected Text ◄─── before you use this option.
│                     │  Can  print out a procedure
│ ▒▒▒ Active Window ◄─── in the View window.
│                     │
│ ▒▒▒ Current Module◄─── Prints out the module with all
│                     │  procedures.
│ ▒▒▒ All Modules   ◄─── Prints all loaded files (Full
│                     │  menus only).
└─────────────────────┘
If the active window is a help window, only the first two
options are available.
Leaves QuickBASIC temporarily so you can use DOS commands.
To do this
  1. Choose the DOS Shell command from the File menu.
  2. Perform DOS tasks, but don't delete any files
     that QuickBASIC might need (loaded files, libraries).
  3. Type "exit" at the DOS prompt to return to QuickBASIC.
Choose when you are finished using QuickBASIC.

A dialog box may appear if new or changed text has not
been saved.
    ■ Choose <Yes> to save your changes.
    ■ Choose <No> to discard your changes.
    ■ Choose <Cancel> or press ESC if you change your mind.
Use to reverse your most recent edit. Undo restores the
current line to its condition before the last change you
made. Once the cursor moves off the line QuickBASIC accepts
the edit and Undo has no affect.
Use Cut (or press SHIFT+DEL) to remove selected text from
the active window and put it in the Clipboard.

You can then use Paste (SHIFT+INS) to insert it into an
active window.

Tip: Select text by placing the cursor where the text should
     begin and pressing the SHIFT+DIRECTION keys. Remove
     selected text without copying it to the clipboard by
     pressing DEL.

This example shows how Cut and Paste can be used together:
       1.                   2.                     3.
Select text with     Choose Cut command    Move cursor to
SHIFT+ARROW          or press SHIFT+DEL    insertion point
                                           and choose Paste
┌─────Text────┐       ┌─────Text────┐       ┌─────Text────┐
│▒▒▒▒▒▒▒▒▒▒▒  │       │             │       │             │
│             │       └─────────────┘       │▒▒▒▒▒▒▒▒▒▒▒  │
└─────────────┘                             └─────────────┘

┌──Clipboard──┐       ┌──Clipboard──┐       ┌──Clipboard──┐
└─────────────┘       │▒▒▒▒▒▒▒▒▒▒▒  │       │▒▒▒▒▒▒▒▒▒▒▒  │
                      └─────────────┘       └─────────────┘
The cut text is still in the Clipboard and could be pasted
in at another point.
Use Copy (or press CTRL+INS) to copy a block of selected
text from the active window to the Clipboard. The original
block of text remains unchanged.

You can then use Paste (SHIFT+INS) to insert the text into
into an active window.

 Tip: Select text by putting the cursor where the text
      should begin and pressing the SHIFT+ARROW keys.



This example shows how Copy and Paste can be used together:
       1.                    2.                    3.
Select text with      Choose Copy or        Move cursor to
SHIFT+ARROW           press CTRL+INS        insertion point
                                            and choose Paste
┌─────Text────┐       ┌─────Text────┐       ┌─────Text────┐
│▒▒▒▒▒▒▒▒▒▒▒  │       │             │       │             │
│             │       │             │       │             │
└─────────────┘       └─────────────┘       │▒▒▒▒▒▒▒▒▒▒▒  │
                                            └─────────────┘
┌──Clipboard──┐       ┌──Clipboard──┐       ┌──Clipboard──┐
└─────────────┘       │▒▒▒▒▒▒▒▒▒▒▒  │       │▒▒▒▒▒▒▒▒▒▒▒  │
                      └─────────────┘       └─────────────┘
The copied text is still in the Clipboard and could be
pasted in at another point.
Use Paste (or press SHIFT+INS) to copy a block of text from
the Clipboard to any point in the active window.

An insertion point can be defined by:
  ■ Highlighted text; it is deleted and the contents of the
    Clipboard copied in its place.
  ■ The cursor position if no text is highlighted. Then
        ■ Less than one line of text is copied to the left
          of the cursor
        ■ More than one line is copied above the cursor
Use Clear (or press DEL) to delete a block of selected text
from the active window without copying it to the Clipboard.
The Clipboard's contents remain intact.
Use New SUB to create a new SUB procedure as part of the
program or module in the View window.

A dialog box will prompt you for a procedure name.
QuickBASIC will then clear the View window and generate
the needed SUB and END SUB statements so you can start
entering text.

When you are through entering the new SUB, use the SUBs
command from the View menu (or press F2) to return to your
program. Your new SUB now appears in the SUBs command list.

 Tip: You can start a procedure editing screen without
      using a menu. Simply type the QuickBASIC keyword
      SUB followed by a procedure name.
Prompts for the name of a new SUB or FUNCTION. Enter the
name (up to 40 characters) in the text box, then choose
<OK>.

Descriptive procedure names help you remember the
procedure's use and minimize the chances of duplicating
the name of another procedure or a variable.
Use to prepare to enter a function definition in the View
window. A QuickBASIC FUNCTION is a procedure that returns
a value to your program.

Note: A FUNCTION name can only be defined once in a program.
Use to view different parts of a loaded program. You can
  ■ Change the contents of the View window
  ■ Split the View window to see different parts of the
    same program or two programs at once
  ■ Delete procedures and modules
  ■ Move procedures between modules
Select a program item from the list box to view, move, or
remove, then choose the appropriate button.
┌───────────────SUBs ─────────────┐
│ Choose program item to edit:    │ Select an item here
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄──(uppercase names are
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ modules; indented names
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ are procedures).
│ XXX is xxxxxxxxxxxxxxxx ◄──────── Describes selected
│                                 │ items.
│<Edit in Active>  <Edit in Split>│◄──These allow you to
│                                 │   view or edit an item.
│     <Delete>         <Move>     │◄──These delete or move
└─────────────────────────────────┘   an item without
                                      displaying it.
Which module do you want the selected procedure to be
moved to?
┌──────────────SUBs ───────────┐
│ Choose destination module:   │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄─── All the modules in
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │   your currently loaded
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │   program are listed
│                              │   here.  Select one,
│            <OK>              │   then choose <OK>.
└──────────────────────────────┘
Use Next SUB (or SHIFT+F2) to bring another SUB into the
View window.

      ┌──────C──────┐
      │             │   QuickBASIC moves from procedure to
   ┌──────B──────┐  │   procedure in alphabetical order.
   │             │ ─┘   In this example, pressing SHIFT+F2
┌──────A──────┐  │      once moves from procedure B to C;
│             │ ─┘      pressing it twice moves to A.
│             │
└─────────────┘

Note: CTRL+F2 moves through the procedures in reverse
      alphabetical order.

Tip:  For programs with many procedures it may be quicker
      to use the SUBs command.
Use to work on two parts of a program, or two programs,
simultaneously.

Split divides the View window horizontally. Use F6 and
SHIFT+F6 to move between the windows on the screen:
  ■ F6 moves the cursor down through the windows.
  ■ SHIFT+F6 moves the cursor up.

To restore an unsplit View window, choose Split again.

The active window contains the cursor. This window can be
sized from the keyboard:

  ■ ALT+PLUS(+)  expands it one line
  ■ ALT+MINUS(-) shrinks it one line
  ■ CTRL+F10     expands it to fill the screen, or returns
                 it to its former size
Places the cursor on the next executable program statement
following the point where a program has been suspended. You
can then resume with
  ■ The Continue command (or press F5)
  ■ Pressing F8 to execute only the next statement
  ■ Using Set Next Statement to change the point where
    execution will resume
Use to toggle between the QuickBASIC environment screen and
the program output screen.

Press F4 as a shortcut.
Command is active only when a loaded program contains one
or more $INCLUDE metacommands.

Use to load an include file into the View window so you can
change it:
  1. Place the cursor on the $INCLUDE metacommand that names
     the file you want to edit.
  2. Choose the Included File command.
  3. Edit the file in the View window, then choose Save As
     from the File menu, or debug your program with the
     include file incorporated and save the file later, as
     part of the program.

  Tip: To view the program text while you edit the include
       file (requires Full Menus):
       1. Split the View window with the View menu's Split
          command.
       2. Choose Load File from the File menu to load the
          include file.
       3. Return the program to the program text to make its
          window active again. You can now run your program.
This toggle turns the display of include file text in the
active window on and off. A bullet appears next to the
command name on the menu when the toggle is on.

Use this command only if your program contains a $INCLUDE
metacommand.

When Included Lines is on, the include file text appears in
low-intensity video following the $INCLUDE metacommand that
names it. These displayed lines are read-only. You must load
the include file into a dedicated View window to edit them.
Use to search for a text string in
  ■ The active window
  ■ The current module
  ■ All loaded modules

You can request an exact (case sensitive) match or a
whole-word match.

To change a string use the Change command instead.

Using the Selected Text command (Full Menus only) is an
efficient alternative when searching for a short (one line
or less) string in the active window.
Defines the criteria for a search.
┌────────────── Find ──────────────┐
│                                  │ String to find. Type
│ Find What: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄─ in or use the string
│                                  │ already there.
│                ┌──── Search ────┐│
│ ▒ Match U/L     ▒ Active Window  │
│                                 ◄── Select scope of the
│ ▒ Whole Word    ▒ Current Module │  search.
│ ▲                                │
│ │               ▒ All Modules    │
└─│────────────────────────────────┘
Tightens up the criteria for a match, when selected.

Choose Match U/L for a case-sensitive match, or Whole Word
to exclude matches within words or strings. Whole-Word
searches recognize a match only when the target text is
surrounded by blanks, punctuation, or other special
characters.
QuickBASIC could not find the string specified.

The cursor remains at the location where you started the
search.
The search and replace task is complete. The cursor is
back at the point where the search started.
Use to search for one text string and replace it with
another.

You can search
  ■ The active window only
  ■ The current module
  ■ All loaded modules

You can elect to
  ■ Review each replacement before it's made
  ■ Use a case-sensitive or whole-word search
┌──────────────Change──────────────┐
│                                  │  Enter text string or
│ Find What: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── accept the default.
│                                  │  Enter replacement
│ Change To: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── text string.
│                                  │
│                ┌──── Search ───┐◄── Select search range.
│ ▒ Match U/L     ▒ Active Window  │
│                                  │
│ ▒ Whole Word    ▒ Current Module │
│                                  │
│                 ▒ All Modules    │
│                                  │ Find and Verify lets
│  <Find and Verify> <Change All> ◄──you review before
└──────────────────────────────────┘ changing.
The Find What text box was empty when you executed a
Find or Change command. Choose the command again and
enter a text string before choosing <OK>.
A match has been found and is highlighted in the active
window. You may
  ■ Choose <Change> to make the replacement and continue
    searching
  ■ Choose <Skip> to leave the text unchanged and continue
    searching
  ■ Choose <Cancel> to leave the text unchanged and stop
    searching
Use to find a text string that matches target text of one
line or less that has been selected in the active window.

The shortcut key for Selected Text is CTRL+. For other
situations, use Find.

To execute Selected Text
  1. Select (highlight) the target string.
  2. Choose Selected Text or press CTRL+. QuickBASIC will
     highlight the next instance of the selected text.
Use Repeat Last Find (or press F3) to repeat most recent
Find or Change command.

If no Find or Change command has been executed since
you started QuickBASIC, Repeat Last Find will define the
search string as
   ■ The word the cursor is on
   ■ The word to the cursor's left, if the cursor isn't
     on a word
Use like Find when you are searching for a line label.

When using Label, QuickBASIC looks only at the first
nonblank item in a program text line that ends with a
colon.

Note: When you enter the search label into the Find What
      text box, do NOT include the colon. BASICA-style
      integer line labels are not followed by colons,
      so you cannot use Label to locate them.
Use to clear memory and start program execution at the
first executable statement in the main module.

The Start command can be used after stopping a running
program with CTRL+BREAK to run the program again from the
beginning. Use Start as an alternative to Restart or
Continue.

The Start command shortcut key is SHIFT+F5.

Tip: QuickBASIC breakpoint and watchpoints are alternatives
     to pressing CTRL+BREAK to stop a running program.
Use as an alternative to Start and Continue. Restart clears
memory and highlights the first executable statement.

Use F8 to execute one statement at a time. You can alter
which statement will execute next with Set Next Statement
from the Debug menu (Full Menus only).
Use Continue after your running program has stopped and you
want to continue execution of your program.

This command is often used to continue a program after a
breakpoint or watchpoint has let you look at variables'
values in the Immediate window or view the output screen.

The Continue command shortcut key is F5.
Use when debugging a QuickBASIC program that uses the
COMMAND$ function. COMMAND$ transfers information from
the DOS command line.

Modify COMMAND$ lets you test your program's response to
new command lines without switching between QuickBASIC
and DOS.
Enter the DOS command line you want to test with Modify
COMMAND$ (for use with the COMMAND$ function).

┌────────Modify COMMAND$───────┐
│   Enter text for COMMAND$:   │
│                              │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── Enter up to 127
│                              │  characters here,
│  <OK>                        │  then choose <OK>.
└──────────────────────────────┘
Use to build an .EXE (executable) version of your
completed, debugged QuickBASIC program.

This version of your program will run directly from the
DOS command line without QuickBASIC having been invoked.
This command will produce a version of your program that
will run outside QuickBASIC.
┌────────────── Make EXE File ─────────────┐ Default is
│                                          │ base name of
│ EXE File Name: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ◄────.BAS file.
│                                          │
│               Produce:                   │ Program will
│ ▒ Produce     ▒ EXE requiring BRUN45.EXE◄─ need BRUN45
│ ▲ Debug Code                             │ present to run.
│ │             ▒ Stand-alone EXE ◄───────── Program will
│ │                                        │ run alone. This
│ │  <Make EXE>      <Make EXE and Exit>   │ option works
└─│────────────────────────────────────────┘ best with
Toggle on for users to be able to stop       small programs.
program execution with CTRL+BREAK

Note: Programs that use BRUN45.EXE are smaller than the
      same programs in stand-alone form. They also preserve
      COMMON variables and open files across CHAIN
      statements; stand-alone programs do not.

      Use the stand-alone option if you distribute your
      program to others.
Use to combine a set of program modules into a Quick
library file or to update an existing Quick library.

Make a Quick library when you have created a set of
procedures that you want to use in more than one program.
Quick libraries are convenient and save disk space.

You can load a Quick library by using the /L option in
the QB command line when you invoke QuickBASIC.
Use this dialog to create a Quick library from the
currently loaded modules.

┌────────────── Make Library ───────────┐ Type a file name
│                                       │ with extension
│ Quick-Library File Name: ▒▒▒▒▒▒▒▒▒▒▒▒◄──(default is QLB).
│                                       │
│ ▒ Produce Debug Code ◄──────────────────This option will
│                                       │ slow execution;
│                <Make Library and Exit>│ debug modules
└────────────────────────────▲──────────┘ before putting
  Choose to make the library ┘           them in a library.
  and then return to DOS

The modules for a Quick library can come from single-module
program files, multiple-module program files, or existing
Quick library files.

Create a Quick library from single-module program files by
  1. Loading each file with Load File from the File Menu
     (Full Menus only)
  2. Choosing Make Library from the Run menu

Create a Quick library from multiple-module program files by
  1. Loading the program into memory
  2. Using Unload File from the File menu to eliminate any
     modules you don't want included
  3. Choosing Make Library command from the Run menu

Add modules to an existing Quick library by
  1. Invoking QuickBASIC with the /L option to load the
     Quick library
  2. Using Load File from the File Menu (Full Menus only)
     to add additional modules
  3. Choosing Make Library from the Run Menu to create
     a new library

 Tip: You must give the new library its own unique name.

Note: QuickBASIC creates .LIB files with the same base name
      as the .QLB files. The .LIB files are used to build
      new Quick libraries from existing Quick libraries.
Use when working on a multiple-module program to change its
initial execution location. During program development it is
common practice for each module to have test code as the
first executable statements.

┌─────── Set Main Module ──────┐
│ Choose new main module:      │
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄──Select a new main module
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ here and choose <OK>.
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
│                              │
│  <OK>                        │
└──────────────────────────────┘
Use to continuously watch the value of a variable or the
condition (-1 for true or 0 for false) of an expression
as your program executes.

Watched variables appear in the Watch window at the top
of the screen.

Note: The message 'Not watchable' appears in the Watch
      window if QuickBASIC cannot access the value of the
      variable.
Enter the program variable or expression you want to watch.

The Watch window can display the value of an expression
made of variables (e.g. X + Y).

┌────────   Add Watch   ───────┐  Type the variable
│ Enter expression to be added │  or expression you
│ to Watch window:             │  want to watch
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── here.
│                              │
│  <OK>                        │
└───▲──────────────────────────┘
After you choose <OK>, the Watch window will show the
variable name, preceded by the name of the program
part, in the View window.
Use when program execution is suspended, to display
  ■ The value of a variable
  ■ The condition of an expression (true or false)

To display the value of a variable
  1. Place the cursor on the variable name
  2. Choose Instant Watch from the Debug menu (or press
     SHIFT+F9).

To display the value of an expression
  1. Select (highlight) the expression in the View window
     or place the cursor in the expression (QuickBASIC
     searches the appropriate expression or variable)
  2. Choose Instant Watch (or press SHIFT+F9)
  3. The expression is true if Instant Watch displays -1,
     false if it displays 0

The values are displayed in a dialog box. Use this box to
add the variable or expression to the Watch window.

Note: Mouse users can display an Instant Watch by placing
      the mouse cursor on a variable, or selecting an
      expression, and simultaneously pressing SHIFT and
      clicking the right mouse button.
Use to look at the current value of a variable or the
condition of an expression, and to:
  ■ Add the variable or expression to the Watch window
  ■ Get more help about it
┌──────────────────────────────┐
│   ┌───────Expression──────┐  │  The text you selected
│   │                       │◄─── in the active window
│   └───────────────────────┘  │  appears here.
│   ┌───────  Value   ──────┐  │
│   │                       │◄─── Current value or
│   └───────────────────────┘  │  condition appears here.
│<Add Watch>  <Cancel>  <Help>◄── Displays information
└────▲─────────────────────────┘  about the expression.
     │
     Adds the expression to the Watch window.
Use to suspend program execution when a condition you
specify becomes true. The condition may be
  ■ A variable name
  ■ A relational statement

A relational statement is constructed using the operators
=, <>, >, <, >=, or <=.

If you use the simpler form and just enter a variable name
or an expression, QuickBASIC assumes the relation <> 0. For
example, entering X + Y yields the expression X + Y <> 0.

Add Watch
    ■ Displays the values of variables as they change
      during program execution
    ■ Does not suspend program execution
A Watchpoint
    ■ Does not display variables' values
    ■ Suspends program execution when the expression
      becomes true
┌────────Add Watchpoint ───────┐
│ Enter Watchpoint to be added │
│ to Watch window:             │  When this expression
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── becomes true (non-zero),
│                              │  the program will stop.
│  <OK>                        │
└───▲──────────────────────────┘
    │
After you choose <OK>, the expression entered here appears
in the Watch window.
Use to remove items from the Watch window one at a time.

Use Delete All Watch (Full Menus only) to remove all items
at once and close the window.
Select a watchpoint or watch expression and choose <OK>.

┌─────────Delete Watch─────────┐
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄── All watchpoints and
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │  watch expressions in
│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │  the Watch window are
│                              │  listed here, preceded by
│  <OK>                        │  their procedure names.
└──────────────────────────────┘
Use this command to remove all Watch window items and close
the window.
Turn this toggle on when you want QuickBASIC to
  ■ Run your program in slow motion, highlighting each
    statement as it executes
  ■ Record the last 20 lines of program code executed
    before a program stops

This lets you observe the general flow of your program.
Use with watchpoints, breakpoints, or CTRL+BREAK to
suspend program execution periodically.

Then use SHIFT+F8 and SHIFT+F10 to single-step backward
and forward through the last 20 lines of code.
Turn this toggle on when you want QuickBASIC to
  ■ Run your program at full speed
  ■ Record the last 20 lines of program code executed
    before a program stops

You can then step backward and forward through the 20 lines
of code recorded by History On by pressing SHIFT+F8 or
SHIFT+F10 to review branching and other program actions.

Tip: Use History On together with breakpoints to review any
     group of 20 consecutive statements in your program.
Use the Toggle Breakpoint command to turn breakpoints
(places you want your program to stop running) on and off:
  1. Move the cursor to the line you want the breakpoint on.
  2. Choose Toggle Breakpoint (or press F9).
QuickBASIC highlights the breakpoint line.

To turn off a breakpoint:
  1. Move the cursor to a highlighted breakpoint line.
  2. Choose Toggle Breakpoint.

Use a breakpoint to pause your program at a point where
you suspect problems, then
  ■ Test the values of variables in the Immediate window
    or with Instant Watch
  ■ Add variables to the Watch window and single step your
    program from the breakpoint forward
Use this command to remove all breakpoints from your
program.

Use Toggle Breakpoint (or press F9) to turn individual
breakpoints off.
Use this command when debugging a program that contains
an error-handling procedure.

Break On Errors (toggled on when a bullet appears next
to the command) causes your program to stop at the first
statement in the most recently executed error-handling
subroutine. This suspends program execution so you can
locate the error's source.

Turning on Break On Errors also enables the History On
toggle, so the 20 statements executed just before the
breakpoint are also recorded. Use the SHIFT+F8 key once to
back up to the statement that caused the error. Backing up
further will show you the statements that lead to the error.
Use to change the program execution sequence so the next
statement executed is the one the cursor is on.
Use the Display command to control
  ■ Screen colors
  ■ Scroll bars in windows and lists
  ■ The number of spaces the TAB key advances the cursor
Use to customize the QuickBASIC screen.
                 ┌────────────────Display─────────────────┐
                 │ ┌────────────── Colors ───────────────┐│
                 │                     Foregrnd  Backgrnd │
                 │ ▒ Normal Text       ▒▒▒▒▒▒▒▒  ▒▒▒▒▒▒▒▒ │
                 │                     ▒▒▒▒▒▒▒▒  ▒▒▒▒▒▒▒▒ │
Colors you pick  ─►▒ Current Stmt      ▒▒▒▒▒▒▒▒  ▒▒▒▒▒▒▒▒ │
here will        │                                        │
highlight text   ─►▒ Breakpoint Lines                     │
during debugging │                                        │
                 │ ┌──────────Display Options────────────┐│
                 │   ▒ Scroll Bars          Tab Stops: ▒  │
                 └───▲─────────────────────────────────▲──┘
Turn off if you do   │    Enter number of spaces you   │
not use a mouse. ────┘    want TAB to advance cursor. ─┘

To set options
  1. Move the cursor to the appropriate option box with
     the DIRECTION keys (Normal Text, Current Statement,
     or Breakpoint Lines).
  2. Press TAB. The cursor will jump to the foreground
     color list.
  3. Use the DIRECTION keys to select a color.
  4. Press TAB to repeat the color selection process for
     the background color.
  5. Press ENTER to choose the new color pair.
Use to change the default DOS paths QuickBASIC uses to find
  ■ Executable files (.EXE and .COM files)
  ■ Include files (.BI and .BAS files)
  ■ Library files (.LIB and .QLB files)
  ■ Help files (.HLP)
QuickBASIC will search for specific files in the directories
you indicate in this box. You don't need to set search paths
if you have done so with DOS environment variables or if all
files needed by your program are in the current directory.
┌───────────────Set Paths──────────────┐
│ Search Path For:                     │ For example,
│ Executable Files: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄─ c:qb45\bin
│                                      │    For example,
│ Include Files:    ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄──── c:qb45qbbi
│                                      │ For example,
│ Library Files:    ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄─ c:qb45qblib
│                                      │    For example,
│ Help Files:       ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒◄──── c:qb45qbhlp
└──────────────────────────────────────┘
Tip: When you enter a path, QuickBASIC does not check
     what you typed for syntax or meaning. QuickBASIC
     uses the same syntax as DOS environmental variables.
Toggles the effect of single-clicking the right mouse
button between
  ■ Displaying help about the item the cursor is on
  ■ Executing the current program from the beginning
    to the line the cursor is on
Assigns a function to the right mouse button.
                        ┌────────  Right Mouse  ──────────┐
                        │                                 │
    Keyboard users get  │ On right mouse button click:    │
    the same effect     │                                 │
    by pressing F1. ─────► ▒  Context-sensitive Help      │
                        │                                 │
 Useful in debugging. ───► ▒  Execute up to this line     │
 Keyboard users get     │                                 │
 the same effect by     └─────────────────────────────────┘
 pressing F7.
This command toggles a QuickBASIC Smart Editor function on
and off.

As you enter each line, the Smart Editor
  1. Checks the line for syntax errors
  2. Formats the line
  3. Translates the line to executable form if the syntax
     is correct

Turn off the Syntax Checking to suppress the first of these
functions to enter program code for debugging later.

When Syntax Checking is on, a bullet will appear to the left
of the command.

These commands from the File Menu turn Smart Editor features
on while they execute:
  ■ New Program or Open Program
  ■ Create File or Load File (unless you select the Document
    option).

If you select the Document option with Create File or Load
File, the editor will be turned off.
Use to toggle between the Full and Easy forms of QuickBASIC
menus.

When the Full Menus feature is on, a bullet appears to the
left of the Full Menus command.

The Easy Menus contain all the commands you need to build
programs. The Full Menus provide additional commands and an
additional menu (the Calls menu).
The Help index is an alphabetical list of Help topics,
including BASIC language keywords. Each term in the index
is linked to additional information.

To get help
  1. Choose the Index command from the Help menu
  2. Press the key corresponding to the item's first
     letter
  3. Move the cursor to the item you want help on, then
     press F1
Outlines QuickBASIC's on-line help.

To get help on any item in the outline
  1. Choose the Contents command from the Help menu
  2. Press the letter key corresponding to the first letter
     of the item
  3. Press F1
Choosing this command displays information on a topic
determined by the cursor's current location. The topic the
cursor currently points to appears as part of the command.

You can also access this information by pressing F1 (or
mouse users can click the right button).
Help on Help describes how to use the mouse or keyboard
to get help on an item displayed on the QuickBASIC screen.
Symbol help is not available for your program because of
errors in the program. Use keyword help and the error
message dialog boxes for help in debugging your program.

Press SHIFT+F5 or press F8 to start running the program.
This will show you what the error is.
The cursor is not on a program line that contains a valid
expression. The Instant Watch command expects the
cursor to be on an expression whose value you want to see.

Choose <OK> on the error message dialog box and reposition
the cursor within the expression you want to watch.

Tip: In a complex expression, it may be hard to decide
     where to put the cursor to watch a particular
     variable or subexpression. You can unambiguously
     indicate what the Instant Watch command should watch
     by highlighting it. Just place the cursor on the
     extreme left or right end of the expression and
     pressing SHIFT+RIGHT or SHIFT+LEFT.
You have attempted to open a file on a device that does
not exist in your system. Check the list of available
device names in the Dirs/Drives list box and use one
of those.
You are attempting to create a new element in your program
and have given it a name that is already being used.
Examples of this are:
  ■ Giving a new procedure the name of an existing
    procedure.
  ■ Giving a new variable the name of an existing
    procedure.
  ■ Starting a variable name with the letters FN.

There can also be a conflict of file names. Attempting to
create a file using the name of a file that already exists
in the current directory will cause this error.

Either
  ■ Use a different name in the dialog box, or
  ■ Cancel the command and either change the name of the
    existing item that is causing the name conflict, or
    delete it.
A constant is too large to be represented within the range
allowed for a number.

Use the Help menu's Contents command to get a hyperlink
to Limits to QuickBASIC, which display's the largest
numbers QuickBASIC can handle.
While attempting to execute the File menu's Print command,
QuickBASIC tried repeatedly to send text to a printer
attached to the LPT1 port, without getting an acknowledging
signal back from the printer.

Make sure that there is a printer attached to LPT1.
While executing the File menu's Print command, QuickBASIC
detected a fault at the printer

Make sure that
  ■ The printer cable is still securely connected to
    both the computer and the printer.
  ■ The printer power is still on.
  ■ The printer on-line indicator light is still on.
Make sure the file specification you entered in the
text box is formatted correctly.

Any file name can contain a full or partial path name.
A full path name starts with the drive name; a partial
path name has one or more directory names before the
file name, but does not include a drive name. For
example,

  a:progsgraphiccircle.bas is a valid full path name
  graphiccircle.bas is a valid partial path name
  ..graphiccircle.bas is a valid partial path name

This error can also occur when you try to save a file
which replaces an existing read-only file.
QuickBASIC cannot find a path to the file name you
specified in the dialog box. QuickBASIC may have also
looked along these other paths, depending upon the file
name extension:
  ■ Paths specified by the Options menu's Set Paths command
  ■ Paths specified by DOS environmental variables
    PATH, INCLUDE, or LIB.
Note: If the file name is eight or less characters with
      no period, QuickBASIC assumes the extension .BAS.
      If the file name is between 9 and 11 characters,
      QuickBASIC puts a period after the eighth character.
First check to make sure you spelled the file name
correctly in the dialog box. If it is correct, you must
adjust the path specification in either the dialog box,
the Set Paths command, or the DOS environment variables.
Make sure the file name you entered in the dialog box
conforms to these rules and assumptions used by QuickBASIC:
  ■ A file name has two parts: the "base name", which is
    everything up to but not including the period (.), and
    the "extension," which includes the period and up to
    three characters. You can use any combination of upper-
    and lower-case characters; these example filenames all
    refer to the same file:
      abcde.bas, ABCDE.BAS, and aBcDe.BaS
  ■ If the file name is 8 or less characters with no
    period, QuickBASIC assumes the extension .BAS. If the
    file name is between 9 and 11 characters, QuickBASIC
    puts a period after the eighth character.
QuickBASIC can't find a file with the specified name
on the specified disk and/or directory.

Check your path specification in the command dialog box.
Also check the spelling of the file name.
You are attempting to overwrite a read-only disk file or
there is a write-protect tab on the disk you are trying
to write to.

To avoid the read-only conflict, use a different file name.
Remove the tab or use a different disk if the write-
protect tab is present.
There is no disk in the drive specified in the dialog box.

Insert a disk and retry the operation.
QuickBASIC does not recognize the format of the disk
or diskette it is attempting to use.

Try a different diskette or reformat the current diskette
QuickBASIC has a limit to the number of disk files it
can have open at any one time, and your program is at
that limit. Before this command can be executed, you
need to close some of these files.

The easiest way to do this is with the BASIC CLOSE
statement:
  1. Move the cursor to the Immediate window.
  2. Type CLOSE on the first available text line.
  3. Press ENTER to execute the statement.

This lets you execute the QuickBASIC command you were
attempting before, but if your program was running
you will have to restart it.
There isn't room on the specified disk to save this
file. You can
  ■ Save the file to another disk
  ■ Cancel this command and use the QuickBASIC Shell
    command from the File menu to delete some files
    from the disk. Then try this command again.
This can occur only in the File menu's Print command.
The printer has malfunctioned.
QuickBASIC is attempting to load a binary file and does
not recognize the binary-file format. QuickBASIC
recognizes two binary-file formats:
  1. QuickBASIC program files
  2. Help files
This error commonly occurs when QuickBASIC is asked to
use an include file that has been saved in compressed
format. Include files must be saved in text format, so
  1. Reload the include file as a module
  2. Save it in text format
  3. Run the program again.
While executing the Print command from the File menu,
QuickBASIC has detected that the printer is out of paper.
Either
  ■ Put some paper in the printer and choose <OK>, so
    the Print command can continue, or
  ■ Choose <Cancel>, and refill the printer later.
QuickBASIC will not make a Quick library with the same
name as a Quick library already loaded into memory.
Either
  ■ Enter a different name in the text box for the new
    Quick Library to include the contents of the loaded
    library in the new one you are building, or
  ■ Re-invoke QuickBASIC from the DOS command line without
    using the /L option. This lets you make a Quick library
    that does not include a previously made one.
You are about to execute a command that will cause the
changes you have made to a loaded file since the last the
last time you saved it to be lost. Either
  ■ Choose <Yes> to save the file, preserving your
    changes, and then finish executing this command.
  ■ Choose <No> to finish executing this command without
    saving the file. Use this choice to throw away work
    that you do not wish to save. Or,
  ■ Choose <Cancel> to stop the command, leaving everything
    just as it was before you chose this command.
When QuickBASIC runs a program that references include
files through $INCLUDE metacommands, QuickBASIC can only
use the versions of those include files that are on disk.

There are one or more include files loaded into memory
that have not been saved to disk since they were modified.
QuickBASIC needs to know which version of the include files
you want to run. Either,
  ■ Choose <Yes> to save the modified include files and
    run.
  ■ Choose <No> to run the program with the versions that
    are currently on disk (the unmodified versions). Or,
  ■ Choose <Cancel> if you don't want to run the program.
QuickBASIC is about to save a file and finds one or more
include files that have been loaded into memory but not
saved to disk since they were modified. Either
  ■ Choose <Yes> to save the modified include files and
    then save the program file.
  ■ Choose <No> to save the program file, but not the
    modified include files, if you are still experimenting
    with the include file or do not have complete
    confidence in it.
  ■ Choose <Cancel> if you don't want to save any files.
To debug a SELECT...END SELECT statement with the aid
of a breakpoint, set the breakpoint on the SELECT CASE
line in your program. Then single-step through the rest
of the statement structure.
Each NEXT statement must have a matching FOR statement.

Also verify that other control structures within the
FOR...NEXT structure are correctly matched. For example,
an IF without a matching ENDIF inside the FOR...NEXT
structure generates this error.
ERR Code: 1
Several conditions can cause this error:
  ■ At compile time, the most common cause is a mistyped
    QuickBASIC keyword or argument.
  ■ At run time, the most common cause is an improperly
    formatted DATA statement.

ERR code: 2
The program just executed a RETURN statement without
executing a GOSUB.

ERR code: 3
A READ statement has been executed but there are no DATA
statements with unread data remaining in the program.

ERR code: 4
A parameter that is out of range has been passed to a
BASIC statement or function. For example, a screen row
number that is off the screen has been passed to the
LOCATE statement. Other examples of function call errors
are:
  ■ An unreasonably large subscript is used
  ■ A negative number is raised to a power that is not
    an integer
  ■ A negative record number is given GET or PUT file I/O
    statements
  ■ 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 (variable-length
    strings only)
  ■ A BLOAD or BSAVE operation is directed to a non-disk
    device

ERR code: 5
The result of a calculation, or datatype conversion of
a procedure argument, was too large to be represented
within the range allowed for a number.

Use the Help menu's Contents command to look at the ranges
of numbers QuickBASIC can handle, as follows:
  1. Choose <OK> to close the error message dialog box.
  2. Press ALT+H to open the Help menu.
  3. Choose the Contents command.
  4. Choose the Limits to QuickBASIC hyperlink. The
     maximum numeric values that QuickBASIC can handle
     will be displayed in the Help window.
  5. Press ESC to clear the Help window.

ERR code: 6
More memory was required than is available. For example,
there may not be enough memory to allocate a file buffer.

In DOS
  ■ Reduce the size of your DOS buffers
  ■ Eliminate any terminate-and-stay resident programs
  ■ Eliminate some device drivers
In QuickBASIC
  ■ Try placing a $DYNAMIC metacommand at the top of your
    program if you have large arrays
  ■ Unload any document or source files that are in memory
    but not needed
  ■ Make your programs smaller
  ■ Try to put your routines into a Quick library

ERR code: 7
The statement refers to a label that QuickBASIC cannot
find:
  ■ GOTO, GOSUB, and single-line IF statements can only
    refer to labels in the current procedure.
  ■ Labels that begin error-handling and event-handling
    routines must be in the main-module level of the
    program.

ERR Code: 8
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.

You may also get this error if the array size exceeds 64K,
the array is not dynamic, and the /AH option was not used.
Either
  ■ Reduce the size of the array
  ■ Make the array dynamic and re-invoke QuickBASIC using
    the /AH command-line option

ERR code: 9
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 a variable definition, or
  ■ 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.

ERR code: 10
Causes of this message are
  ■ Dividing by zero in an expression
  ■ Raising zero to a negative power

ERR code: 11
The highlighted statement is only valid within a program
and cannot be used in the Immediate window. In general
  ■ The following nonexecutable statements cannot be used
    in the Immediate window:
      COMMON, CONST, DATA, DECLARE, DIM, OPTION, SHARED,
      STATIC, and TYPE
  ■ The following metacommands cannot be used:
      $INCLUDE, $DYNAMIC, $STATIC
  ■ The following other statements cannot be used:
      REDIM, SUB...END SUB, FUNCTION...END FUNCTION,
      DEF FN...END DEF, ELSE IF, END IF, END TYPE

ERR Code: 12
The highlighted variable, or the variable closest to the
highlighted keyword, is not of the required data type.

For example, you are trying to use the SWAP statement
with a string variable and a numeric variable, or with
two numeric variables of different types.

ERR code: 13
String variables exceeded the allocated amount of string
space. Try the following:
  ■ Place a $DYNAMIC metacommand at the top of your
    program if you have large numeric arrays.
  ■ Reduce the amount of memory used by the stack by
    executing a CLEAR statement.
  ■ Unload any document or source files that are in memory
    but not needed.

ERR code: 14
Either
  ■ A string formula was too long, or
  ■ An INPUT statement requested more than 15 string
    variables.

Break the formula or INPUT statement into smaller parts.

ERR code: 16
You must define a function before using it.

The module or Quick library that contains the function
definition may not be loaded.
ERR code: 18
The end of the program was encountered while the program
was in an error-handling routine.

Add a RESUME statement in the error-handling routine.

ERR code: 19
A RESUME statement was encountered before an
error-trapping routine was entered.

ERR code: 20
The program did not receive information from an I/O device
within a predetermined amount of time.

ERR code: 24
A device has returned a hardware error:
 ■ If you are attempting to print a file, the printer
   is not attached to the parallel port LPT1.
 ■ If data are being transmitted to a communications
   file, the signals being tested with the OPEN COM
   statement were not found in the specified period
   of time.

ERR code: 25
Each FOR statement must have a matching NEXT statement.

ERR code: 26
The printer is out of paper, or it is not turned on.

ERR code: 27
Each WHILE statement must have a matching WEND statement.

ERR Code: 29
Each WEND statement must have a matching WHILE statement.

Also verify that other control structures within the
WHILE...WEND structure are correctly matched. For
example, an IF without a matching ENDIF inside the
WHILE...WEND structure will generate this error.

ERR Code: 30
Two program lines were assigned the same number or label.
Each line number or label in a module must be unique.

Check all the SUB and function definitions in the module,
as well as the module-level code, for the duplicate label.
The Search menu's Find command is handy for this.
ERR code: 33
You are attempting to call a SUB that QuickBASIC cannot
find in any loaded module or Quick library.

ERR Code: 35
An incorrect number of arguments was used in a
SUB or function call.

Compare the DECLARE statement for the SUB or function
with the CALL statement to make sure the argument list
has the same number of items in both cases. You can
use the Search menu's Find command to look at the DECLARE
statement.

ERR Code: 37
Your program is attempting to use an array that is not
currently defined.

Make sure the array is defined with a DIM or REDIM
statement.

ERR code: 38
No matching case was found for an expression in a SELECT
CASE statement.

ERR code: 39
A GET or PUT statement must specify a variable when
operating on a file opened in binary mode.

ERR code: 40
A FIELD statement attempted to allocate more bytes than
were specified for the record length of a random-access
file.

ERR code: 50
An internal malfunction occurred in QuickBASIC.

Use the Product Assistance Request form at the back of
Learning and Using Microsoft QuickBASIC to report the
conditions under which the message appeared.

(Do not report this if you generated the error message
by executing a BASIC ERROR 51 statement.)

ERR code: 51
Be sure file names and numbers are as follows:
  ■ Valid file numbers are integers between 1 and 255.
  ■ Valid file numbers refer to files that are currently
    open
  ■ Valid file names use DOS file naming rules. For
    example, the file name extension must be three or
    less characters.

ERR code: 52
A FILES, KILL, NAME, OPEN or RUN statement referenced a
file that does not exist.

ERR code: 53
This error occurs when the program is trying to
  ■ Use PUT or GET statements with a sequential file
  ■ Use a FIELD statement with a file not opened for
    random access
  ■ Write to a file opened for input
  ■ Read from a file opened for output or appending.

ERR code 54
This message appears if you attempted to use
  ■ An OPEN statement for a sequential file that
    was already open
  ■ A KILL statement referring to an open file

ERR code: 55
A GET or PUT statement specified a record variable on a
file for which FIELD statements had been executed.

GET or PUT with a record-variable argument may only be
used on files where no FIELD statements have been
executed.

ERR code: 56
An I/O error occurred on a device I/O operation.

The operating system cannot recover from the error.

ERR code: 57
The file name specified in a NAME statement was identical
to a file name already on the disk.

ERR code: 58
A GET or PUT statement was executed to specify a record
variable whose length did not match the record length
specified in the corresponding OPEN statement.

ERR code: 59
There wasn't enough room on the disk to complete 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.

ERR code: 61
An INPUT statement read from a null (empty) file or from
a file in which all data have already been read.

Use the EOF function to detect the end of file.

ERR code: 62
The record number in a PUT or GET statement was less than
or equal to zero.

ERR code: 63
An illegal form was used for the file name with LOAD,
SAVE, KILL, or OPEN (for example, the file name had
too many characters).

ERR code 64
At compile time, this error occurs when include files are
nested more than five levels deep.

At run time, QuickBASIC limits the number of disk files
that can be open at any one time, and your program
has exceeded that limit. Either increase the FILES=
parameter in the CONFIG.SYS file, or simplify your
program.

DOS has a limit to the number of entries in a root
directory. If your program is opening and closing files
in a root directory, change your program so it uses a
subdirectory.

ERR code: 67
The device you attempted to access is not on line or
does not exist.

ERR code: 68
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. So,
  ■ Check the buffer more frequently (with the LOC
    function)
  ■ Empty the buffer more often (with the INPUT$
    function).

ERR code: 69
An attempt was made to write to a write-protected disk,
a read-only file, or to access a locked file.

ERR code: 70
The disk-drive door is open, or no disk is in the drive.

ERR code: 71
Disk-drive hardware has detected a physical flaw on the
disk.

ERR code: 72
You are attempting to use a QuickBASIC feature that is
is available with another version of BASIC or supported
only under a later version of DOS or OS/2.

ERR code 73
An attempt was made to rename a file with a new drive
designation. This is not allowed.

You can rename a file with a new drive designation by
loading the file and then saving it to the new drive
with a new file name. Then erase the original copy
of the file.
ERR code: 74
During execution of an OPEN, MKDIR, CHDIR, or RMDIR
statement, the operating system was unable to make a
correct connection between the path name and the
file name.

The operation is not completed.

ERR code: 75
During an OPEN, MKDIR, CHDIR, or RMDIR operation, DOS was
unable to find the path specified.

The operation is not completed.

ERR code: 76
This error is caused by executing an ERROR command with
an ERR code value that is not recognized by QuickBASIC.
For example, executing the statement ERROR 66 will cause
this error.
Choose <Yes> only if you are sure that by overwriting the
contents of the file on disk with the file contents in
memory you won't lose valuable information.
Otherwise,
  ■ Choose <No> to redisplay the dialog box and enter a
    new, unique disk-file name for saving the file in
    memory. Or,
  ■ Choose <Cancel> to stop the command, leaving everything
    just as it was before you chose this command.
QuickBASIC cannot load a document file larger than 64K.

Use another editor to divide your document into separate
files, none of which exceed 64K.
QuickBASIC cannot load an include file larger than 64K.

Use another editor to divide your include file into
separate files, none of which exceed 64K.
The file named in the QB invocation line or in an Open
Program dialog box is a multiple-module program and the
Full Menus option is off.

Turn on Full Menus to work with a multiple-module
program. Then,
  ■ Choose <OK> to continue loading the program. Or,
  ■ Choose <Cancel> if you don't want to load the program.
Include file text is displayed in the View window along
with program text, but the include file text is read-only.
If you want to edit the include file, you must put it in
a separate View window.
  ■ Choose <OK> to move the include file text into a
    new View window so you can edit it.
Include file text is displayed in the View window along
with program text. If you want to edit the program, you
must remove the include file from the View window.
  ■ Choose <OK> to remove the read-only include file from
    the View window so you can start editing program text.
    The Include Lines command will also be turned off.
You have referred to your removable disk drive as A: when
it is named B:, or B: when it is named A:.

Make sure the file you want this command to operate on
is in the removable disk drive, then choose <OK>.
QuickBASIC renames the drive for you.
You may
  ■ Work with the file already loaded in memory
  ■ Unload the file that is already in memory so you
    can load this one
  ■ Look at the list of files available for loading.
    You may have tried to load the wrong one.
The file you attempted to load contains at least one
procedure definition, and there is already a file in
memory with a procedure of the same name.

Rename or delete the procedure definition in one of the
files, preferably the file in memory.
When QuickBASIC loaded a multiple-module program, it
could not find one of the modules listed in the .MAK file.
To complete the load process, QuickBASIC created an empty
module to satisfy the .MAK file's module list.

When you rerun the program, QuickBASIC lets you
  ■ Choose <OK> to delete the empty module and the .MAK
    file entry for the module.
  ■ Choose <Cancel> to cancel this run operation so you
    can either
      - reconcile the .MAK file entry with the module file
        you may have in a different directory, or
      - save the program text you may have just entered into
        the empty module so you can try running it again.
You entered the name of a procedure in a text box that is
  ■ More than 40 characters long, or
  ■ Does not begin with a letter, or
  ■ Contains characters other than letters, numbers, or
    the special characters ., %, &, !, #, or $
You chose <OK> in a dialog box when the contents of the
text box were blank. When you clear this help dialog box,
you should type a module or procedure name in the text box.
During debugging, you used the Next Statement command to
specify a statement that is in a procedure other than
the one where program execution is suspended. QuickBASIC
ignores the Next Statement command.

Move the suspended procedure into the View window and, if
you still want to use a Next Statement command, use it
to start running from a statement in that procedure.
QuickBASIC requires that all DATA statements in a program
be in the module-level code. This message informs you
that QuickBASIC has moved DATA statements to the
module level.
This may occur when you are working with a multiple-
module program and use the Save As command to rename
one of the modules as you save it.

If any of the other files loaded into memory have this
file name, you get this message.

Use another filename in the Save As dialog box.
Before completing execution, the SUBs command needs
confirmation that you want to delete this procedure
from the current module. Either
  ■ Choose <OK> to execute the command and delete the
    procedure. Or,
  ■ Choose <Cancel> to stop the command, leaving everything
    as it was before you chose the command.
Ordinarily the SUB or FUNCTION statement that begins a
procedure is the first line in the View window. When you
try to use the smart editor to put a blank line above
the SUB or FUNCTION statement, the editor always transforms
that blank line into a comment line.
An ASCII file that contains tabs is currently loaded in
memory, so you can't use the Display Command's Tab Stops
Option to change the value of a tab stop.

Unload the ASCII file, then change the Tab Stops option.
You selected the wrong type of item from the SUBs command
list box when choosing the <Move>.

In the SUBs dialog box, the type of each item in the list
box is shown just below the list box each time that item
is highlighted.
This often occurs while you are debugging. While your
program is suspended (at a breakpoint, for example) you
made a change to the program that has implications
throughout the program, not just at the point where you
made the change. You may have redimensioned an array,
changed procedure arguments, or edited some other
declarative statement. Either
  ■ Choose <OK> to keep the change and restart the
    program. Or,
  ■ Choose <Cancel> to have QuickBASIC undo the change in
    your program text. You may do this if restarting the
    program interferes with your debugging strategy.
All the loaded modules are shown in the list box. Choose
the one you want to be the main module.

When you start running a program, the first executable
statement in the main module is always the first statement
executed.
You are about to clear the contents of memory and one or
more files are loaded in memory that have not been saved
since the last time they were changed. Either
  ■ Choose <Yes> to save the file or files and then
    execute the command. If one of the files is not named,
    you will be prompted for it's file name.
  ■ Choose <No> to clear memory without saving the files,
    then execute the command.
  ■ Choose <Cancel> to stop the command, leaving the
    contents of memory the same as before you chose the
    command.
You are attempting to run the program after you have
unloaded the main module. Every program must have a main
module so QuickBASIC knows where to start running the
program. Either
  ■ Use the Load File command from the File menu to
    reload the main module you unloaded. Or,
  ■ Use the Set Main Module command from the Run menu
    to assign the role of "main module" to one of the
    currently loaded modules.
Identifiers must not be longer than 40 characters.
Identifiers cannot end with %, &, !, #, or $.

The above suffixes are not allowed in type identifiers,
subprogram names, or named COMMON blocks.
User-defined type identifier and record-element names
cannot contain periods. The period should be used only
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 AS clause that defined a user datatype
anywhere in the program.

If you have programs that use the period in variable names,
you should change them to mixed case.  For example,
variable ALPHA.BETA would become AlphaBeta.
Certain internal limitations of QuickBASIC have been
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. Likewise, a numeric expression with many
complicated subexpressions can cause this error.

Try:
  ■ simplifying expressions
  ■ assigning strings to variables.
The format of the number does not correspond to the number
format expected by QuickBASIC.

You have probably made a typographical error. For example,
the number 2p3 produces this error.

To see the valid formats, use the QB Advisor help system.
Choose the Help menu's Contents command, then choose the
hyperlink to the Data Types topic.
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.
This statement is not allowed in module-level code.
The statement is not allowed in module-level code or DEF FN
functions.
The statement is not allowed inside a SUB, FUNCTION, or
DEF FN.
The only statements allowed before a procedure definition
are REM and DEFtype.
The terminating statement is missing from a procedure.
The SUB or FUNCTION statement is missing from a procedure.
You may have deleted it during editing.
An END DEF statement has no corresponding DEF statement.

Also check other control structures within the
DEF...END DEF structure and verify that they are correctly
matched. For example, an IF without a matching ENDIF inside
the DEF...END DEF structure generates this error.
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.
No TYPE...END TYPE statement exists in this module for the
user-defined type.
  ■ You may have misspelled the user-defined type name
  ■ You can use the Search menu's Find command to locate all
    the TYPE...END TYPE definitions in this module.
In block IF...THEN...ELSE constructs, IF, ELSE, ELSEIF, and
END IF can only be preceded by a line number or label.

In SELECT...END SELECT constructs, CASE and END SELECT can
only be preceded by a line number or label.
You are attempting to add code after a procedure.

You must either return to the main module or open another
module.
There is no END TYPE statement associated with a TYPE
statement.
An END TYPE statement is used outside a TYPE declaration.
The only statements allowed between the TYPE and END TYPE
statements are
  ■ REM
  ■ AS datatype clause
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.
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.
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.
You are attempting to load from, or save to, a nondisk
device such as the printer or keyboard.
The syntax of a metacommand is incorrect.

Metacommands must be embedded in comments.

Note that the syntax of the $INCLUDE metacommand is
as follows:

  REM $INCLUDE: 'filespec'
  or
  ' $INCLUDE: 'filespec'
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.
  ■  An attempt to redimension a dynamic array with a
     DIM statement without using the ERASE statement to
     deallocate the array first.
  ■  An OPTION BASE statement that occurs after an
     array is dimensioned.
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
The beginning of an IF block is missing.

Also check other control structures within the IF...ENDIF
block and verify that they are correctly matched. For
example, a nested IF block without a matching ENDIF
inside the outer IF...ENDIF block generates this error.
There is no corresponding END IF in a block IF construct.
An ELSE clause appears without a corresponding IF.
Sometimes this error is caused by incorrectly nested IF
statements.

Also check other control structures within the IF...ENDIF
block and verify that they are correctly matched. For
example, a nested IF block without a matching ENDIF
inside the outer IF...ENDIF block generates this error.
An EXIT FOR statement is used outside of a FOR...NEXT
statement.
An EXIT DO statement is used outside of a DO...LOOP
statement.
The terminating LOOP clause is missing from a DO...LOOP
statement.
The DO starting a DO...LOOP statement is missing or
misspelled.

Also check other control structures within the DO...LOOP
structure and verify that they are correctly matched. For
example, an IF block without a matching ENDIF inside the
DO...LOOP structure generates this error.
The end of a SELECT CASE statement is missing or misspelled.
The first part of a SELECT CASE statement is missing or
misspelled.

Also check other control structures within the
SELECT...END SELECT structure and verify that they are
correctly matched. For example, an IF block without a
matching ENDIF inside the SELECT...END SELECT structure
generates this error.
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.

Also check other control structures within the
SELECT...END SELECT structure and verify that they are
correctly matched. For example, an IF block without a
matching ENDIF inside the SELECT...END SELECT structure
generates this error.
You cannot use a fixed-length string as a formal parameter
to a SUB or function.
Variables that are user-defined types are not permitted in
expressions such as

  CALL Alpha((X))

where X is a user-defined type. You can pass elements of
user-defined types as arguments. For example

  CALL Alpha((X.FirstEl))
There is no corresponding END DEF in a multi-line function
definition.
A subprogram or FUNCTION parameter type does not match the
DECLARE statement's argument or the calling argument.
A procedure in the Quick library has the same name as a
procedure in your program.
A variable that has not been declared using an AS clause is
being referenced with an AS clause.
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.
Statements and line labels are not permitted between
SELECT CASE and the first CASE statement.

Comments and statement separators are permitted.
Numeric arrays are not allowed as arguments to VARPTR$.

Only simple variables and string array elements are
permitted.
The "element AS type" clause is permitted only within a
TYPE...END TYPE block.
More COMMON variables are specified in the module than in
the currently loaded Quick library.
An array reference contains the wrong number of dimensions.
DEF FN function definitions are not permitted inside control
constructs such as IF...THEN...ELSE and  SELECT CASE.
The file you attempted to compile is not an ASCII file.

All source files saved by BASICA should be saved with the
,A option.
      WARNING: program contains unsupported types
    WARNING: program contains unsupported statements
While debugging, you have made a change that prevents
execution from continuing.
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 accomplishes
     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 256 characters.
     Such lines require allocation of additional
     text buffer space.

ERR code: 7
Your module-level code exceeds QuickBASIC's internal limit.
Try moving some of the code into SUB or FUNCTION procedures.
The procedure has exceeded QuickBASIC's internal limit.

Make the procedure smaller by dividing it into several
procedures.
This error occurs when a recursive FUNCTION nests too
deeply, or there are too many active subroutine,
FUNCTION, and SUB calls.

Use the CLEAR statement to increase the program's allotted
stack space.

This error cannot be trapped.
Survival Guide   ◄How to Use Menus and Commands►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
  Tip: The Reference Bar at the bottom of the screen always contains help
       about the most useful commands in each QuickBASIC context. If the
       command name has angle brackets around it, it can be executed from
       the Reference Bar by choosing it with the mouse.

  Use the Menu Bar at the top of the screen to tell QuickBASIC what to do.

Menu Action             With a mouse...             With a keyboard...
Pull down a menu        Move mouse cursor to        Press and release ALT to
                        menu name, then press       highlight menu letters,
                        and release ("click")       then press letter key
                        the left mouse button.      for menu you want.

Choose a command        Move mouse cursor to        Press letter key that
                        command name and            matches the highlighted
                        click                       letter on the command.

Cancel a command        Move mouse cursor out-      Press ESC
                        side menu and click
Survival Guide   ◄How to Use a Dialog Box►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
 Dialog boxes appear immediately after you choose a command in some cases.
┌─────────────Save As────────────┐
│                                │    The dialog box pictured at the
│ File Name: ▒▒▒▒▒▒▒▒▒▒▒▒        │    left gives you the chance to
│                                │    input three items:
│ Dirs/Drives         Format     │      ■ a file name
│ ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒ QuickBASIC  │      ■ a disk drive or directory
│ ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒             │      ■ a choice between two file formats
│ ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒ Text        │
│                                │
├────────────────────────────────┤◄───Use the choices below this line to:
│     ▒▒▒       ▒▒▒       ▒▒▒    │      ■ execute the command
└────────────────────────────────┘      ■ cancel the command, or
                                        ■ display help about the dialog box.

Dialog Box Action      With a mouse...             With a keyboard...
Select an input area   Move the mouse cursor to    Press TAB repeatedly
                       a characteristic shape      until the cursor is in
                       within the dialog box.      the area you want.

  Tip: Input areas within a dialog box are marked by a rectangle, a list of
       items within a box, a pair of brackets, or a pair of parentheses.

Choose an item from    Highlight the item by       Highlight the item by
a list                 moving the mouse and then   pressing the DIRECTION
                       press the left mouse        keys and then press
                       button twice in             ENTER.
                       succession.

Choose an option       Move the mouse cursor       Move the bullet with
(place a bullet        between the parentheses     the DIRECTION keys
between a pair of      and click the left
parentheses)           button.

Turn a check box on    Move the mouse cursor       Use TAB to move the
or off                 between the square          cursor between the square
                       brackets and click          brackets, then press the
                                                   SPACEBAR
Choose a command       Move the mouse cursor       Use TAB to move the
button                 between the angle           cursor between the
                       brackets and click          angle brackets and press
                                                   ENTER
Survival Guide   ◄How to Select Text►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
You need to select (or highlight) blocks of text to carry out some commands

Action                 With a mouse...             With a keyboard...
Select (highlight)     Move the mouse cursor       Move the cursor to the
text                   to the point where you      point you want to begin
                       want highlighting to        highlighting, using the
                       begin. Then hold down       DIRECTION keys. Then hold
                       the left mouse button       down the SHIFT key while
                       while you drag the mouse    you use the DIRECTION keys
                       across the text. Release    to highlight your text.
                       the mouse button to
                       end the selection.
Survival Guide   ◄How to Use QB Advisor Help►   Contents   Index
──────────────────────────────────────────────────────────────────────────────
  Tip: The Reference Bar at the bottom of the screen always contains help
       about the most useful commands in each QuickBASIC context.

QB Advisor help text is available about the BASIC language at all times.

Action                 With a mouse...             With a keyboard...
Get help on a BASIC    Move the mouse cursor       Move the cursor to the
keyword from your      to the keyword and click    keyword and press F1.
program text.          the right mouse button.

To get help on a       Move the mouse cursor       Move the cursor to the
program object         to the symbol and click     symbol and press F1.
(a variable, a         the right mouse button.
procedure, etc.)
from your program
text.

To get help on other   Move the mouse cursor       Repeatedly press TAB or
topics.                to the hyperlink for        the key that corresponds
                       that topic and click        to the first letter in
                       the right mouse button.     the hyperlink until the
                                                   cursor moves into the
                                                   hyperlink you want. Then
                                                   press F1.

To retrace a path                                  Repeatedly press ALT+F1
of hyperlinks                                      until the contents of
you chose                                          the Help window are
                                                   restored to what you need.

On-line help is also available about items in the QuickBASIC environment:
menus, commands, dialog boxes (including error message dialog boxes).

Action                 With a mouse...             With a keyboard...
Get help on a menu.                                Select the menu name from
                                                   the menu bar and press F1.

Get help on a                                      Select the command and
command.                                           press F1.

Get help on a          Move the mouse cursor to    Press F1.
dialog box.            the <Help> button within
                       the dialog box and click
                       the left mouse button.
  ◄Help on Help►     Contents   Index
──────────────────────────────────────────────────────────────────────────────
  Use help as follows:

    ■ To get help at any time, press F1 or click the right mouse button.
    ■ To get help on any part of a BASIC statement, a QuickBASIC menu item
      or dialog box, position the cursor there press F1.
    ■ To remove the help information from the screen, press ESC.
    ■ To scroll help information, press PGDN.

  Look for the help display in either
    ■ The Help window at the top of the screen
    ■ A dialog box which pops up in the center of the screen

  In the Help window, use hyperlinks to display information about
  related topics.
    ■ All BASIC keywords are hyperlinks
    ■ Other hyperlinks can be identified because
      - Visually, they are bounded by highlighted arrowheads.
      - Pressing the TAB key moves the cursor to a hyperlink.

  To display the information that a hyperlink refers to, position the
  cursor anywhere on the hyperlink and press F1 or click the right
  mouse button.

  Tip: Press F6 or SHIFT+F6 to move the cursor into the Help window or
       move the mouse cursor into the Help window and click the left button.

  QuickBASIC saves the twenty most recently used hyperlinks. To review
  them press ALT+F1, repeatedly.

  You can use QuickBASIC commands to
    ■ Copy text, such as a programming example, out of the Help window
      and paste it into the View window
    ■ Find other uses of a term you want help on in the Help files.
      This is useful if the term is not a hyperlink.

  An alternative to the Help shortcut keys F1 and ALT+F1 is the Help
  menu commands. To pull down the Help menu, press ALT+H. Then,
  to choose a Help menu command, press the letter key that matches
  the highlighted letter in the command you want.

  Here is a summary of the Help menu commands:

    Command          Action
    ■ Index          Lists all the BASIC keywords as hyperlinks in the
                     Help window
    ■ Contents       Lists a set of general topics about BASIC and
                     QuickBASIC as hyperlinks in the Help window. For
                     example, this is the way to display information
                     about BASIC data types or expression operators.
    ■ Topic:         Displays help on the item where the cursor is
    ■ Help on Help   Displays the text you have just finished reading.
                     To display this help on help text at any time,
                     press SHIFT+F1.
  Help on Help   ◄Contents►   Index                         Copyright
──────────────────────────────────────────────────────────────────────────────
Using QuickBASIC                      BASIC Programming Language
  │                                       │
  ├─ Shortcut Key Summary               ├─ Functional Keyword ListsEdit Keys                      ├─ Syntax Notation ConventionsView Keys                      │
  │      Search Keys                    ├─ Fundamental Building BlocksRun and Debug Keys             ├─ Data TypesHelp Keys                      ├─ Expressions and Operators
  │                                       ├─ Modules and Procedures
  ├─ Limits to QuickBASIC               ├─ Selected Programs
  ├─ Version 4.5 Differences            │
  ├─ QB Command Line Options            ├─ ASCII Character Codes
  └─ Survival Guide                     └─ Keyboard Scan Codes
  Help on Help     Contents     ◄Index►
──────────────────────────────────────────────────────────────────────────────
To get help on a particular QuickBASIC keyword in the list below:
  1. To move the cursor to the sublist of all keywords that start with
     the same letter, press the key of the first letter of the keyword
  2. Use the DIRECTION keys to move the cursor to the keyword
  3. Press F1 to display the help text in the Help window
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ A ║
                                                                  ╚═══╝
  ABS Function                       APPEND
  ACCESS                             AS
  ALIAS                              ASC Function
  AND Operator                       ATN Function
  ANY
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ B ║
                                                                  ╚═══╝
  BASE                               BLOAD Statement
  BASIC Program Lines                BSAVE Statement
  BEEP Statement                     BYVAL
  BINARY
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ C ║
                                                                  ╚═══╝
  CALL Statement                     CLS Statement
  CALLS Statement                    COLOR Statement
  CALL ABSOLUTE Statement            COM Statement
  CALL INTERRUPT Statement           COMMAND$ Function
  CASE                               COMMON Statement
  CDBL Function                      CONST Statement
  CDECL                              COS Function
  CHAIN Statement                    CSNG Function
  CHDIR Statement                    CSRLIN Function
  CHR$ Function                      CVD Function
  CINT Function                      CVDMBF Function
  CIRCLE Statement                   CVI Function
  CLEAR Statement                    CVL Function
  CLNG Function                      CVS Function
  CLOSE Statement                    CVSMBF Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ D ║
                                                                  ╚═══╝
  DATA Statement                     DEFINT Statement
  Data Types                         DEFLNG Statement
  DATE$ Function                     DEFSNG Statement
  DATE$ Statement                    DEFSTR Statement
  DECLARE (BASIC) Statement          DIM Statement
  DECLARE (Non-BASIC) Statement      DO...LOOP Statement
  DEF FN Statement                   DOUBLE
  DEF SEG Statement                  DRAW Statement
  DEFDBL Statement                   $DYNAMIC Metacommand
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ E ║
                                                                  ╚═══╝
  ELSE                               ERDEV Function
  ELSEIF                             ERDEV$ Function
  END Statement                      ERL Function
  ENDIF                              ERR Function
  ENVIRON Statement                  ERROR Statement
  ENVIRON$ Function                  EXIT Statement
  EOF Function                       EXP Function
  EQV Operator                       Expressions and Operators
  ERASE Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ F ║
                                                                  ╚═══╝
  FIELD Statement                    FOR...NEXT Statement
  FILEATTR Function                  FRE Function
  FILES Statement                    FREEFILE Function
  FIX Function                       FUNCTION Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ G ║
                                                                  ╚═══╝
  GET (File I/O) Statement           GOSUB Statement
  GET (Graphics) Statement           GOTO Statement

                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ H ║
                                                                  ╚═══╝
  HEX$ Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ I ║
                                                                  ╚═══╝
  IF...THEN Statement                INPUT$ Function
  IMP Operator                       INSTR Function
  $INCLUDE Metacommand               INT Function
  INKEY$ Function                    INTEGER
  INP Function                       IOCTL Statement
  INPUT Statement                    IOCTL$ Function
  INPUT # Statement                  IS
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ K ║
                                                                  ╚═══╝
  KEY Statement                      KILL Statement
  KEY(n) Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ L ║
                                                                  ╚═══╝
  LBOUND Function                    LOCATE Statement
  LCASE$ Function                    LOCK...UNLOCK Statements
  LEFT$ Function                     LOF Function
  LEN Function                       LOG Function
  LET Statement                      Logical Operator Truth Table
  LINE (Graphics) Statement          LONG
  LINE INPUT Statement               LOOP
  LINE INPUT # Statement             LPOS Function
  LIST                               LPRINT Statements
  LOC Function                       LSET Statement
  LOCAL                              LTRIM$ Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ M ║
                                                                  ╚═══╝
  MID$ Function                      MKL$ Function
  MID$ Statement                     MKS$ Function
  MKD$ Function                      MKSMBF$ Function
  MKDIR Statement                    MOD
  MKDMBF$ Function                   Modules and Procedures
  MKI$ Function

                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ N ║
                                                                  ╚═══╝
  NAME Statement                     NOT Operator
  NEXT
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ O ║
                                                                  ╚═══╝
  OCT$ Function                      ON UEVENT Statement
  OFF                                ON...GOSUB Statement
  ON                                 ON...GOTO Statement
  ON COM(n) Statement                OPEN (File I/O) Statement
  ON ERROR Statement                 OPEN COM Statement
  ON event Statements                Operator Precedence Rules
  ON KEY(n) Statement                OPTION BASE Statement
  ON PEN Statement                   OR Operator
  ON PLAY(n) Statement               OUT Statement
  ON STRIG(n) Statement              OUTPUT
  ON TIMER(n) Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ P ║
                                                                  ╚═══╝
  PAINT Statement                    POINT Function
  PALETTE Statements                 POKE Statement
  PCOPY Statement                    POS Function
  PEEK Function                      PRESET Statement
  PEN Function                       PRINT Statement
  PEN Statement                      PRINT USING Statement
  PLAY(n) Function                   PRINT # Statement
  PLAY (Music) Statement             PSET Statement
  PLAY (Event Trapping) Statements   PUT (File I/O) Statement
  PMAP Function                      PUT (Graphics) Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ R ║
                                                                  ╚═══╝
  RANDOM                             RETURN Statement
  RANDOMIZE Statement                RIGHT$ Function
  READ Statement                     RMDIR Statement
  REDIM Statement                    RND Function
  REM Statement                      RSET Statement
  RESET Statement                    RTRIM$ Function
  RESTORE Statement                  RUN Statement
  RESUME Statement
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ S ║
                                                                  ╚═══╝
  SADD Function                      SPC Function
  SCREEN Function                    SQR Function
  SCREEN Statement                   STATIC Statement
  SEEK Function                      $STATIC Metacommand
  SEEK Statement                     STEP
  SELECT CASE Statement              STICK Function
  SETMEM Function                    STOP Statement
  SGN Function                       STR$ Function
  SHARED Statement                   STRIG Function
  SHELL Statement                    STRIG Statements
  SIGNAL                             STRING
  SIN Function                       STRING$ Function
  SINGLE                             SUB Statement
  SLEEP Statement                    SWAP Statement
  SOUND Statement                    SYSTEM Statement
  SPACE$ Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ T ║
                                                                  ╚═══╝
  TAB Function                       TIMER Statement
  TAN Function                       TO
  THEN                               TROFF Statement
  TIME$ Function                     TRON Statement
  TIME$ Statement                    TYPE Statement
  TIMER Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ U ║
                                                                  ╚═══╝
  UBOUND Function                    UNLOCK Statement
  UCASE$ Function                    UNTIL
  UEVENT Statement                   USING
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ V ║
                                                                  ╚═══╝
  VAL Function                       VARSEG Function
  Variable Scope Rules               VIEW (Graphics) Statement
  VARPTR Function                    VIEW (Text) Statement
  VARPTR$ Function
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ W ║
                                                                  ╚═══╝
  WAIT Statement                     WINDOW Statement
  WEND                               WRITE (Screen I/O) Statement
  WHILE...WEND Statement             WRITE (File I/O) Statement
  WIDTH Statements
                                                                  ╔═══╗
══════════════════════════════════════════════════════════════════╣ X ║
                                                                  ╚═══╝
  XOR Operator
SIGNAL Keyword

  The SIGNAL keyword is reserved for future use.
LOCAL Keyword

  The LOCAL keyword is reserved for future use.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ABS - a math function that returns the absolute value of a numeric
      expression

Syntax
  ABS(numeric-expression)
ACCESS Clause

Syntax
  {ACCESS READ | ACCESS WRITE | ACCESS READ WRITE}

The ACCESS clause is used in the OPEN statement. It works only if you
are using a version of DOS that supports networking (DOS Versions 3.0
or later).

  ■ READ          Opens a file for reading only.
  ■ WRITE         Opens a file for writing only.
  ■ READ WRITE    Opens a file for both reading and writing. This mode
                  is valid only for RANDOM and BINARY files and files
                  opened for APPEND.

See Also  OPEN
ALIAS Clause

Syntax
  ALIAS "name-in-Quick-Library"

The ALIAS clause in a DECLARE statement announces to QuickBASIC that the
name of a procedure in a Quick library is different from the name you will
use in your program to call that procedure.

See Also  DECLARE (Non-BASIC)
AND Operator

Syntax
  result=numeric-expression1 AND numeric-expression2

The AND logical-conjunction operator compares corresponding bits in two
numeric expressions and sets the corresponding bit in the result to 1
if both bits are 1. The AND operator use this "truth table":

─────────────────────────────────────────────────────────────────
Bit in First Expression   Bit in Second Expression   Bit in Result
─────────────────────────────────────────────────────────────────
           1                       1                      1
           1                       0                      0
           0                       1                      0
           0                       0                      0
──────────────────────────────────────────────────────────────────
ANY Clause

Syntax
  variable AS ANY

When used as the variable type in an AS type clause that is part
of a procedure declaration, ANY disables type checking for that
parameter.

See Also  DECLARE
APPEND Keyword

The APPEND keyword in an OPEN statement specifies that the file is
to be opened for sequential access, and sets the file pointer to the
end of the file. PRINT # or WRITE # statements then append to (extend)
the file.

See Also  OPEN  PRINT #  WRITE #
AS Clause - Different Uses
See Also
To specify a variable's type in a declarative statement or parameter list:
    COMMON                                FUNCTION
    DECLARE SUB                           REDIM
    DECLARE FUNCTION                      SHARED
    DEF FN                                STATIC
    DIM                                   SUB
To specify an element's type in a user-defined data type:
    TYPE...END TYPE
To assign a file number to a file or device in an OPEN statement:
    OPEN
To specify a field name in a random-access record:
    FIELD
To specify a new file name when you rename a file:
    NAME
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ASC - a string processing function that returns a numeric value
      that is the ASCII code for the first character in a string
      expression

Syntax
  ASC(stringexpression)

See Also  ASCII Character Codes  CHR$
◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ATN - a math function that returns the arctangent of a numeric
      expression (the angle whose tangent is equal to the numeric
      expression)

Syntax
  ATN(numeric-expression)

See Also  TAN  SIN  COS
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BEEP - a device I/O statement that sounds the speaker

Syntax
  BEEP
RANDOM Keyword

An optional keyword in the OPEN statement, RANDOM specifies random-access
file mode. In random-access mode, you may read or write information to any
record position in the file using GET or PUT statements.

See Also  OPEN  PUT  GET
BINARY Keyword

BINARY is used in an OPEN statement to specify binary file mode. In
binary mode, you may read or write information to any byte position in
the file using GET or PUT statements.

See Also  OPEN  PUT  GET
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BLOAD - a file I/O statement that loads a memory-image file,
        created by BSAVE, into memory from an input file or device

Syntax
  BLOAD filespec[,offset]
    ■ filespec is a string expression that specifies the file or device
      from which to load the memory-image file
    ■ offset is a Detail that lets you load the file into a precise
      memory location

See Also  BSAVE - to see how to create the memory-image file
          DEF SEG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
BSAVE - a file I/O statement transfers the contents of an area
        of memory to an output file or device

Syntax
  BSAVE filespec,offset,length
    ■ filespec, a string expression, specifies the file or device on which
      to save the memory-image file
    ■ offset, a numeric expression, is the number of bytes beyond the start
      of the memory segment from which to start saving
    ■ length, a numeric expression that has an unsigned integer value
      between 0 and 65,535, is the number of memory bytes to save

See Also  DEF SEG  BLOAD
BYVAL Clause

Syntax
  BYVAL variable [AS type]

The BYVAL attribute in the parameter list of a DECLARE statement causes
the value of the specified variable to be passed to the procedure, rather
than the variable's address. BYVAL can only be used in DECLARE statements
for non-BASIC procedures, and cannot be applied to string parameters.

See Also  CALLS or CALL (Non-BASIC) statements
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL - a statement that transfers control to another procedure, a
       BASIC SUB
Syntax
  CALL name[(argumentlist)]
    ■ name is the name of the SUB
    ■ argumentlist lists the variables or constants passed to the SUB

See Also  DECLARE  SUB...END SUB
Other Uses
  CALLS - to transfer control to a procedure written in another language
  CALL ABSOLUTE - to transfer control to a machine-language procedure
  CALL INTERRUPT - to perform a DOS system call
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL, CALLS - Statements that transfer control to a procedure written
              in another programming language
Syntax
  CALL name [(call-argumentlist)]
  name [call-argumentlist]
  CALLS name [(calls-argumentlist)]
    ■ name identifies the procedure being called
    ■ call-argumentlist, if used, has the syntax
        [{BYVAL|SEG}]argument[()][,{BYVAL|SEG}]argument[()]] ...
      (see Details)
    ■ calls-argumentlist, if used, has the syntax
        argument[,argument] ...

See Also  DECLARE (Non-BASIC) statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL ABSOLUTE - a statement that transfers control to a machine-language
                procedure
Syntax
  CALL ABSOLUTE([argumentlist,]integervariable)
    ■ argumentlist, if used, contains the names of values in the current
      data segment
    ■ integervariable contains the offset from the current code segment,
      set by DEF SEG, to the starting location of the called procedure

See Also  CALLS or CALL(Non-BASIC) statements - which provide a simpler
          way to call assembly language procedures from BASIC
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CALL INTERRUPT - a statement that allows BASIC programs to perform
                 DOS system calls
Syntax
  CALL INTERRUPT(interruptnum,inregs,outregs)
  CALL INTERRUPTX(interruptnum,inregs,outregs)
    ■ interruptnum, an integer expression which has a value between
      0 and 255, is a DOS interrupt number
    ■ inregs contains the register values before the interrupt is performed
      (see Details for how to declare a user-defined type which will
      contain these register values)
    ■ outregs contains the register values after the interrupt
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CDBL - a conversion function that converts a numeric expression to a
       double-precision number

Syntax
  CDBL(numeric-expression)

See Also  CINT  CSNG  CLNG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHAIN - a program control statement that transfers control to another
        program
Syntax
  CHAIN filespec
    ■ filespec is a string expression that identifies the program to which
      control is passed. The filespec may include a path specification.

See Also  RUN - another way to transfer control to a program
          COMMON - which enables sharing of variables between chained
                     programs
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHDIR - a statement that uses DOS to change the current default directory
        for the specified drive

Syntax
  CHDIR pathspec
    ■ pathspec is a string expression that identifies the directory that
      is to become the default directory

See Also  MKDIR  RMDIR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CHR$ - a string processing function that returns a one-character
       string whose ASCII code is the argument

Syntax
  CHR$(code)
    ■ code, a numeric expression that has a value between 0 and 255,
      is one of the ASCII character codes

See Also  ASC  ASCII Character Codes
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CINT - a conversion function that converts a numeric expression to
       an integer by rounding the fractional part of the expression

Syntax
  CINT(numeric-expression)

See Also  CDBL  CSNG  CLNG  FIX  INT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CIRCLE - a graphics statement that draws an ellipse or circle
         with a specified center and radius
Syntax
  CIRCLE [STEP] (x,y),radius[,[color][,[start][,[end][,aspect]]]]
    ■ (x,y) are the screen coordinates of the center of the circle or ellipse
    ■ radius, a numeric expression, is the radius
    ■ Use STEP if x and y are offsets from the current cursor position,
      rather than absolute screen coordinates
    ■ start and end can be used to draw arcs
    ■ color and aspect are Details

See Also  SCREEN Statement - to find out about the different screen
                               coordinate systems that are available
          LINE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLEAR - a memory management statement that reinitializes all program
        variables, closes files, and optionally sets the stack size.

Syntax
  CLEAR [,,stack]
    ■ stack is a Detail, it lets you set the stack size

See Also  ERASE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLNG - a conversion function that converts a numeric expression to a
       long (4-byte) integer by rounding the fractional part of the
       expression

Syntax
  CLNG(numeric-expression)

See Also  CINT  CSNG  CDBL
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLOSE - a file I/O statement that concludes I/O to a file or device

Syntax
  CLOSE [[#]filenumber[,[#] filenumber]...]
    ■ If all arguments are omitted, all open files and devices are closed
    ■ filenumber is the number of an open file

See Also  OPEN  RESET  END  STOP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CLS - a  device I/O statement that clears the display screen

Syntax
  CLS [{0|1|2}]
    ■ If all arguments are omitted, either the graphics viewport or the text
      viewport are cleared, depending upon previous uses of VIEW statement.
    ■ 0 clears the screen of all text and graphics.
    ■ 1 clears only the graphics viewport, if it is active.
    ■ 2 clears only the text viewport, leaving bottom screen line unchanged.

See Also  VIEW - to see how to activate the graphics viewport
          VIEW PRINT - to see how to set the text viewport
          WINDOW - to see how to customize the graphics viewport
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COLOR - a graphics statement that selects display colors

SCREEN Mode 0 Syntax:  COLOR [foreground][,[background][,border]]
   ■ foreground is the text color (range = 0-31, with 16-31 blinking)
   ■ background is the screen color (range = 0-7)
   ■ border is the color surrounding the screen (range = 0-15)
     0 = black       4 = red           8 = grey             12 = light red
     1 = blue        5 = magenta       9 = light blue       13 = light magenta
     2 = green       6 = brown        10 = light green      14 = yellow
     3 = cyan        7 = white        11 = light cyan       15 = bright white
SCREEN Mode 1 Syntax:  COLOR [background][,palette]
   ■ background is the screen color (range = 0-15)
   ■ palette is a three-color palette (range = 0-1)
     0 = green, red, and brown         1 = cyan, magenta, and bright white
SCREEN Modes 7-10 Syntax:  COLOR [foreground][,background]
   ■ foreground is the line-drawing color (range = 0-15, except in Mode 10)
   ■ background is the screen color (ranges vary)
SCREEN Modes 11-13 Syntax:  COLOR [foreground]
   ■ foreground is the line-drawing color (ranges vary)

See Also  SCREEN - to see how the combination of mode set by the SCREEN
                     statement, the graphics adapter, and the display
                     determine available color ranges.
          PALETTE - to see how to use color attribute numbers in screen
                      modes 7-10, 12, and 13.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COM(n) - an event trapping statement that enables, disables, or inhibits
         event trapping of communications activity on a specified port

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

    ■ n is the number of the communications port, either 1 or 2

See Also  ON COM(n)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMAND$ - a function that interfaces with DOS to return the command
           line used to invoke the program

Syntax
  COMMAND$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COMMON - a non-executable statement that declares global variables for
         sharing between modules, or for chaining to another program
Syntax
  COMMON [SHARED][/blockname/] variablelist
    ■ variablelist is one or more variables, separated by commas, that are
      to be shared between modules or chained-to programs
    ■ SHARED and /blockname/ are Details

See Also  SUB  FUNCTION  CALL  CHAIN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CONST - a non-executable statement that declares symbolic constants
        to use in place of numeric or string values

Syntax
  CONST constantname = expression [,constantname = expression]...
    ■ constantname is a name following the same naming rules as a BASIC
      variable. You may add to the name a type-declaration character
      (%, &, !, #, or $) to indicate its type (this character is not
      part of the name).
    ■ expression consists of literals, other constants, or any of the
      arithmetic and logical operators except exponentiation (^).
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
COS - a math function that returns the cosine of an angle given in
      radians

Syntax
  COS(numeric-expression)
    ■ numeric-expression, which may be of any type, is the angle, expressed
      in radians. See Details on how to convert degrees into radians.

See Also  SIN  TAN  ATN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSNG - a conversion function that converts a numeric expression to a
       single-precision value

Syntax
  CSNG(numeric-expression)

See Also  CDBL  CINT  CLNG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CSRLIN - a device I/O function that returns the current line (row)
         position of the cursor
Syntax
  CSRLIN

See Also  POS Function - which returns the current character position
                           of the cursor within a line
          LOCATE - to see how to move the cursor to a specific location
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVSMBF and CVDMBF - conversion functions that convert strings containing
                    Microsoft Binary format numbers to IEEE-format numbers
Syntax
  CVSMBF (4-byte-string)
  CVDMBF (8-byte-string)

See Also  MKSMBF$, MKDMBF$  CVD, CVI, CVL, CVS  MKD$, MKI$, MKS$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
CVI, CVS, CVL, CVD - functions that convert strings containing numeric
                     values to numbers
Syntax
  CVI(2-byte-string)
  CVS(4-byte-string)
  CVL(4-byte-string)
  CVD(8-byte-string)

See Also  MKD$, MKI$, MKS$  GET (File I/O)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATA - a non-executable statement that stores the numeric and string
       constants used by a program's READ statements

Syntax
  DATA  constant[,constant]...
    ■ constant is any valid numeric or string constant. If a string constant
      contains commas, colons, or leading or trailing spaces you want to
      preserve in your program, you must enclose the string in double quotes.

See Also  READ  RESTORE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DATE$ - a statement that uses DOS to set the current date

Syntax
  DATE$ = stringexpression
    ■ stringexpression must have one of the following forms:
        mm-dd-yy, mm-dd-yyyy, mm/dd/yy, or mm/dd/yyyy
      where mm and dd are the month and day, and yy or yyyy are the year

See Also  TIME$

Other Uses of the DATE$ Keyword
  DATE$ function - to get the current date from DOS
CDECL Keyword

  CDECL in a DECLARE statement that declares a non-BASIC procedure
  indicates that the declared procedure uses the C-language argument order.
  QuickBASIC will pass the arguments in the argument list from right to
  left, rather than from left to right as is the BASIC convention.

See Also  CALLS and CALL (Non-BASIC) statements
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DECLARE - a non-executable statement that declares references to
          BASIC procedures and invokes argument type checking
Syntax
  DECLARE {FUNCTION | SUB } name [([parameterlist])]
    ■ name is the name that will be used to call the procedure
    ■ parameterlist indicates the number and type of arguments that will
      be used to call the procedure

See Also  FUNCTION  SUB  CALL

Other Uses of the DECLARE Keyword
  DECLARE can also be used to declare references to procedures written
            in other programming languages, such as C
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF FN - a procedure statement that defines and names a function

Single-Line Syntax
  DEF FNname[(parameterlist)] = expression

Block Syntax
  DEF FNname[(parameterlist)]
     [statements]
  FNname = expression
     [statements]
  END DEF

  ■ The FUNCTION...END FUNCTION statement offers a more straight-forward
    way to define and name a new function. If you must use DEF FN, see
    Details for the meaning of the various arguments.

See Also  FUNCTION STATIC
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEF SEG - a memory statement that sets the current segment address
          for a subsequent PEEK function or BLOAD, BSAVE, CALL ABSOLUTE,
          or POKE statement

Syntax
  DEF SEG [=address]
    ■ If all arguments are omitted, the BASIC data segment is used.
    ■ address, a numeric expression has an unsigned integer value between
      0 and 65,535, is the beginning of the segment to be used by the
      other statement or function.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DEFtype - BASIC declarations that 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]...

    ■ letterrange has the form
        letter1[-letter2]
      where letter1 and letter2 are any of the upper or lowercase letters
      of the alphabet. Variable and function names beginning with the letters
      in letterrange have the type specified by the last three letters of
      the keyword (INT, SNG, DBL, LNG, or STR).
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DIM - a declaration statement that names one or more variables and
      allocates storage space for them
Syntax
  DIM [SHARED] variable[(subscripts)] [AS type]
               [,variable[(subscripts)] [AS type]...
    ■ variable is a BASIC variable name
    ■ Use the SHARED keyword if you want all procedures in this module to
      be able to use this variable
    ■ Use the optional (subscripts) to declare the size of arrays (see
      Details)
    ■ AS type is a Detail

See Also  ERASE  REDIM  OPTION BASE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WHILE...WEND - a control flow statement that executes a series of
               statements in a loop, as long as a given condition is true
Syntax
  WHILE condition
    [statements]
  WEND
    ■ condition is an expression that will return non-zero (true) or zero
      (false)
    ■ statements are one or more BASIC statements to be executed as long as
      condition is true

See also  DO...LOOP - to see a more flexible way to build a loop
          FOR...NEXT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DO...LOOP - a control flow statement that repeats a block of statements
            while a condition is true or until a condition becomes true

Syntax 1
  DO [{WHILE | UNTIL} booleanexpression]
    [statementblock]
  LOOP

Syntax 2
  DO
    [statementblock]
  LOOP [{WHILE | UNTIL} booleanexpression]

  ■ booleanexpression is an expression that will return non-zero (true)
    or zero (false).
  ■ statementblock is any number of statements on one or more lines which
    are to be executed as long as booleanexpression is true.

See Also  WHILE...WEND  FOR...NEXT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
DRAW - a graphics statement that interprets a string expression and
       draws an object.
Syntax
  DRAW stringexpression
    ■ stringexpression is a one or more drawing commands.
                             Drawing Commands
───Used to Draw a Line or Move the Current Graphics Position (CGP) or Both───
B   Optional prefix - move, no line   │ N   Optional prefix - line, no move
Un  Up             Dn  Down           │ Ln  Left             Rn  Right
En  Up and right   Fn  Down and right │ Gn  Down and left    Hn  Up and left
Mx,y  Move to screen point x,y (if x has a + or - in front, move is relative)
─────────────────────────────────Used to Color────────────────────────────────
Cn  Change drawing (foreground) color │ Pp,b  Fill enclosed shape that has
    (SCREEN mode determines 'n')      │       border color b with color p
────────────────────────────Used to Scale and Rotate──────────────────────────
Sn  Increases or decreases length of  │ An   Rotate (n * 90) degrees,
    moves (n=4 is default)            │      where n = 0, 1, 2, or 3
                                      │ TAn  Rotate (0 >= n <= 360) degrees
──────────────────────────Used to Execute Substrings──────────────────────────
     X + VARPTR$(string-expression)      Executes another command string

See Also  SCREEN  PALETTE  VARPTR$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
END - a BASIC declaration that ends a BASIC program, procedure,
      or block

Syntax
  END [{DEF | FUNCTION | IF | SELECT | SUB | TYPE}]

See Also  DEF FN  FUNCTION  IF...THEN...ELSE
          SELECT CASE  SUB  TYPE  STOP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON$ - a function that interfaces with DOS to retrieve an
           environment string from the DOS environment-string table

Syntax
  ENVIRON$ (environmentstring)
  ENVIRON$ (n)
    ■ environmentstring, a string constant or variable, is the name of
      the environment string whose current value is to be returned
    ■ n, which is a numeric expression, indicates that the nth string from
      the environment string table should be returned

See Also  ENVIRON Statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ENVIRON - a statement that interfaces with DOS to modify a parameter
          in the DOS environment-string table

Syntax
  ENVIRON stringexpression
    ■ stringexpression must have the form
        parameterid=text
      or
        parameterid text

See Also  ENVIRON$  SHELL
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EOF - a file I/O function that tests for the end-of-file condition

Syntax
  EOF(filenumber)
    ■ filenumber is the number of an open file

See Also  LOF  LOC  OPEN
EQV Operator

Syntax
  result = numeric-expression1 EQV numeric-expression2

Use the logical-equivalence operator to compare corresponding bits in
numeric-expression1 and numeric-expression2, and then set the corresponding
bit in the result according to the following table:

──────────────────────────────────────────────────────────────────
Bit in First Expression   Bit in Second Expression   Bit in Result
──────────────────────────────────────────────────────────────────
       1                         1                          1
       1                         0                          0
       0                         1                          0
       0                         0                          1
──────────────────────────────────────────────────────────────────
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERASE - a memory management statement that reinitializes the elements
        of static arrays or deallocates dynamic arrays

Syntax
  ERASE arrayname [,arrayname...]
    ■ arrayname is the name of a previously declared array. It is important
      to know whether this array is static or dynamic.

See Also  $STATIC and $DYNAMIC Metacommands  DIM  REDIM  CLEAR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERDEV and ERDEV$ - error-trapping functions that provide
                   device-specific status information after an error
Syntax
  ERDEV
  ERDEV$

  ■ ERDEV is an integer function that returns an error code from the
    last device to return an error
  ■ ERDEV$ is a string function that returns the name of the device
    returning the error
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERL and ERR - error-trapping functions that return program-specific
              status information after an error
Syntax
  ERR
  ERL

  ■ ERR is an integer function that returns an error code for the last
    error that occurred
  ■ ERL is an integer function that returns the line number where the
    error occurred, or the last line number before the line where the
    error occurred. ERL returns no line label information.

See Also  ON ERROR  RESUME  ERROR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
ERROR - an error-trapping statement that simulates the occurrence
        of a BASIC error or allows the user to define error codes

Syntax
  ERROR integerexpression
    ■ integerexpression, which has a value between 1 and 255, is
      the error code

See Also  ON ERROR  ERR  ERL  RESUME
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXIT - a control flow statement that exits a DEF FN function, DO...LOOP,
       FOR...NEXT loop, FUNCTION, or SUB

Syntax
  EXIT {DEF | DO | FOR | FUNCTION | SUB}

See Also  DEF FN  DO...LOOP  FOR...NEXT
          FUNCTION  SUB
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
EXP - a math function that calculates the exponential function
      (e raised to the power of a numeric expression).

Syntax
  EXP(numeric-expression)
    ■ numeric-expression, which must have a value less than or equal to
      88.02969, is the power to which e, the base of natural logarithms,
      is to be raised.

See Also  LOG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIELD - a file I/O statement that allocates space for variables in a
        random-access file buffer

Syntax
  FIELD [#]filenumber, fieldwidth AS stringvariable
                     [,fieldwidth AS stringvariable] ...
    ■ filenumber is the number of an open file
    ■ fieldwidth is the number of characters in the field
    ■ stringvariable is the location in the program where the field data
      is read to or written from

See Also  RSET  LSET  GET (File I/O)  PUT (File I/O)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILEATTR - a file I/O function that returns information about an
           open file
Syntax
  FILEATTR(filenumber,attribute)
    ■ filenumber is the number of an open file
    ■ attribute, a numeric expression that with a value of 1 or 2, indicates
      the type of information to return about the file (see Details).

See Also  OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FILES - a statement that interfaces with DOS to print the names of
        files residing on the specified disk

Syntax
  FILES [filespec]
    ■ If all arguments are omitted, all files in the current directory
      are listed
    ■ filespec is a string variable or constant that includes either a
      filename or pathname, and an optional device name

See Also  CHDIR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FIX - a math function that returns the truncated integer part of a
      numeric expression

Syntax
  FIX(numeric-expression)

See Also  INT  CINT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FOR...NEXT - a control flow statement that repeats a block of
             statements a specified number of times
Syntax
  FOR counter = start TO end [STEP increment]
    [statements]
  NEXT [counter [,counter...]]
    ■ counter is a numeric variable used as the loop counter
    ■ start is the initial value and end is the final value of the counter
    ■ increment is the amount the counter is incremented each time
      through the loop

See Also  DO...LOOP  WHILE...WEND
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FRE - a memory management function that returns the amount of
      available memory

Syntax
  FRE(stringexpression)
  FRE(numeric-expression)
    ■ stringexpression, which can have any value, indicates to the
      function that you want free string memory compacted into a single
      block and then the size, in bytes, of that block to be returned.
    ■ numeric-expression, which has the value of -1, -2, or any other
      numeric value, indicates what type of status information you want
      returned about string or stack space (see Details).
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FREEFILE - a file I/O function that returns the next free BASIC file
           number

Syntax
  FREEFILE

See Also  OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
FUNCTION...END FUNCTION - a non-executable statement that declares the
                          name, the parameters, and the code that form
                          the body of a FUNCTION procedure
Syntax
  FUNCTION name [(parameterlist)][STATIC]
      [statements]
    name = expression
      [statements]
  END FUNCTION
    ■ name, which follows the same rules as are used for naming BASIC
      variables, determines the data type the function returns
    ■ (parameterlist) is one or more variables, separated by commas,
      that will be passed to the function when it is called
    ■ expression is the return value of the function
    ■ Use of the keyword STATIC is a Detail

See Also  DECLARE  STATIC statement  DEF FN  SUB
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GET - a file I/O statement that reads from a disk file into a
      random-access buffer or variable

Syntax
  GET [#]filenumber[,[recordnumber][,variable]]
    ■ filenumber is the number of an open file
    ■ recordnumber and variable are Details

See Also  OPEN  PUT (File I/O)

Other Uses of the GET Keyword
GET (Graphics) - to copy a rectangular area of the screen by translating
                  the image to numeric data and storing that data in an array
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PUT - a file I/O statement that writes from a variable or a random-access
      buffer to a file
Syntax
  PUT [#]filenumber[,[recordnumber][,variable]]
  PUT [#]filenumber[,{recordnumber|recordnumber,variable|,variable}]
    ■ filenumber is the number of an open file
    ■ recordnumber is the file position to write to (a record number for
      random-access files, a byte number for binary files)
    ■ variable contains the information to be written

See Also  OPEN  GET (File I/O)

Other Uses of the PUT Keyword
  PUT (Graphics) statement - to put the contents of a graphics image file
                               on the screen
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOSUB...RETURN - a control flow statement that branches to, and
                 returns from, a subroutine
Syntax
  GOSUB {linelabel1 | linenumber1}
  [statements]
  RETURN [linelabel2 | linenumber2]

  ■ linelabel1 or linenumber1 is the label of the first line of the
    subroutine
  ■ The optional linelabel2 or linenumber2, used on the RETURN statement
    that ends the subroutine, is a Detail

See Also  RETURN  SUB
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
GOTO - a control flow statement that branches unconditionally to the
       specified line

Syntax
  GOTO {linelabel | linenumber}

  ■ linelabel or linenumber is the label of the line to execute next.
    This line must be in the same procedure or subroutine as the GOTO
    statement

See Also  EXIT - which provides an alternative way to branch out of
          a control structure.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
HEX$ - a string function that returns a string that represents the
       hexadecimal value of the decimal argument expression

Syntax
  HEX$(expression)
    ■ expression is a numeric expression that has a decimal value

See Also  OCT$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IF...THEN...ELSE - a control flow statement that allows conditional
                   execution or branching, based on the evaluation of
                   an expression that must be either true or false

Block IF...THEN...ELSE Syntax
  IF booleanexpression1 THEN
     [statementblock-1]
  [ELSEIF booleanexpression2 THEN
     [statementblock-2]
  . . .
  [ELSE
     [statementblock-n]]
  END IF
    ■ booleanexpression is an expression that must return non-zero (true)
      or zero (false)
    ■ statementblock consists of any number of statements on one or more
      lines.

Single-line IF...THEN...ELSE Syntax
  IF booleanexpression THEN thenpart [ELSE elsepart]
    ■ booleanexpression is an expression that must return non-zero (true)
      or zero (false)
    ■ thenpart consists of the statements or branches performed when
      booleanexpression is true (see Details)
    ■ elsepart consists of the statements or branches performed when
      booleanexpression is false

See Also  SELECT CASE  ON...GOTO  ON...GOSUB
IMP Logical Operator

Syntax
  result = numeric-expression1 IMP numeric-expression2

The logical-implication operator, IMP, compares corresponding bits in
numeric-expression1 and numeric-expression2, and then sets the
corresponding bit in the result according to the following table:

──────────────────────────────────────────────────────────────────
Bit in First Expression   Bit in Second Expression   Bit in Result
──────────────────────────────────────────────────────────────────
       1                         1                          1
       1                         0                          0
       0                         1                          1
       0                         0                          1
──────────────────────────────────────────────────────────────────
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INKEY$ - a device I/O function that reads a character from the
         keyboard

Syntax
  INKEY$

See also  ASCII Character Codes, Keyboard Scan Codes
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INP - a device I/O function that returns the byte read from an
      I/O port

Syntax
  INP(port)
    ■ port, a numeric-expression which has an integer value between
      0 and 65,535, identifies the hardware I/O port to read

See Also  OUT  WAIT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT - a device I/O statement that reads input from the keyboard
        during program execution and stores it into a list of variables

Syntax
  INPUT[;]["promptstring"{;|,}]variablelist
    ■ variablelist is one or more variables separated by commas
    ■ promptstring, if used, is displayed on the screen to tell the user
      of the program what to enter at the keyboard
    ■ the characters ";" and "," are Details

See Also  INKEY$
Other Uses of the INPUT Keyword
  LINE INPUT - to read an entire line of input from the keyboard and store
               it in one string variable
  INPUT # - to retrieve data items (or "fields") from a sequential file
            record and store them into a list of variables
  LINE INPUT # - to retrieve an entire record from a sequential file and
                 store it into one string variable
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INPUT$ - a file I/O function that returns a string of characters
         read from the specified file

Syntax
  INPUT$(n[,[#]filenumber])
    ■ n, a numeric expression, is the number of characters to read from
      the file
    ■ If the optional filenumber argument is not used, characters are read
      from the DOS standard input device (see Details)
    ■ If used, filenumber must be the number of an open file

See Also  OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INSTR - a string processing function that returns the character
        position of the first occurrence of a string in another string

Syntax
  INSTR([start,]stringexpression1,stringexpression2)
    ■ stringexpression1 is the string to be searched
    ■ stringexpression2 is the string to look for
    ■ If the optional start argument is used to begin the search beyond the
      first character of stringexpression1, it must be a numeric-expression
      with an integer value between 1 and 32,767.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
INT - a math function that returns the largest integer less than
      or equal to a numeric-expression

Syntax
  INT(numeric-expression)

See Also  CINT  FIX
Specifies the type (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a
user-defined type) for a variable in a declarative statement or
parameter list.
INTEGER - specifies that a variable is a 16-bit signed integer.
LONG    - specifies that a variable is a 32-bit signed integer.
SINGLE  - specifies that a variable is single-precision floating-point.
DOUBLE  - specifies that a variable is double-precision floating-point.
STRING  - specifies that a variable is a string, in a COMMON, DIM,
              REDIM, SHARED or STATIC statement. If is STRING is followed
              by * n, the string has a fixed length of n bytes. If no
              specification follows, the string is variable-length.

See Also  AS  COMMON  DECLARE  DEF FN
          DIM  FUNCTION  SHARED
          STATIC  SUB  TYPE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL$ - a file I/O function that receives a control data string
         from a device driver

Syntax
  IOCTL$([#]filenumber)
    ■ filenumber is a the number of an open device

    Refer to the device driver documentation to find out what status
    information the device driver is capable of sending.

See Also  IOCTL
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
IOCTL - a file I/O statement that transmits a control data string to
        a device driver

Syntax
  IOCTL [#]filenumber, string
    ■ filenumber is the number of an open device
    ■ string, a string-expression, is the command sent to the device.
      Refer to the device driver documentation to find out what the valid
      IOCTL command strings are.

See Also  IOCTL$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KEY - a device I/O statement that assigns soft-key string values to
      function keys and then can be used to display the soft-key values
      in various ways
Syntax                     Use
  KEY LIST                 Displays soft-key string values
  KEY {ON|OFF}             Turns on and off the soft-key display line at the
                           bottom of the screen
  KEY n,stringexpression   Assigns soft-key string values

    ■ n is the number of a specific key, chosen from the values below:
      1-10   Function keys F1-F10            │ 14     DOWN
        11   UP                              │ 15-25  User-defined keys
        12   LEFT                            │ 30-31  Function keys F11-F12
        13   RIGHT                           │        on 101-key keyboards

    ■ stringexpression, for all values of n except 15 through 25, is the
      is the string that is input by the program when the key is pressed.
      For n = 15 through 25, stringexpression has the syntax
        CHR$(keyboardflag) + CHR$(scancode)

See Also  ON KEY(n)  Keyboard Scan Code Table
Other Uses of the KEY Keyword
  KEY(n) - to trap a full range of keypress events
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
KILL - a statement that uses DOS to delete a disk file

Syntax
  KILL filespec
    ■ filespec is a string expression that identifies the file to delete.
      The filespec may include a path specification.

See Also  FILES  RMDIR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LBOUND - a memory function that returns the lower bound (smallest
         available subscript) for the indicated dimension of an array

Syntax
  LBOUND(array[,dimension])
    ■ array identifies the array
    ■ dimension, a numeric-expression with an integer value, indicates
      the dimension of the array for which you want to see the smallest
      available subscript. Use 1 for the first dimension, 2 for the second
      dimension, etc. This is an optional argument for one-dimensional
      arrays.

See Also  UBOUND
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LCASE$ - a string processing function that returns a string expression
         with all letters in lower-case

Syntax
  LCASE$(stringexpression)
    ■ stringexpression may be a string constant, string variable, or
      string expression. It may refer to a fixed- or variable-length
      string.

See Also  UCASE$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEFT$ - a string processing function that returns a string consisting
        of the leftmost n characters of a string

Syntax
  LEFT$(stringexpression,n)
    ■ stringexpression is a string constant, string variable, or string
      expression
    ■ n, a numeric expression, must have a value between 0 and 32,767.
      If n is zero, the null string (a zero-length string) is returned.

See Also  MID$ Function - to see how to extract n characters from the
                            middle of a screen
          RIGHT$ - to see how to extract the n right-most characters
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LEN - a string processing function that returns the number of
      characters in a string or the number of bytes required by a variable

Syntax
  LEN(stringexpression)
  or
  LEN(variable)
    ■ stringexpression is a string constant or string expression
    ■ variable identifies the object for which you want the number of
      required bytes
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LET - the expression evaluation statement that assigns the value
      of an expression to a variable

Syntax
  [LET] variable=expression

See Also  LSET - to see how to assign record variables of different
                     user-defined types
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LINE - a graphics statement that draws a line or box on the screen

Syntax
  LINE [[STEP] (x1,y1)]-[STEP] (x2,y2) [,[color][,[B[F]][,style]]]
    ■ (x2,y2) are the screen coordinates of the end of the line
    ■ (x1,y1), if used, is the start of the line
    ■ STEP, if used, enables you to specify relative screen coordinates
    ■ color, B, BF, and style are Details

See Also  SCREEN statement  CIRCLE  PSET
  Tip: SCREEN is especially important because it determines the range of
       numbers you can use to specify (x2,y2).

Other Uses of the LINE Keyword
  LINE INPUT - to read an entire line of input from the keyboard and store
               it in one string variable
  LINE INPUT # - to retrieve an entire record from a sequential file and
                 store it into one string variable
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOC - a file I/O function that returns the current position within
      the file

Syntax
  LOC(filenumber)
    ■ filenumber is the number of an open file or device
    ■ See Details for the differences in the meaning of the value returned
      by the LOC function for random-access files, sequential files, binary
      files, and communications devices.

See Also  LOF  EOF  OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCATE - a device I/O statement that moves the cursor to the
         specified position

Syntax
  LOCATE [row][,[column][,[cursor][,[start,stop]]]]
    ■ You may omit any argument. See Details about how QuickBASIC assigns
      default values to omitted arguments
    ■ row and column to move the cursor
    ■ cursor, start, and stop define the visibility and shape of the cursor

See Also  CSRLIN  POS
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOCK...UNLOCK - file I/O statements that control access by other
                processes to all or part of an opened file

Tip: LOCK and UNLOCK are only useful in network environments where
     several processes may need access to the same file, and only
     function if you are using DOS version 3.1 or later.

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

    ■ filenumber is the number of an open file
    ■ record, start, and end indicate the range of records or bytes to
      be locked
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOF - a file I/O function that returns the length of the named file
      in bytes

Syntax
  LOF(filenumber)
    ■ filenumber is the number of an open file

See Also  LOC  EOF OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LOG - a math function that returns the natural logarithm of a
      numeric expression

Syntax
  LOG(numeric-expression)
    ■ numeric-expression, which must have a value greater than zero, is
      the number for which you want the natural logarithm

See Also  EXP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPOS - a device I/O function that returns the current position of
       the line printer's print head within the printer buffer

Syntax
  LPOS(n)
    ■ n, a numeric expression that has an integer value between 0 and 3,
      is the index of the printer port being tested. 1 means LPT1:, 2 means
      LPT2:, etc.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LPRINT, LPRINT USING - file I/O statements that print data on the
                       printer LPT1:
Syntax 1
  LPRINT [expressionlist][{;|,}]
Syntax 2
  LPRINT USING formatstring; expressionlist[{;|,}]

    ■ If all arguments are omitted from the LPRINT statement, the printer
      prints a blank line
    ■ expressionlist is one or more expressions, separated by semicolons
    ■ The optional characters ";" or "," are Details
    ■ formatstring in the LPRINT USING statement is a string literal or
      variable containing literal characters to print and special
      formatting characters.

See Also  PRINT  PRINT USING  WIDTH
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LSET - a file I/O statement that moves data from memory to a
       random-access file buffer (in preparation for a PUT statement),
       left-justifies the value of a string in a string variable, or
       copies one record variable to another.

Tip: LSET is a way of copying one record to another without regard to
     datatype equivalence.

Syntax
LSET {stringvariable=stringexpression | stringexpression1=stringexpression2}
  ■ stringvariable is any string variable
  ■ stringexpression is the value assigned to stringvariable and
    left-justified

See Also  PUT (File I/O)  MKD$, MKI$, MKL$, MKS$  RSET
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RSET - a string processing statement that 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
    ■ stringvariable may be a random-access file field defined in a FIELD
      statement, or any other string variable
    ■ stringexpression is the value assigned to stringvariable

See also  PUT (File I/O)  MKD$, MKI$, MKL$, MKS$  LSET
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
LTRIM$ - a function that returns a copy of a string with leading
         spaces removed

Syntax
  LTRIM$(stringexpression)

See Also  RTRIM$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MID$ - a string processing statement that replaces a portion of a
       string variable with another string

Syntax
  MID$(stringvariable,start[,length])=stringexpression
    ■ stringvariable is the name of the string you want to change
    ■ start, a numeric expression, is the character position at which the
      change starts
    ■ length, an optional numeric expression, is the number of characters
      to use from stringexpression
    ■ stringexpression supplies the new characters

Other Uses of the MID$ Statement
  MID$ function - to extract a given number of characters from a string
See Also  LEFT$  RIGHT$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKDIR - a statement that uses DOS to create a new directory

Syntax
  MKDIR pathspec
    ■ pathspec is a string expression that identifies the directory to be
      created

See Also  RMDIR  CHDIR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKSMBF$ and MKDMBF$ - conversion functions that convert an IEEE-format
                      number to a string containing a Microsoft Binary
                      format number.
Syntax
  MKSMBF$(single-precision-expression)
  MKDMBF$(double-precision-expression)

See Also  CVDMBF, CVSMBF  CVD, CVI, CVL, CVS  MKD$, MKI$, MKL$, MKS$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
MKD$, MKI$, MKL$, MKS$ - functions that convert numeric values to
                         string values
Syntax
  MKI$(integerexpression)
  MKS$(single-precision-expression)
  MKL$(long-integer-expression)
  MKD$(double-precision-expression)

See Also  CVD, CVI, CVL, CVS  GET (File I/O)
MOD Arithmetic Operator

Syntax
  numeric-expression1 MOD numeric-expression2

The modulus or "remainder" operator. Divides one number by another
(rounding real values to integers, if required) and returns the
remainder. For example, 19 MOD 6.7 equals five.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
NAME - a statement that uses DOS to change the name of a disk file
       or directory
Syntax
  NAME oldfilename AS newfilename
    ■ oldfilename, a string expression, is the name of an existing file.
    ■ newfilename, a string expression, must be a filename that does not
      exist

Tip:  oldfilename and/or newfilename may contain a pathname. If the path
      in oldfilename is different than the path in newfilename, the NAME
      statement moves the file and renames it. Both files must be on the
      same drive.
NEXT Keyword - Different Uses

Syntax 1
  NEXT [loopvar]
    ■ The terminating line of a FOR...NEXT structure. Should include the
      name of the loop control variable for readability, but is not
      required to.
Syntax 2
  RESUME NEXT
    ■ Returns control from an error-handling routine to the statement
      following the one that caused the error.

See Also  FOR...NEXT  RESUME
NOT Operator

Syntax
  result = NOT numeric-expression

The logical-complement operator evaluates each bit in numeric-expression,
then sets the corresponding bit in the result according to the following
table:
              ─────────────────────────────────────────
              Bit in Expression         Bit in Result
              ─────────────────────────────────────────
                       1                       0
                       0                       1
              ─────────────────────────────────────────
This inverts the bit values of any variable. If an integer variable has
the value 0 (false), the variable becomes -1 (true), and vice-versa.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OCT$ - a string function that returns a string representing the
       octal value of the numeric argument

Syntax
  OCT$(numeric-expression)
    ■ numeric-expression can be of any type

See Also  HEX$
OFF Keyword - Different Uses

  ■ The OFF keyword is used in various statements to disable trapping of
    the following events:
      COM(n) OFF   - events on communications port n
      KEY(n) OFF   - a keypress event on key n
      PEN OFF      - lightpen events
      PLAY OFF     - background music buffer events
      STRIG(n) OFF - events on joystick trigger n
      TIMER OFF    - timer events
      UEVENT OFF   - user-defined events

  ■ The OFF keyword is also used to turn off the display of soft-key
    assignments on the bottom line of the screen:
      KEY OFF
ON Keyword - Different Uses

The ON keyword is used in various statements to trap events:
Specifies a trap          Type of event                    Enables the trap
ON COM(n)         events on communications port n          COM(n) ON
ON KEY(n)         a keystroke on key n                     KEY(n) ON
ON PEN            lightpen events                          PEN ON
ON PLAY(n)        less than n notes in music buffer        PLAY ON
ON STRIG(n)       events on joystick trigger n             STRIG(n) ON
ON TIMER(n)       timer events                             TIMER ON
ON UEVENT         user-defined events                      UEVENT ON

Other uses of the ON keyword are:
ON ERROR - to enable error handling and specify the error-handling routine
ON...GOSUB - to branch to one of a list of subroutines
ON...GOTO  - to branch to one of a list of line labels
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPEN - a file I/O statement that enables I/O to a file or device
Syntax
  OPEN file [FOR mode] [ACCESS access] [lock] AS [#]filenum [LEN=reclen]
    ■ file is a string expression that specifies an optional device name,
      followed by a file name or path name
    ■ mode is one of the following keywords:

RANDOM   Read or write from a random- │ INPUT   Read only from sequential file
         access file (the default)    │ OUTPUT  Write to a sequential file
BINARY   Read or write from a binary  │ APPEND  Write to the end of a
         file                         │         sequential file

    ■ access and lock are Details used only in a networking environment
    ■ filenum is an integer expression whose value is between 1 and 255
    ■ reclen defaults to 128 for random-access files, to 512 for sequential
      files, and is not needed at all for binary files
See Also  FREEFILE
Other Uses of the OPEN Keyword
  OPEN mode,[#]filenum,file[,reclen] - an alternate syntax (see Details)
  OPEN COM - to open a communications channel
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OPTION BASE - a BASIC declaration that declares the default
              lower bound for array subscripts

Syntax
  OPTION BASE n
    ■ n, a numeric expression, must have a value of 0 or 1.

See Also  LBOUND  DIM
OR Operator

Syntax
  result = numeric-expression1 OR numeric-expression2

The logical "inclusive or" operator compares corresponding bits in
numeric-expression1 and numeric-expression2, then sets the corresponding
bit in the result according to the following table:

──────────────────────────────────────────────────────────────────
Bit in First Expression   Bit in Second Expression   Bit in Result
──────────────────────────────────────────────────────────────────
        1                        1                        1
        1                        0                        1
        0                        1                        1
        0                        0                        0
──────────────────────────────────────────────────────────────────
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
OUT - a device I/O statement that sends a byte to a machine I/O port

Syntax
  OUT port, data
    ■ port, a numeric-expression which has an integer value between
      0 and 65,535, identifies the destination hardware I/O port
    ■ data, a numeric expression that has an integer value between
      0 and 255, is the data to be sent out the port

See Also  INP  WAIT
OUTPUT

In the FOR mode clause of an OPEN statement, if mode is OUTPUT, the file
is opened for sequential writing.

See Also  OPEN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PAINT - a graphics statement that fills an area with the color or
        pattern specified

Syntax
  PAINT [STEP] (x,y)[,[paint] [,[bordercolor] [,background]]]
    ■ (x,y) are the screen coordinates that indicate the area to be filled.
    ■ Use the optional STEP keyword if (x,y) are coordinate values which
      are relative to the most recently drawn point
    ■ paint is a numeric expression that specifies the color to paint with,
      or a string expression that indicates the pattern (or "tiling") to
      paint with
    ■ bordercolor and background are Details

See Also  DRAW  CIRCLE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PALETTE, PALETTE USING - graphics statements that change one or
                         more of the colors in the palette
Tip:  The PALETTE statement works only on systems equipped with EGA, VGA,
      or MCGA adapters.

Syntax
  PALETTE [attribute,color]
  PALETTE USING array-name [(array-index)]
    ■ attribute is the palette attribute to be changed
    ■ color is the display color assigned to the attribute
    ■ array-name and array-index are used to change more that one palette
      assignment with a single statement (see Details)

See Also  SCREEN  COLOR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PCOPY - a graphics statement that copies one screen page to another

Syntax
  PCOPY sourcepage, destinationpage
    ■ sourcepage, a numeric expression that has an integer value between
      0 and n, identifies the segment of video memory that contains the
      source. The value of n is determined by the current size of video
      memory and the current screen mode.
    ■ destinationpage, also a numeric expression that has an integer value
      between 0 and n, identifies the video memory location of the copy

See Also  SCREEN Statement - to see how the current SCREEN mode
                               determines the number of pages available
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEEK - a memory function that returns the byte stored at a specified
       memory location

Syntax
  PEEK(address)
    ■ address, a numeric expression with a value between 0 and 65,535, is
      an offset into the memory segment specified by the most recently
      executed DEF SEG statement

See Also  DEF SEG  POKE  VARPTR$  VARPTR  VARSEG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PEN - an event-trapping statement that enables, disables, or suspends
      lightpen-event trapping
Syntax
  PEN ON
  PEN OFF
  PEN STOP

See Also  ON PEN
Other Uses of the PEN Keyword
PEN function - to read the lightpen coordinates
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PLAY - a device I/O statement that plays music

Syntax
  PLAY commandstring
    ■ commandstring is a stringexpression that contains music commands:
──────────────────────────Set Octaves and Play Tones──────────────────────────
 On  Sets current octave (n = 0-6)    │  < or >  Up or down one octave
 Nn  Plays note n (n = 0-84, 0 is a   │  A-G  Plays A, B, ..., G in current
     rest)                            │      octave (+ = sharp, - = flat)
──────────────────────────Set Tone Duration and Tempo─────────────────────────
 Ln  Sets length of a note (L1 is     │  MS  Each note plays 3/4 of length
     whole note, L4 is quarter note,  │  MN  Each note plays 7/8 of length
     etc.)  n = 1-64                  │  ML  Each note plays full length
 Tn  Sets number of quarter notes per │  Pn  Pause for the duration of
     minute (n = 32-255, 120 default  │      n quarternotes (n = 1-64)
────────────────────────────────Set Operation─────────────────────────────────
 MF  Plays music in foreground        │  MB  Plays music in background
───────────────────────────────Execute Substrings─────────────────────────────
       X + VARPTR$(string-expression)     Executes another command string

See Also  SOUND  BEEP  ON PLAY(n)
Other Uses of the PLAY Keyword
  PLAY ON, PLAY OFF, and PLAY STOP - to enable, disable, or suspend play
                                       event trapping
  PLAY function - to return the number of notes in the background music
                    queue
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PMAP - a graphics function that maps view-coordinate expressions to
       physical locations or maps physical expressions to a view-coordinate
       location

Syntax
  PMAP (expression, function)
    ■ expression indicates the coordinate to be mapped
    ■ function, a numeric expression which has an integer value
      between 0 and 3, specifies one of four different mapping functions
      to be done (see Details).

See Also  WINDOW  VIEW  POINT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POINT - a graphics function that reads the color number of a pixel from
        the screen or returns the pixel's coordinates
Syntax
  POINT (x,y)
  POINT (number)
    ■ (x,y) are the pixel coordinates for which you want the color number
    ■ number, a numeric expression that has an integer value between 0 and 3,
      indicates one of four possible ways you want the current location of
      the graphics cursor to be reported (see Details).

See Also  SCREEN - to see the range of coordinates that are available
                     in the various screen modes and the meaning of color
                     numbers in those various modes
          PMAP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POKE - a memory statement that writes a byte into a memory location

Syntax
  POKE address,byte
    ■ address, a numeric expression that returns a value between
      0 and 65,535, is an offset into the memory segment specified by
      the most recently executed DEF SEG statement
    ■ byte, a numeric expression that returns an integer value between
      0 and 255, is the data to be written into the memory location

See Also  DEF SEG  PEEK  VARPTR$  VARPTR  VARSEG
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
POS - a device I/O function that returns the current horizontal
      position of the cursor

Syntax
  POS(0)

See Also  CSRLIN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRESET - a graphics statement that draws a specified point on the
         screen
Syntax
  PRESET [STEP](x,y)[,color]
    ■ (x,y) specify the screen coordinates where you want the point drawn
    ■ Use the optional STEP keyword if the (x,y) values are relative to
      the current location of the graphics cursor
    ■ If color is omitted, the current background color is used

See Also  PSET  SCREEN statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PRINT - a device I/O statement that outputs data on the screen

Syntax
  PRINT [expressionlist][{,|;}]
    ■ If all arguments are 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.)
    ■ The optional characters "," and ";" are Details.

Other Uses of the PRINT Keyword
  PRINT USING - to output formatted text to the screen
  PRINT # - to output data to a sequential file
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
PSET - a graphics statement that draws a point on the screen

Syntax
  PSET [STEP](x,y) [,color]
    ■ (x,y) specify the screen coordinates where you want the point drawn
    ■ Use the optional STEP keyword if the (x,y) values are relative to
      the current location of the graphics cursor
    ■ If color is omitted, the current foreground color is used

See Also  PRESET  SCREEN statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RANDOMIZE - a math statement that initializes (reseeds) the
            random-number generator
Syntax
  RANDOMIZE [expression]
    ■ If the argument is omitted, the user will be prompted for a random
      number seed.
    ■ expression may be any type of expression

See Also  RND
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
READ - an I/O statement that reads values from a DATA statement
       and assigns the values to variables

Syntax
  READ variablelist
    ■ variablelist is made up of one or more variables, separated by
      commas, which are to receive the data. The variables may be string
      or numeric. See Details about data type conversion performed by
      QuickBASIC.

See also  DATA  RESTORE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REDIM - a BASIC declaration that changes the space allocated to an
        array that has been declared $DYNAMIC

Syntax
  REDIM [SHARED] variable(subscripts)[AS type]
                 [,variable(subscripts)[AS type]]...

    ■ variable is a BASIC variable name
    ■ Use the SHARED keyword if you want all procedures in this module to
      be able to use this variable
    ■ Use the (subscripts) to declare the size of arrays
      (see Details)
    ■ Use the optional AS type clause to declare a data type for the
      array (see Details)

See Also  DIM  ERASE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
REM - a BASIC declaration that allows explanatory remarks to be
      inserted in a program

Syntax
  REM remark
  ' remark

    ■ remark is any explanation you think will be useful to a reader of
      the program text, and which will fit on the rest of the program line

See Also  $STATIC and $DYNAMIC Metacommands  $INCLUDE Metacommand
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESET - a file I/O statement that closes all disk files

Syntax
  RESET

See Also  CLOSE
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESTORE - an I/O statement that allows DATA statements to be
          reread from a specified line

Syntax
  RESTORE [{linelabel | linenumber}]
    ■ If the argument is omitted, the next READ statement which executes
      will read the first item in the first DATA statement in the program
    ■ linelabel or linenumber identifies the DATA statement you want the
      next READ statement to use. The first item from that line will be
      read.

See Also  DATA  READ
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RESUME - an error-trapping statement that continues program execution
         after an error-trapping routine has been invoked

Syntax
  RESUME [0]
  RESUME NEXT
  RESUME {linelabel | linenumber}

  ■ If the argument is omitted, or is 0, program execution resumes with
    the statement that caused the error
  ■ NEXT resumes program execution with the statement immediately following
    the one that caused the error
  ■ linelabel or linenumber are Details

See Also  ON ERROR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RETURN - a control flow statement that returns control from a subroutine

Syntax
  RETURN [{linelabel | linenumber}]
    ■ If the argument is omitted, RETURN continues execution where an event
      occurred (for event handling) or at the statement following the GOSUB
      (for subroutine calls)
    ■ linelabel or linenumber, if used, must identify a line in the
      module-level code to execute next

See Also  GOSUB
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RIGHT$ - a string function that returns the rightmost n characters
         of a string

Syntax
  RIGHT$(stringexpression,n)
    ■ stringexpression is a string constant, string variable, or string
      expression
    ■ n, a numeric expression which must have a value between 0 and 32,767,
      specifies how many right-most characters the function should return.
      If n is zero, the null string (a zero-length string) is returned.

See Also  LEFT$  MID$ function
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RMDIR - a statement that interfaces with DOS to remove an existing
        directory

Syntax
  RMDIR pathspec
    ■ pathspec is a string expression that identifies the directory
      to be removed

See Also  MKDIR  CHDIR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RND - a math function that returns a single-precision random number
      between 0 and 1

Syntax
  RND[(n)]
    ■ If the argument is omitted, the RND function returns the next
      number in the random number sequence
    ■ n is a numeric expression that specifies a value less than zero,
      zero, or greater than zero. See Details on how the RND function
      interprets each of these types of values.

See also  RANDOMIZE - to see how to generate a different random number
                        sequence each time the program is run
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RTRIM$ - a string processing function that returns a string with
         trailing (right-hand) spaces removed

Syntax
  RTRIM$(stringexpression)

See Also  LTRIM$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
RUN - a control flow statement that restarts the program currently in
      memory, or executes a specified program

Syntax
  RUN [{linenumber | filespec}]
    ■ If the argument is omitted, execution begins at the first executable
      statement in the main module of the currently loaded program
    ■ linenumber explicitly identifies a line where execution of the main
      module begins
    ■ filespec, a string expression, specifies a file to load into memory
      and run

See Also  CHAIN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SADD - a memory function that returns the address of the specified
       string expression
Tip:  The SADD function is most often used in mixed-languages programming.

Syntax
  SADD(stringvariable)
    ■ stringvariable identifies the string for which you want the
      memory location

See Also  FRE  PEEK  POKE  VARPTR$  VARPTR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SCREEN - a graphics statement that sets the specifications for the
         display screen

Syntax
  SCREEN [mode] [,[colorswitch]][,[apage]][,[vpage]]
    ■ mode is an integer constant or expression that selects a screen mode
      for a particular combination of display and adapter:

        MDPA, CGA, EGA, or VGA (Text Only)
        CGA, EGA, VGA, or MCGA Low- and Medium-Resolution Graphics
        EGA and VGA Medium- and High-Resolution Graphics
        EGA and VGA Monochrome High-Resolution Graphics
        VGA and MCGA High-Resolution Graphics
        Hercules and Other Adapters
    ■ colorswitch, apage, and vpage are Details

See Also  COLOR  PALETTE  WIDTH
Other Uses of the SCREEN Keyword
  SCREEN function - to read a character's ASCII value or its color from
                    a specific screen location
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SEEK - a file I/O statement that sets the position in a file for
       the next read or write
Syntax
  SEEK [#]filenumber,position
    ■ filenumber is an integer used in an OPEN statement to open the file
    ■ position is a numeric expression indicating where the next read or
      write is to be done:
        - for files opened in RANDOM mode, position is a record number.
        - for files opened in BINARY, INPUT, OUTPUT, or APPEND modes,
          position is the number of a byte from the beginning of the file.

See Also  OPEN  GET(File I/O)  PUT(File I/O)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SELECT CASE - a control flow statement that 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

    ■ testexpression is any numeric or string expression.
    ■ expressionlist contains one or more expressions of the same type as
      testexpression. The IS keyword must precede any relational operators
      in an expression.
    ■ statementblock consists of any number of statements on one or more
      lines.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SETMEM - a memory management function that changes the amount of memory
         used by the far heap - the area where far objects and internal
         tables are stored

Syntax
  SETMEM(numeric-expression)
    ■ numeric-expression has a value that is less than zero, zero, or
      greater than zero. See Details about how the SETMEM function
      interprets each of these values.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SGN - a math function that indicates the sign of a numeric expression

Syntax
  SGN(numeric-expression)
    ■ If numeric-expression is positive, the SGN function returns +1.
    ■ If numeric-expression is zero, the SGN function returns 0.
    ■ If numeric-expression is negative, the SGN function returns -1.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHARED - a statement that 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]]...
    ■ variable identifies the module-level variable the procedure will use.
      It is either an array name followed by (), or a variable name.
    ■ The optional AS type clause is a Detail.

See Also  SHARED keyword in COMMON statement
          SHARED keyword in DIM statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SHELL - a statement that interfaces with DOS to exit the BASIC program,
        run a .COM, .EXE, or .BAT program, or a DOS command, and return
        to the program at the line following the SHELL statement

Syntax
  SHELL [commandstring]
    ■ If all arguments are omitted, DOS will give you a new COMMAND.COM
      shell and DOS commands can be entered at the DOS prompt
    ■ commandstring is a string expression that contains the name of a
      program to run and any program options
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SIN - a math function that returns the sine of an angle given in radians

Syntax
  SIN(numeric-expression)
    ■ numeric-expression, which may be of any type, is the angle, expressed
      in radians. See Details on how to convert degrees into radians.

See Also  COS  TAN  ATN
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SLEEP - a control flow statement that suspends execution of the
        calling program
Syntax
  SLEEP [seconds]
    ■ If the argument is omitted, the program is suspended until a key is
      pressed or an enabled event occurs
    ■ If the optional seconds argument is used, the program will stay
      suspended until the number of seconds elapses, a key is pressed,
      or an enabled event occurs, whichever happens first.

See Also  WAIT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SOUND - a device I/O statement that generates sound through the
        speaker
Syntax
  SOUND frequency,duration
    ■ frequency, a numeric expression that has an integer value between
      37 and 32,767, is the frequency of the sound in cycles/second,
      or hertz
    ■ duration, a numeric expression that has an unsigned integer value
      between 0 and 65,535, is the number of system clock ticks the
      sound lasts. There are 18.2 clock ticks per second.

See Also  PLAY
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPACE$ - string processing function that returns a string of spaces
         of length n
Syntax
  SPACE$(n)
    ■ n, a numeric expression that has an integer value between 0 and 32,767,
      is the number of spaces you want in the string

See Also  STRING$  SPC  TAB  PRINT USING
          RSET  LSET
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SPC - a device I/O function that skips n spaces in a PRINT or LPRINT
      statement

Syntax
  SPC(n)
    ■ n, a numeric expression that returns an integer value between
      0 and 32,767, is the number of spaces you want in print line

See Also  SPACE$  TAB
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SQR - a math function that returns the square root of numeric expression

Syntax
  SQR(numeric-expression)
    ■ numeric-expression must have a value greater than or equal to zero
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STATIC - BASIC declaration that makes simple variables or arrays local
         to a procedure (or a DEF FN function) and preserves the variable
         values between procedure calls

Syntax
  STATIC variablelist
    ■ variablelist has the following syntax:
        variable[()][AS type][,variable[()][AS type]...
      Use the "()" characters to identify an array. See Details for
      more information about the AS type clause.

See Also  SUB  FUNCTION  DEF FN
Use the STEP keyword to

  ■ indicate how much to increase or decrease the loop counter after
    each iteration of a FOR...NEXT loop.

  ■ in graphics statements, to indicate that the pixel coordinates that
    follow STEP are relative offsets from the last location of the
    graphics cursor on the screen, rather than absolute distances
    from the upper left corner of the screen.

See Also  FOR...NEXT  CIRCLE  LINE  PAINT
        PRESET  PSET
        GET (Graphics)  PUT (Graphics)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STICK - a device I/O function that returns the x and y coordinates
        of the two joysticks

Syntax
  STICK(n)
    ■ n, a numeric expression that has an unsigned integer value between
      0 and 3, tells the STICK function which one of four possible
      joystick coordinate values to return (see Details)
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STOP - a control flow statement that terminates the program

Syntax
  STOP

See Also  END
Other Uses of the STOP Keyword
  The STOP keyword is used in various statements to suspend trapping of
  various events in the following statements:
      Statement       Type of Event Trapping Suspended
      COM(n) STOP   - events on communications port n
      KEY(n) STOP   - a keypress event on key n
      PEN STOP      - lightpen events
      PLAY STOP     - background music buffer events
      STRIG(n) STOP - events on joystick trigger n
      TIMER STOP    - timer events
      UEVENT STOP   - user-defined events
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STR$ - a string function that returns a string representation of the
       value of a numeric expression

Syntax
  STR$(numeric-expression)

See Also  VAL
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRIG(n) - an event-trapping statement that enables, disables, or
           inhibits trapping of joystick activity
Syntax
  STRIG(n) ON
  STRIG(n) OFF
  STRIG(n) STOP

See Also  ON event statements
Other Uses of the STRIG Keyword
  STRIG function - to return the status of a specified joystick trigger
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
STRING$ - string processing function that 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)
    ■ m, a numeric expression, is the length of the string to return
    ■ n, a numeric expression that has an integer value between 0 and 255,
      is the ASCII character code of the character that fills the string
    ■ stringexpression identifies a string whose first character can
      be used to fill the string

See Also  ASCII Character Codes
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SUB...END SUB - a procedure statement that marks the beginning and
                end of a subprogram
Syntax
  SUB globalname[parameterlist][STATIC]
    [statements]
  [EXIT SUB]
    [statements]
  END SUB

    ■ globalname is a variable name up to 40 characters long, which does
      not appear in any other SUB or FUNCTION statement in the same program
    ■ parameterlist contains the names of the simple variables and arrays
      passed to the SUB when it is called (see Details for the syntax of
      the parameter list)
    ■ use the optional STATIC keyword to preserve local variable values
      between calls

See also  DECLARE  CALL  SHARED  STATIC Statement
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SWAP - an assignment statement that exchanges the values of two variables

Syntax
  SWAP variable1,variable2
    ■ variable1 and variable2 must be of exactly the same type
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
SYSTEM - a statement that closes all open files and returns
         control to the operating system

Syntax
  SYSTEM

See Also  END  STOP
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAB - a device I/O function that moves the print position when used
          in the PRINT or LPRINT statements

Syntax
  TAB(column)
    ■ column, a numeric expression that has an integer value between
      1 and (column-width of the display device - 1)

See also  SPC  SPACE$  PRINT  LPRINT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TAN - a math function that returns the tangent of an angle expressed
          in radians
Syntax
  TAN(numeric-expression)
    ■ numeric-expression, which may be of any type, is the angle, expressed
      in radians. See Details on how to convert degrees into radians.

See Also  ATN  SIN  COS
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIME$ - a statement that uses DOS to set the current time

Syntax
  TIME$=stringexpression
    ■ stringexpression must have one of the following forms:
        hh, hh:mm, or hh:mm:ss
      where hh is the hour on a 24-hour clock, mm is the minutes, and
      ss is the seconds

See Also  DATE$

Other Uses of the TIME$ Keyword
  TIME$ function - to get the current time from DOS
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TIMER - an event trapping statement that enables, disables, or inhibits
        timer event trapping
Syntax
  TIMER ON
  TIMER OFF
  TIMER STOP

See Also  ON TIMER(n)
Other Uses of the TIMER Keyword
  TIMER function - to return the number of seconds elapsed since midnight
The TO keyword is used to specify ranges in the following statements:

  ■ Specify a range in the CASE clause of a SELECT CASE statement.
  ■ Specify the range for the loop counter in a FOR...NEXT loop.
  ■ Specify a range of records to lock or unlock in a networked
    environment, in the LOCK...UNLOCK statement.
  ■ Separate the lower and upper bounds of an array specification
    in a DIM or REDIM statement.
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TRON and TROFF - debugging statements that trace the execution of
                 program statements
Syntax
  TRON
  TROFF
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
TYPE - a BASIC declaration that defines a data type containing one
       or more elements

Syntax
  TYPE usertype
    elementname AS typename
    [elementname AS typename]
    . . .

  END TYPE

    ■ usertype is a name that will identify the user-defined type. Use
      BASIC variable naming rules to coin this name.
    ■ elementname will identify this element of the user-defined type.
      Use BASIC variable naming rules.
    ■ typename is INTEGER, LONG, SINGLE, DOUBLE, STRING*n, or another
      user-defined type
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UBOUND - a memory function that returns the upper bound (largest
         available subscript) for the indicated dimension of an array

Syntax
  UBOUND(array[,dimension])
    ■ array identifies the array
    ■ dimension, an numeric-expression that has an integer value, indicates
      the dimension of the array for which you want to see the smallest
      available subscript. Use 1 for the first dimension, 2 for the second
      dimension, etc. This is an optional argument for one-dimensional
      arrays.

See Also  LBOUND
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UCASE$ - a string processing function that returns a string expression
         with all letters in uppercase

Syntax
  UCASE$(stringexpression)

See Also  LCASE$
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UEVENT - an event-trapping statement that enables, disables or suspends
         event trapping for a user-defined event

Syntax
  UEVENT ON
  UEVENT OFF
  UEVENT STOP

See Also  ON UEVENT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
UNLOCK - a file I/O statement that releases locks applied to parts
         of a file
  Tip: LOCK and UNLOCK are only useful in networked environments where
       several processes my need access to the same file. They only
       function if you are using DOS version 3.1 or later.

Syntax
  UNLOCK [#] filenumber [,{record| [start] TO end}]
    ■ filenumber is the number of an open file
    ■ record, start, and end indicate the range of records or bytes to
      be locked

See Also  LOCK
──────────────────Characters Used to Format a Numeric Expression──────────────
 #   Digit position                     │ -     Placed after digit positions,
 .   Decimal point position             │       prints trailing sign for
 ,   Placed left of the decimal point,  │       negative numbers only
     prints a comma every third digit   │ $$    Prints leading $
 +   Position of number's sign          │ **    Fills leading spaces with *
^^^^ Prints number in exponential format│ **$   Combines ** and $
───────────────────Characters Used to Format a String Expression──────────────
 &   Prints entire string               │     Prints first 'n' characters,
 !   Prints only the first character    │       where n is the number of
     of the string                      │       blanks between slashes + 2
─────────────────────────────Characters Used as Literals──────────────────────
 _   Prints the following formatting    │       Any character not in this
     character as a literal             │       table is printed as a literal
See Also  PRINT USING  PRINT
Other Uses of the USING Keyword
  PALETTE USING - to specify the colors used in a graphics display
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VAL - a string-processing function that returns the numeric value of
      a string of digits

Syntax
  VAL(stringexpression)

See Also  STR$  ASC
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VARPTR and VARSEG - memory functions that return the address of a
                    variable
Syntax
  VARPTR(variablename)
  VARSEG(variablename)
    ■ variablename is the name of any BASIC variable, including a record
      variable or record element

See Also  VARPTR$  DEF SEG  PEEK  POKE  SADD
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VARPTR$ - a memory function that returns a string representation of
          a variable's address for use in DRAW and PLAY statements

Syntax
  VARPTR$(variablename)

See Also  VARPTR
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
VIEW - a graphics statement that defines screen limits for graphics
       output
Syntax
  VIEW [[SCREEN] (x1,y1)-(x2,y2) [,[color][,border]]]
    ■ If all arguments are omitted, the entire screen is the viewport
    ■ (x1,y1) and (x2,y2) are numeric expressions that are the coordinates
      of diagonally opposite corners of the viewport
    ■ Use the optional SCREEN keyword to specify the coordinates are absolute
      to the screen, not relative to an already established viewport
    ■ color and border are Details

See Also  SCREEN statement

Other Uses of the VIEW Keyword
  VIEW PRINT statement - to set the boundaries of the text viewport on the
                           screen
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WAIT - a control flow statement that suspends program execution while
       monitoring the status of a machine input port

Syntax
  WAIT portnumber,and-expression[,xor-expression]
    ■ portnumber, a numeric expression that has an integer value between
      0 and 255, is the number of the machine input port
    ■ and-expression is an integer expression that is combined with the
      data at the port with an AND operation. Only if the result is
      non-zero will the WAIT statement pass control to the next
      statement in the program.
    ■ xor-expression is a Detail

See Also  INP  OUT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WIDTH - a file I/O statement that 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

    ■ See Details for the different ways the WIDTH statement arguments
      can be used

See Also  SCREEN statement  VIEW PRINT
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WINDOW - a graphics statement that defines the dimensions of the
         current viewport
Syntax
  WINDOW [[SCREEN] (x1,y1)-(x2,y2)]
    ■ If all arguments are omitted, the view coordinates will be the
      same as the screen coordinates
    ■ (x1,y1)-(x2,y2) are a set of single-precision numbers that specify
      the "view coordinate" values for the border coordinates of the screen.
    ■ The optional SCREEN keyword is a Detail

See Also  SCREEN statement  VIEW  WIDTH
  ◄QuickSCREEN►      Details      Example      Contents      Index
──────────────────────────────────────────────────────────────────────────────
WRITE # - a file I/O statement that writes data to a sequential file

Syntax
  WRITE #filenumber[,expressionlist]
    ■ filenumber is an integer used in an OPEN statement for the file.
      The file must be opened in OUTPUT or APPEND mode.
    ■ expressionlist is one or more string or numeric expressions,
      separated by commas.
    ■ If you omit expressionlist, a blank line is written to the file

See Also  OPEN  PRINT #

Other Uses of the WRITE Keyword
  WRITE statement - to send data to the screen
XOR Operator

Syntax
  result = numeric-expression1 XOR numeric-expression2

The logical "exclusive or" operator compares corresponding bits in
numeric-expression1 and numeric-expression2, then sets the corresponding
bit in the result according to the following table:

─────────────────────────────────────────────────────────────────
Bit in First Expression   Bit in Second Expression   Bit in Result
──────────────────────────────────────────────────────────────────
       1                         1                          0
       1                         0                          1
       0                         1                          1
       0                         0                          0
──────────────────────────────────────────────────────────────────
                         Welcome to the QB Advisor
The QB Advisor displays text about Help topics here in the Help window.

■ To close the Help window, press ESC
■ To scroll text in the Help window, press PGDN, PGUP, or DIRECTION keys
■ To move between hyperlinks to topics, press TAB
(hyperlinks are words between highlighted brackets)
    How to Use QB Advisor Help System
    How to Use QuickBASIC Menus and Commands
    How to Use Dialog Boxes
    How to Select Text for Cut, Copy, and Paste Operations

■ To choose a hyperlink, press F1

See Also  Contents  Index