PCjs Machines

Home of the original IBM PC emulator for browsers.

Logo

MS BASIC 7.1 Language Reference

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

BASIC Language Reference







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

                    Microsoft(R) BASIC Language Reference
                for IBM(R) Personal Computers and Compatibles

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









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

Copyright 1989, Microsoft Corporation. All rights reserved.

Simultaneously published in the U.S. and Canada.

Printed and bound in the United States of America.



Microsoft, MS, MS-DOS, and CodeView are registered trademarks of
Microsoft Corporation.

Apple and Macintosh are registered trademarks of Apple Computer,
Inc.

Helvetica and Times Roman are registered trademarks of Linotype AG
and its subsidiaries.

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

IBM is a registered trademark of International Business Machines
Corporation.

Intel is a registered trademark of Intel Corporation.

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

WordStar is a registered trademark of MicroPro International
Corporation.



Document No. DB0118-700-R00-1089





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


The printed documentation for Microsoft BASIC 7.0 Professional Development
System consists of three books: Getting Started, the BASIC Language
Reference, and the Programmer's Guide.

Getting Started contains detailed information on setting up and customizing
Microsoft BASIC to optimize program size and speed. It also introduces new
features of this version of Microsoft BASIC and provides a brief
introduction to the new Microsoft Advisor online Help system.

The  BASIC Language Reference has these parts:

    ■   Part 1, "Language Reference," contains reference material and
        programming examples for each BASIC function, statement, and
        metacommand, organized alphabetically.

    ■   Part 2, "Add-On-Library Reference," contains reference material on the
        SUB and  FUNCTION procedures that are supported by the add-on
        libraries included with Microsoft BASIC. These add-on libraries give
        you date/time, financial, and format functions.

    ■   Part 3, "BASIC Toolbox Reference," contains reference material on the
        SUB and  FUNCTION procedures that are supported by the toolbox files
        included with Microsoft BASIC. The toolboxes are Matrix Math,
        Presentation Graphics, Font, and User Interface.

    ■   The appendixes include a list of keyboard scan and ASCII character
        codes, a list of BASIC reserved words, a command-line tools quick
        reference, reference information on error messages, and international
        character sort order tables.



The  Programmer's Guide contains topical information about programming
concepts and techniques and command-line tools.


Document Conventions

This manual uses the following typographic conventions:

Part 1 is a reference for each function, statement, and metacommand in the
BASIC language. Each entry is listed alphabetically and describes the action
performed, and the syntax to use. Arguments, options, and typical usage are
explained further under "Remarks." The "See Also" sections refer you to
related entries. In addition, example programs are included with the
descriptions so you can see exactly how a function or statement works.
In the beginning of Part 1 are summary tables for selected BASIC functions
and statements. Each table contains entries that perform related tasks.
Within each table, you can quickly see specific tasks you can accomplish,
the functions or statements to use, and the actions that result.






BASIC Functions and Statements

The sections in this chapter are made up of related BASIC functions and
statements that have been grouped together according to programming tasks.
Each group's functions and statements are presented in tabular form, listing
the type of task performed by each function or statement (for example,
looping or searching), and the corresponding program action that takes
place.

The following topics are summarized:
*    Control-flow functions and statements
*    Procedure-related statements
*    Standard I/O functions and statements
*    File I/O functions and statements
*    ISAM File I/O functions and statements
*    String-processing functions and statements
*    Graphics functions and statements
*    Trapping functions and statements

You can use these tables both as a reference guide to what each statement or
function does and as a way to identify related statements.


Note
Not all BASIC functions and statements are listed in these tables, only
those recommended for structured programming. For complete information on
all functions and statements, see the alphabetic entries that follow these
tables.



Control-Flow Functions and Statements


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
END IF
Conditionally executes or branches to different statements.

SELECT CASE
END SELECT
Conditionally executes different statements.


Managing the stack
------------------
STACK Function
Returns maximum stack size that can be allocated.

STACK Statement
Sets stack to new size.


Exiting the program
-------------------
END number
SYSTEM number
STOP number
Exit the program and set error level defined by number. If number is not
present, exit the program with error level set to 0.


Procedure-Related Statements


Defining a procedure
--------------------
FUNCTION...
END FUNCTION
Marks the beginning and end, respectively, of a FUNCTION procedure.

SUB...END SUB
Marks the beginning and end, respectively, of a SUB procedure.


Calling a procedure
-------------------
CALL
Transfers control to a BASIC SUB procedure, or to a procedure written in
another programming language and compiled separately. (The CALL keyword is
optional if a DECLARE statement is used.)


Exiting from a procedure
------------------------
EXIT FUNCTION
Provides an alternative way to exit a FUNCTION procedure.

EXIT SUB
Provides an alternative way to exit a SUB procedure.


Declaring a reference to a procedure
------------------------------------
DECLARE
Declares a FUNCTION or SUB procedure and, optionally, specifies the number
and type of its parameters.


Sharing variables among modules, procedures, or programs
--------------------------------------------------------
COMMON
Shares variables among separate modules. When used with the SHARED
attribute, COMMON blocks share variables among different procedures in the
same module. When used with a blank (unnamed) COMMON block, variables pass
from current program to new program when control is transferred with the
CHAIN statement.

SHARED
When used with the COMMON, DIM, or REDIM statement at the module level (for
example, DIM SHARED), shares variables with every SUB or FUNCTION procedure
in a single module.
When used by itself within a procedure, shares variables between that
procedure and the module-level code.

Preserving variable values
--------------------------
STATIC
Forces variables to be local to a procedure or DEF FN function and preserves
the value stored in the variable if the procedure or function is exited,
then called again.


Standard I/O Functions and Statements

Printing text on the screen
---------------------------
PRINT
Outputs text to the screen. Using PRINT with no arguments creates a blank
line.

PRINT USING
Outputs formatted text to the screen.

Changing the width of the output line
-------------------------------------
WIDTH
Changes the width of the screen to either 40 columns or 80 columns. Also, 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 the keyboard
-------------------------------
INKEY$
Reads a character from the keyboard (or a null string if no character is
waiting).

INPUT$
Reads a specified number of characters from the keyboard and stores them in
a single string variable.

INPUT
Reads input from the keyboard and stores it in a list of variables.

LINE INPUT
Reads a line of input from the keyboard and stores it in a single string
variable.

Positioning the cursor on the screen
------------------------------------
LOCATE
Moves the cursor to a specified row and column. Also sets cursor size and
turns it on and off.

SPC
Skips a specified number of spaces in printed output.

TAB
Displays printed output in a given column.

Getting information on cursor location
--------------------------------------
CSRLIN
Tells which row or line position the cursor 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.


File I/O Functions and Statements

Creating a new file or accessing an existing file or device
-----------------------------------------------------------
OPEN
Opens a file or device for retrieving or storing records (I/O).

Closing a file or device
------------------------
CLOSE
Ends I/O to a file or device.


Storing data in a file
----------------------
PRINT #
Stores a list of variables as record fields in a previously opened file.1

PRINT # USING
Similar to PRINT #, except PRINT # USING formats the record fields.1

WRITE #
Stores a list of variables as record fields in a previously opened file.1

WIDTH #
Specifies a standard width for each record in a file.1

PUT
Stores the contents of a user-defined variable in a previously opened file.2


Retrieving data from a file
---------------------------
INPUT #
Reads fields from a record and assigns each field in the record to a program
variable.1

INPUT$
Reads a string of characters from a file.

LINE INPUT #
Reads a record and stores it in a single string variable.1

GET
Reads data from a file and assigns the data to elements of a user-defined
variable.2


Getting information about a file
--------------------------------
EOF
Tests whether all data has 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, random, or ISAM).

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 number of bytes in 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 or record number for the next read or write operation
in an open file.


Managing disk drives, directories, and files
--------------------------------------------
CHDRIVE
Changes the current drive.

CURDIR$
Gives current directory specifica-tion for specified drive (or current drive
if no drive is specified).

DIR$
On first call, returns the first file that matches the file specification.
On successive calls (with no argument), returns remaining files matching the
file specification.

FILES
Prints a listing of the files in a specified directory.

FREEFILE
Returns next available file number.

KILL
Deletes a file from the disk.

NAME
Changes a file's name.
1     For use with sequential files.
2     For use with binary or random-access files.


ISAM File I/O Functions and Statements


Opening and closing tables and databases
----------------------------------------
OPEN database$ FOR ISAM tabletype tablename$
    AS #█ filenumber%
Opens a database or creates a new database, opens a table or creates a new
table.

CLOSE
Closes a specified table.

TYPE tabletype
columnname AS tablename
{columnname AS typename}
END TYPE
Declares the type of the record that is used to build the table.


Managing the data dictionary
----------------------------
CREATEINDEX
Creates an index.

DELETEINDEX
Deletes an index.


Positioning
-----------
MOVEFIRST
Makes the first record current.

MOVELAST
Makes the last record current.

MOVENEXT
Makes the next record current.

MOVEPREVIOUS
Makes the previous record current.

SEEKEQ
SEEKGE
SEEKGT
Makes matching record current.

SETINDEX
Makes the named index the current index.


Getting information about a table
---------------------------------
BOF
Returns TRUE when the current position is beyond the first record of the
current index.

EOF
Returns TRUE when the current position is beyond the last record of the
current index.

FILEATTR
Returns information about an open ISAM table.

GETINDEX$
Returns name of the current index.

LOF
Returns the number of records in a table.


Exchanging data
---------------
INSERT
Inserts a record in a table.

RETRIEVE
Retrieves the current record.

UPDATE
Overwrites current record.

DELETE
Deletes the current record.


Transaction processing
----------------------
BEGINTRANS
Marks the beginning of a transaction.

CHECKPOINT
Saves all currently open databases to disk.

COMMITTRANS
Commits all changes since the most recent BEGINTRANS.

ROLLBACK
Rolls back data to its state at the savepoint.

ROLLBACK ALL
Rolls back state of database to beginning of current transaction.

SAVEPOINT%
Defines a savepoint and returns savepoint's reference number.

Comparing text
--------------
TEXTCOMP
Compares two strings as they would be compared by ISAM.


String-Processing Functions and Statements


Getting part of a string
------------------------
LEFT$
Returns given number of characters from the left side of a string.

RIGHT$
Returns given number of characters from the right side of a string.

LTRIM$
Returns a copy of a string with leading spaces stripped away.

RTRIM$
Returns a copy of a string with trailing spaces stripped away.

MID$ function
Returns given number of characters from anywhere in a string.


Calculating available memory space
----------------------------------
FRE(a$)
For far strings, returns the space remaining in a$'s segment. For near
strings, compacts string storage space and returns space remaining in
DGROUP.

FRE(literal string)
For far strings, returns the space remaining in the temporary string
segment. For near strings, compacts string storage space and returns space
remaining in DGROUP.

FRE(number)
Measures available storage for strings, nonstring arrays, or the stack.


Searching strings
-----------------
INSTR
Searches for a string within another string.


Converting to uppercase or lowercase letters
--------------------------------------------
LCASE$
Returns a copy of a string with all uppercase letters (A-Z) converted to
lowercase 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
uppercase letters (A-Z); leaves uppercase letters and other characters
unchanged.


Changing strings
----------------
MID$ Statement
Replaces part of a string with another string.

LSET
Left justifies a string within a fixed-length string.

RSET
Right justifies a string within a fixed-length string.


Converting between numbers and strings
--------------------------------------
STR$
Returns the string representation of the value of a numeric expression.

VAL
Returns the numeric value of a string expression.


Creating strings of repeating characters
----------------------------------------
SPACE$
Returns a string of blank characters of a specified length.

STRING$
Returns a string consisting of one repeated character.


Getting the length of a string
------------------------------
LEN
Tells how many characters are in a string.


Working with ASCII values
-------------------------
ASC
Returns the ASCII value of the given character.

CHR$
Returns the character with the given ASCII value.


Creating string pointers
------------------------
SSEG
Returns the segment of the string data.

SADD
Returns the offset of the string data.

SSEGADD
Returns a far pointer to the string data.

VARPTR
Returns the offset address of a variable or string descriptor.

VARSEG
Returns the segment address of a variable or string descriptor.


Graphics Functions and Statements

Setting screen- display characteristics
---------------------------------------
SCREEN Statement
Specifies a BASIC screen mode, which determines screen characteristics such
as graphics capability, resolution, and color-number range.

SCREEN Function
Returns a character's ASCII value or its color from a specified screen
location.


Plotting or erasing a single point
----------------------------------
PSET
Draws a pixel on the screen in the specified color, using the screen's
foreground color as default.

PRESET
Draws a pixel on the screen in the specified color, using the screen's
background color as default.

Drawing shapes
--------------
LINE
Draws a straight line or a box.

CIRCLE
Draws a circle, ellipse, arc, or pie.

DRAW
Draws an object. Combines many of the features of other BASIC graphics
statements into a graphics macro language.


Defining screen coordinates
---------------------------
VIEW
Specifies a rectangle on the screen (or viewport) as the area for graphics
output.

WINDOW
Defines the dimensions of the current viewport.

PMAP
Maps view coordinates to window coordinates, or vice versa.

POINT(number)
Returns the screen coordinates of the graphics cursor, or the color of a
specified pixel.


Using color
-----------
COLOR
Sets the default colors used in graphics output.

PALETTE
Assigns different attributes to color numbers. Works only on systems
equipped with an EGA or VGA.

POINT(x, y)
Returns the color number of a pixel whose screen coordinates are x and y.


Painting enclosed shapes
------------------------
PAINT
Fills an area on the screen with 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.



Trapping Functions and Statements


Trapping errors while a program is running
------------------------------------------
ON ERROR GOTO line
At the module level, causes a program to branch to line, where line refers
to either a line number or line label. Branching takes place whenever an
error occurs during execution.

ON LOCAL ERROR
GOTO line
At the procedure level, causes a program to branch to line, where line
refers to either a line number or line label. Branching takes place whenever
an error occurs during execution of the procedure.

ON ERROR RESUME NEXT
At the module level, causes an implicit error trap, then RESUME NEXT.
Returns the error number in ERR.

ON LOCAL ERROR RESUME NEXT
At the procedure level, causes an implicit error trap, then RESUME NEXT.
Returns the error number in ERR.

RESUME
Returns control to the program after executing an error-handling routine.
The program resumes at either the statement causing the error (RESUME), the
statement after the one causing the error (RESUME NEXT), or the line
identified by line (RESUME line)


Getting error-status data
-------------------------
ERR Function
Returns the code for an error that occurs at run time.

ERR Statement
Sets ERR to an integer.

ERL
Returns the number of the line on which an error occurred (if program has
line numbers).

ERDEV
Returns a device-specific error code for the last device (such as a printer)
for which the system detected an error.

ERDEV$
Returns the name of the last device for which the system detected an error.


Defining your own error codes
-----------------------------
ERROR
Simulates the occurrence of a BASIC error; can also be used to define an
error not trapped by BASIC.


Trapping events while a program is running
------------------------------------------
ON event GOSUB line
Causes a branch to the subroutine starting with line, where line refers
either to a line number or line label, whenever event occurs during
execution.

event ON
Enables trapping of event.

event OFF
Disables trapping of event.

event STOP
Suspends trapping of event.

EVENT ON
Enables event trapping.

EVENT OFF
Disables event trapping.

RETURN
Returns control to the program after executing an event-handling subroutine.
The program resumes at either the statement immediately following the
statement that called the subroutine (RETURN), or the line that is
identified by line (RETURN line).




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


Action

Returns the absolute value of a numeric expression.


Syntax

    ABS( numeric-expression#)


Remarks

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


Example

The following example finds an approximate value for a cube root. It uses
ABS to find the difference between two guesses to see if the current
guess is accurate.  DEFDBL establishes the default data type for
all variables.

DEFDBL A-Z
Precision = .0000001#
CLS                               ' Clear the screen.
INPUT "Enter a value: ", Value    ' Prompt for input.
' Make the first two guesses.
X1 = 0#: X2 = Value
' Loop until the difference between guesses is
' less than the required precision.
DO UNTIL ABS(X1 - X2) < Precision
    X = (X1 + X2) / 2#
    ' Adjust the guesses.
    IF X * X * X - Value < 0# THEN
        X1 = X
    ELSE
        X2 = X
    END IF
LOOP
PRINT "The cube root is "; X


Output

Enter a value: 27

The cube root is  2.99999997206032




Absolute Routine
────────────────────────────────────────────────────────────────────────────


Action

Transfers control to a machine-language procedure.


Syntax

    CALL  Absolute (« argumentlist,»  integervariable%)


Remarks

The  Absolute routine uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    argumentlist                           Arguments passed to a
                                        machine-language procedure 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.

    integervariable%                       The offset from the current code
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    integervariable%                       The offset from the current code
                                        segment, set by  DEF SEG, to the
                                        starting location of the procedure.
                                        The argument  integervariable% is
                                        not passed to the procedure. Your
                                        program may need to execute a  DEF
                                        SEG statement before executing
                                        Absolute to set the code segment
                                        for the called routine. Using a
                                        noninteger value for
                                        integervariable% produces
                                        unpredictable results.






Note

The  Absolute routine is provided to maintain compatibility with earlier
versions of BASIC. Mixed-language programming using the  CALL and  DECLARE
statements provides a simpler way to use assembly language with BASIC.

When using the  Absolute routine in OS/2 protected mode, be careful not to
refer to an illegal memory address. Before it executes the  Absolute
routine, BASIC attempts to get an executable-code-segment alias for the code
you wish to access. If this operation fails, BASIC generates the error
message Permission denied. A safe place to store user-written machine code
is in memory allocated for a conventional BASIC object, such as an array.

To use the  Absolute routine in the QBX environment, use the QBX.QLB Quick
library.

To use the  Absolute routine outside of the QBX environment, link your progra
with the QBX.LIB file.

The QBX.BI header file contains the necessary declarations for the  Absolute
routine.


Basica

Assembly-language programs that are invoked from BASICA and that have string
arguments must be changed, because string descriptors are now 4 bytes long.
For a near-string descriptor, the 4 bytes are the low byte and high byte of
the string length, followed by the low byte and high byte of the string
address. Far-string descriptors also are 4 bytes long, but their structure
is proprietary. For more information on using far-string descriptors, see
Chapter 12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language
Programming with Far Strings" in the  Programmer's Guide.


See Also

CALL, CALLS Statements (Non-Basic)


Example

The following example uses  Absolute to execute a machine-language program
stored in an array. The program indicates whether a math coprocessor is
installed.

CONST nASMBYTES = 14
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 BPSave base pointer.
DATA &H8B, &HEC: ' MOV  BP,SP Get our own.
DATA &HCD, &H11: ' INT  11HMake the ROM-BIOS call.
DATA &H8B, &H5E, &H06: ' MOV  BX,[BP+6]Get argument address.
DATA &H89, &H07: ' MOV  [BX],AXSave list in argument.
DATA &H5D  : ' POP  BPRestore base pointer.
DATA &HCA, &H02, &H00: ' RET  2Pop argument off stack
'and make far return.

' Poke the machine-language program into the array.
P = VARPTR(AsmProg(1))' Get the starting offset of the array.
DEF SEG = VARSEG(AsmProg(1)) ' Change the segment.
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 the system.
' Mask off all but the coprocessor bit (bit 2).
CoProcessor = X% AND &H2
IF CoProcessor = 2 THEN
PRINT "Math coprocessor present."
ELSE
PRINT "No math coprocessor."
END IF


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


Action

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


Syntax

    ASC( stringexpression$)

Remarks

If the argument  stringexpression$ is null,  Basic generates the run-time
error message Illegal function call.


See Also

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


Example

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

CONST HASHTABSIZE = 101
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


Output

Enter a name: Bafflegab

The hash value is  66


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


Action

Returns the arctangent of a numeric expression.


Syntax

    ATN( numeric-expression)


Remarks

The argument  numeric-expression can be of any numeric type.

    ATN (arctangent) is the inverse of  TAN (tangent).  ATN takes the ratio of
two sides of a right triangle ( numeric-expression) and returns the
corresponding angle. The ratio is the ratio of the lengths of the side
opposite the angle and the side adjacent to the angle.

The result is given in radians and is in the range π/2 to π/2 radians,
where π = 3.141593 and π/2 radians = 90 degrees.  ATN is calculated in single
precision if  numeric-expression is an integer or single-precision value. If
you use any other numeric data type,  ATN is calculated in double precision.

To convert values from degrees to radians, multiply the angle (in degrees)
times π/180
(or .0174532925199433). To convert a radian value to degrees, multiply it by
180/π (or 57.2957795130824). In both cases, π ≈ 3.141593.


See Also

    COS,  SIN,  TAN


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


Output

78539816325  .78539816325




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


Action

Makes a sound through the speaker.


Syntax

    BEEP


Remarks

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

PRINT CHR$(7)


Example

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

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




BEGINTRANS Statement
────────────────────────────────────────────────────────────────────────────


Action

Indicates the beginning of a transaction (a series of ISAM database
operations).


Syntax

    BEGINTRANS


Remarks

Transactions are a way to group a series of ISAM operations so that you can
commit them
as a whole, rescind them all, or rescind operations since a designated
savepoint. Use the  COMMITTRANS statement to commit a transaction. Use the
SAVEPOINT function to designate a savepoint. Use the  ROLLBACK and  ROLLBACK
    ALL statements to rescind all or part of a transaction's operations.

If you attempt to use  BEGINTRANS when there already is a transaction
pending, BASIC generates the error message Illegal function call.

Any ISAM operation that closes a table causes transactions to be committed.
For example, if a type mismatch occurs while you are opening an ISAM table,
the table is closed and a pending transaction is committed.

You may wish to code your programs so they open all tables, then perform all
transactions, then close tables. Make sure any operation that can close a
table occurs outside a transaction.


See Also

    COMMITTRANS,  ROLLBACK,  SAVEPOINT


Example

The following example uses the  DELETE statement to remove records from an
ISAM file. It creates a transaction with the  BEGINTRANS and  COMMITTRANS
statements, and uses  SAVEPOINT and  ROLLBACK to provide rollback of any or
all of the deletions.

The program uses the file called BOOKS.MDB, which SETUP copies to your disk.

DEFINT A-Z
TYPE Borrower
Cardnum AS LONG             ' Card number.
TheName AS STRING * 36      ' Name.
Address AS STRING * 50      ' Address.
City AS STRING * 26         ' City.
State AS STRING * 2         ' State.
Zip AS LONG                 ' Zip code.
END TYPE

DIM People AS Borrower          ' Record structure variable.
CONST Database = "BOOKS.MDB"    ' Name of the disk file.
CONST Tablename = "Cardholders" ' Name of the table.
CONST viewbottom = 17, viewtop = 3, msgtxt = " *** Deleted: Savepoint "
DIM SavePts(viewbottom - viewtop + 1)
TableNum = FREEFILE
OPEN Database FOR ISAM Borrower Tablename AS TableNum
' Loop until user chooses to quit.
DO
VIEW PRINT
CLS : COLOR 15, 0
PRINT SPC(34); "Card Holders"
PRINT "Card#"; SPC(2); "Name"; SPC(13); "Address";
PRINT SPC(20); "City"; SPC(6); "State"; SPC(2); "Zip"
LOCATE 24, 1: PRINT "Choose a key:    ";
PRINT "D - Delete this record    N - Next record    Q - Quit";
MOVEFIRST TableNum
VIEW PRINT viewtop TO viewbottom: COLOR 7, 0: CLS
vPos = viewtop

' Loop through a screenful of records.
DO
' For each record, display and ask user what to do with it.
RETRIEVE TableNum, People
LOCATE vPos, 1
PRINT USING ("#####"); People.Cardnum;
PRINT "  "; LEFT$(People.TheName, 15); "  ";
PRINT LEFT$(People.Address, 25); "  ";
PRINT LEFT$(People.City, 10); "  "; People.State; "   ";
PRINT USING ("#####"); People.Zip

' Get keystroke from user.
validkeys$ = "DNQ"
DO
keychoice$ = UCASE$(INKEY$)
LOOP WHILE INSTR(validkeys$, keychoice$) = 0 OR keychoice$ = ""

' Process keystroke.
SELECT CASE keychoice$
CASE "D"
IF NOT inTransaction THEN
inTransaction = -1
BEGINTRANS
END IF
NumSavePts = NumSavePts + 1
SavePts(NumSavePts) = SAVEPOINT
DELETE TableNum
LOCATE vPos, 7: PRINT msgtxt; NumSavePts; SPC(79 - POS(0));
CASE "Q"
EXIT DO
CASE "N"
MOVENEXT TableNum
END SELECT
vPos = vPos + 1
LOOP UNTIL EOF(TableNum) OR vPos = viewbottom

' If user didn't delete any records, simply quit.
IF NumSavePts = 0 THEN EXIT DO
' Allow user to commit deletions, or roll back some or all of them.
VIEW PRINT: LOCATE 24, 1: PRINT "Choose a key:    ";
PRINT "R - Rollback to a savepoint   A - Rollback all deletions"
PRINT SPC(17); "Q - commit deletions and Quit";
validkeys$ = "RAQ"
DO
keychoice$ = UCASE$(INKEY$)
LOOP WHILE INSTR(validkeys$, keychoice$) = 0 OR keychoice$ = ""
SELECT CASE keychoice$
CASE "R"
VIEW PRINT 24 TO 25: PRINT : PRINT
DO
PRINT "Roll back to which savepoint ( 1 -"; NumSavePts; ")";
INPUT RollbackPt
LOOP UNTIL RollbackPt > 0 AND RollbackPt <= NumSavePts
ROLLBACK SavePts(RollbackPt)
NumSavePts = RollbackPt - 1
CASE "A"
NumSavePts = 0
ROLLBACK ALL
CASE "Q"
EXIT DO
END SELECT
LOOP

IF inTransaction THEN COMMITTRANS
CLOSE
END




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


Action

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


Syntax

    BLOAD  filespec$«,  offset%»


Remarks

The  BLOAD statement 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.

The  BLOAD statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filespec$                              A string expression that specifies
                                        the file or device from which to
                                        load a memory-image file.

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





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 (DGROUP) is used as the default.

If the offset is a long integer, or a single-precision or double-precision
number, it is converted to an integer. If the offset is a negative number
between -1 and -32,768, inclusive, it is treated as an unsigned 2-byte
offset.


Note

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

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.

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

Because BASIC program code and data items are not stored in the same
locations as they were in BASICA, do not use  BLOAD with files created by
BASICA programs.


BLOAD and Expanded Memory Arrays

Do not use  BLOAD to load a file into an expanded memory array. If you start
QBX with the /Ea switch, any of these arrays may be stored in expanded
memory:

    ■   Numeric arrays less than 16K in size.

    ■   Fixed-length string arrays less than 16K in size.

    ■   User-defined-type arrays less than 16K in size.


If you want to use  BLOAD to load a file into an array, first start QBX
without the /Ea switch.  (Without the /Ea switch, no arrays are stored in
expanded memory.)

For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.


BASICA

    BLOAD does not support the cassette device.


See Also

    BSAVE;  DEF  SEG;  SSEG;  VARPTR,  VARSEG


Example

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

You must create the file MAGCUBE.GRH using the  BSAVE statement programming
example before you can run this program.

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




BOF Function


Action

Tests whether the current position is at the beginning of an ISAM table.


Syntax

    BOF( filenumber%)


Remarks

    BOF returns true (nonzero) if the current position is at the beginning of
the table. The beginning of an ISAM table is the position before the first
record according to the current index. The argument  filenumber% is the
number used in the  OPEN statement to open the table.


See Also

    EOF,  LOC,  LOF,  OPEN


Example

See the  CREATEINDEX statement programming example, which uses the  BOF
function.




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


Action

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


Syntax

    BSAVE  filespec$,  offset%,  length%


Remarks

The  BSAVE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filespec$                              A string expression that specifies
                                        the name of the file or device on
                                        which to save a memory-image file.

    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 that
                                        returns an unsigned integer
                                        between 0 and 65,535, inclusive.-

Argument                                Description
────────────────────────────────────────────────────────────────────────────





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.

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


Note

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

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



If no  DEF SEG statement is executed before the  BSAVE statement, the
program uses the default BASIC data segment (DGROUP). 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 long integer, or single- or double-precision
floating-point value, it is converted to an integer. If the offset is a
negative number between -1 and -32,768, inclusive, it is treated
as an unsigned 2-byte offset.


BSAVE and Expanded Memory Arrays

Do not use  BSAVE to transfer an expanded memory array to an output file.
(If you start QBX with the /Ea switch, any of these arrays may be stored in
expanded memory:

    ■   Numeric arrays less than 16K in size.

    ■   Fixed-length string arrays less than 16K in size.

    ■   User-defined-type arrays less than 16K in size.


If you want to use  BSAVE to transfer an array to an output file, first
start QBX without the /Ea switch. (Without the /Ea switch, no arrays are
stored in expanded memory.)

For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.


BASICA

    BSAVE does not support the cassette device.


See Also

    BLOAD,  DEF SEG


Example

The following 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
programming example 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.





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


Action

Transfers control to a BASIC  SUB procedure. To invoke a non-BASIC
procedure, use the  CALL, CALLS statements (non-BASIC).


Syntax 1

    CALL  name «( argumentlist)»


Syntax 2

    name «( argumentlist)»


Remarks

The  CALL statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    name                                   The name, limited to no more than
                                        40 characters, of the BASIC  SUB
                                        procedure being called.

    argumentlist                           The variables or constants passed
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    argumentlist                           The variables or constants passed
                                        to the procedure. Arguments in the
                                        list are separated by commas.
                                        Arguments are passed by reference
                                        (which means they can be changed
                                        by the procedure).





If  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())

If you omit the optional  CALL keyword, you must declare the procedure in a
DECLARE statement and omit the parentheses around  argumentlist. For more
information, see Chapter 2,  "SUB and FUNCTION Procedures" in the
Programmer's Guide.

The  CALL statement passes arguments only by reference, which means that the
procedure is given the address of the argument. This allows procedures to
change the argument values.

Although the  CALL statement does not pass arguments by value, you can
simulate that by enclosing the argument in parentheses. This makes the
argument an expression. (If an argument is passed by value, the procedure is
given the value of the argument.)

For example, the following statement calls a procedure and passes a single
argument:

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 procedure. Any change made by the
procedure SolvePuzzle is made to the temporary location only, and not to
StartValue itself.


See Also

    Absolute Routine;  CALL,  CALLS (Non-BASIC);  DECLARE (BASIC)


Example

The following example uses the  CALL statement to call a  SUB procedure that
prints a message on the 25th line of the display:

CLS' Clear screen.
message$ = "The quick brown fox jumped over the lazy yellow dog."
CALL PrintMessage(message$)
END

SUB PrintMessage (message$)
    LOCATE 24, 1 ' Move cursor to 25th line of display.
    PRINT message$;
END SUB




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


Action

Transfer control to a procedure written in another language. To invoke a
BASIC procedure, use the  CALL statement (BASIC).


Syntax 1

    CALL  name «( call-argumentlist)»


Syntax 2

    name « call-argumentlist»


Syntax 3

    CALLS  name «( calls-argumentlist)»


Remarks

The  CALL keyword is optional when you use the  CALL statement. When you
omit  CALL, you must declare the procedure in a  DECLARE statement. When you
omit  CALL, you omit the parentheses around the argument list. For more
information about invoking procedures without the  CALL keyword, see Chapter
2, "SUB and FUNCTION Procedures" in the  Programmer's Guide.

    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.

The  CALL and  CALLS statements use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    name                                   The name of the non-BASIC
                                        procedure being called.

    call-argumentlist                      The variables, arrays, or
                                        expressions passed to the
                                        procedure.

    calls-argumentlist                     The variables or expressions
                                        CALLS passes to the procedure.





The  call-argumentlist has two forms of syntax. In the first form,  argument
is a variable:

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

If  argument is an array, parentheses are required:

«argument«( )»» «,  argument «( )»»...

The following list describes the parts of  call-argumentlist:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    BYVAL                                  Indicates the argument is passed
                                        by value rather than by near
                                        reference (the default is by
                                        reference).  BYVAL cannot be used
                                        if the argument is an array.

    SEG                                    Passes the argument as a segmented
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    SEG                                    Passes the argument as a segmented
                                        (far) address.  SEG cannot be used
                                        if the argument is an array.

    argument                               A BASIC variable, array, or
                                        expression passed to a procedure.





Use the first syntax if
    argument is not an array; use the second if  argument is an array. The
array is specified by the array name and a pair of parentheses. For example:


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

The argument  calls-argumentlist has the following syntax, where  argument
is a BASIC variable or expression:

« argument» «,  argument»...

These arguments are passed by reference as far addresses, using the segment
and offset of the variable. Whole array arguments cannot be passed by calls.

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 the procedure in the
other language must accept an address (because the address of the temporary
location is passed).


Note

If the argument  name refers to an assembly-language procedure, it must be a
name declared with  PUBLIC (symbol).


Be careful using the  SEG keyword to pass elements of arrays because BASIC
may move arrays 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 defined functions.


See Also

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


Example

See the  VARPTR function programming example, which uses a  CALL statement
to invoke a C function.




CCUR Function
────────────────────────────────────────────────────────────────────────────


Action

Converts a numeric expression to a currency value.


Syntax

    CCUR( numeric-expression)


Remarks

The argument  numeric-expression can be any numeric expression.


See Also

    CDBL,  CINT,  CLNG,  CSNG


Example

The following example passes a double-precision, floating-point value to a
FUNCTION procedure that returns the sales tax, as a currency value, for the
passed value. The returned value has four digits of precision, but it is
displayed in conventional currency value format with two places to the right
of the decimal.  CCUR is used to convert from double-precision to currency
data type.

DECLARE FUNCTION GetSalesTax@ (Amount#, percent!)
' $INCLUDE: 'FORMAT.BI'
CONST percent! = 8.1
CLS    ' Clear screen.
INPUT "What is the taxable currency amount"; Amount#
PRINT
USCurFmt$ = FormatC$(GetSalesTax@(Amount#, percent!), "$#,###,###,##0.00")
SetFormatCC (49)    ' West Germany
WGCurFmt$ = FormatC$(GetSalesTax@(Amount#, percent!), "#.###.###.##0,00")
WGCurFmt$ = WGCurFmt$ + " DM"

PRINT "In the United States, currency is displayed with commas as"
PRINT "numerical separators and a period serves to separate whole from"
PRINT "fractional currency amounts. In some European countries, the"
PRINT "numerical separator is a period, and the comma serves to separate"
PRINT "whole from fractional currency amounts."
PRINT
PRINT "In the US, the tax on $"; Amount#; "at"; percent!; "percent is "
PRINT "displayed as "; USCurFmt$
PRINT
PRINT "In West Germany, the tax on"; Amount#; "DM at"; percent!; "percent"
PRINT "is displayed as "; WGCurFmt$
END

FUNCTION GetSalesTax@ (Amount#, percent!)
    GetSalesTax@ = CCUR(Amount# * (percent! * .01))
END FUNCTION




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


Action

Converts a numeric expression to a double-precision value.


Syntax

    CDBL( numeric-expression)


Remarks

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

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.


See Also

    CCUR,  CINT,  CLNG,  CSNG


Example

The following example demonstrates how the precision of the argument affects
the value returned by  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)
PRINT 7#/9#' Accurate to 15 decimal places.


Output

.7777778
.7777777910232544
.7777777910232544
.7777777777777778




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


Action

Transfers control from the current program to another program.


Syntax

    CHAIN  filespec$


Remarks

The argument  filespec$ is a string expression that represents the program
to which control is passed. It may include a path. (With DOS 2.1 or earlier
versions, you cannot use  CHAIN unless  filespec$ provides a complete path,
including drive. Also under DOS 2.1, if the run-time module is in the root
directory, the root directory must be listed in the PATH environment
variable.) Programs running within the QBX 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 BASIC
environment assume a .EXE extension and cannot chain to BASIC source files
(files with a .BAS extension).

You can pass variables between programs using the  COMMON statement to set
up a blank common block. For more information on passing variables, see the
entry for the  COMMON statement.

When you compile a program outside the QBX environment, the BCL70efr.LIB
object-module library does not support  COMMON. There are two ways to use
COMMON with chained programs outside the environment:

    ■   Use the default (BRT70EFR.EXE for DOS and OS/2 real mode; BRT70EFR.DLL
        for OS/2 protected mode) by compiling the programs using the option in
        the Make EXE dialog box called "EXE Requiring BRT Module."

    ■   Use BRT70EFR.LIB by compiling from the command line without the /O
        option. For more information, see Appendix C, "Command-Line Tools
        Quick Reference."


Note

When programs use BRT70EFR.EXE or BRT70EFR.DLL, files are left open during
chaining unless they are explicitly closed with a  CLOSE statement. The
filenames BCL70efr.LIB, BRT70EFR.EXE, and BRT70EFR.DLL assume that you
selected these compiler options when you installed BASIC: emulator
floating-point math, far strings, and real mode. If you used different
options, see Chapter 17, "About Linking and Libraries" in the  Programmer's
Guide for information about other compiler options.


    CHAIN is similar to  RUN. The main differences are that  RUN closes all
open files and does not support data blocks declared with  COMMON.


BASICA

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

The current version of BASIC does not support the all, merge, or delete
option available in BASICA, nor does it allow you to specify a line number.

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


See Also

    CALL (BASIC), Common,  RUN


Example

In the following example, 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, then uses the  CHAIN statement to
load and run the other program. The second program finds and prints the
average of the values. The first two statements initialize the variables
that are passed to PROG2.

DIM values(1 TO 50)
COMMON values(), NumValues%

' PROG2 creation section.
' The following few lines of code create the second program on the
' disk so that it can load and run with the CHAIN statement. It uses
' PRINT # statements to put the proper BASIC statements in a file.
OPEN "PROG2.BAS" FOR OUTPUT AS #1
PRINT #1, "' PROG2 for the CHAIN and COMMON statements example."
PRINT #1, "DIM X(1 TO 50)"
PRINT #1, "COMMON X(), N%"
PRINT #1, "PRINT"
PRINT #1, "IF N% > 0 THEN"
PRINT #1, "   Sum% = 0"
PRINT #1, "   FOR I% = 1 TO N%"
PRINT #1, "      Sum% = Sum% + X(I%)"
PRINT #1, "   NEXT I%"
PRINT #1, "   PRINT "; CHR$(34); "The average of the values is";
PRINT #1, CHR$(34); "; Sum% / N%"
PRINT #1, "END IF"
PRINT #1, "END"
CLOSE #1
' End of PROG2 creation section.

CLS
PRINT "Enter values one per line. Type 'END' to quit."
NumValues% = 0
DO
    INPUT "-> ", N$
    IF I% >= 50 OR UCASE$(N$) = "END" THEN EXIT DO
    NumValues% = NumValues% + 1
    values(NumValues%) = VAL(N$)
LOOP
PRINT "Press any key to continue... "
DO WHILE INKEY$ = ""
LOOP
CHAIN "PROG2.BAS"
END




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


Action

Changes the current default directory for the specified drive.


Syntax

    CHDIR  pathname$


Remarks

The argument  pathname$ is a string expression identifying the directory
that is to become the default directory. The  pathname$  expression 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 cannot be shortened to CD.

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

CHDIR "D:\TMP"

Use  CURDIR$ to return the current directory and  CHDRIVE to change the
default drive.


See Also

    MKDIR,  RMDIR


Example

This example uses the MKDIR statement to create a subdirectory. The AddADir
procedure uses the CHDIR statement with the ON ERROR statement to check if
the subdirectory already exists. If it does not exist, the error-handling
routine traps error 76, prompts the user, and creates the directory.

DECLARE SUB AddADir (DstDir$)

CLS
AddADir "TESTDIR"

SUB AddADir (DestDir$)
ON LOCAL ERROR GOTO ErrHandler'Set up the local error handler.
CurDirName$ = CURDIR$'Preserve the name of the current directory.
CHDIR$ DestDir$'Change to DestDir$ - Error 76 if not exist.
CHDIR$ CurDirName$'Change back to original directory.
EXIT SUB

ErrHandler:
IF ERR = 76 THEN
PRINT "Directory does not exist. Create ?";
Ans$ = INPUT(1)
PRINT Ans$
IF UCASE$(Ans$) = "Y" THEN
MKDIR DestDir$'Make the directory.
PRINT DestDir$; "directory created."
RESUME NEXT
ELSE
PRINT DestDir$; "directory not created."
END IF'Return control to caller.
END IF
RESUME NEXT'Just continue.
END SUB




CHDRIVE Statement
────────────────────────────────────────────────────────────────────────────


Action

Changes the current drive.


Syntax

    CHDRIVE  drive$


Remarks

The argument  drive$ is a string expression that specifies a new default
drive. It must correspond to an existing drive and must be in the range A to
    lastdrive, where  lastdrive is the maximum drive letter you set in your
CONFIG.SYS file.

If you supply a null argument ("") for  drive$, the current drive does not
change. If the argument  drive$ is a string,  CHDRIVE uses only the first
letter. If you omit  drive$, BASIC generates the error message Expected:
Expression (in QBX) or String expression required (outside of QBX).

    CHDRIVE is not case sensitive. "C" is the same as "c."


See Also

    CHDIR,  CURDIR$


Example

The following example demonstrates use of the  CHDRIVE statements. It calls
a  SUB procedure that evaluates a file specification and changes the
currently logged drive if necessary.

DECLARE SUB ChangeDataDrive (filespec$)
ON ERROR RESUME NEXT
filespec$ = "A:"
ChangeDataDrive filespec$
filespec$ = "C:\DOS"
ChangeDataDrive filespec$
SUB ChangeDataDrive (filespec$)
    curdrive$ = LEFT$(CURDIR$, 2)        ' Get the current drive.
    ' Determine if there is a drive name on the filespec.
    IF INSTR(1, filespec$, ":") = 2 THEN
        newdrive$ = LEFT$(filespec$, 2)
    ELSE
        newdrive$ = curdrive$
    END IF
    ' Ensure that the new drive is different from the
    ' currently logged drive.
    IF newdrive$ <> curdrive$ THEN
        CHDRIVE newdrive$           ' It isn't, so change it.
        PRINT "Logged drive changed from "; curdrive$; " to "; newdrive$
    ELSE                            ' It is, so don't change it.
        PRINT "New drive same as logged drive. No change occurred."
    END IF
END SUB




CHECKPOINT Statement
────────────────────────────────────────────────────────────────────────────


Action

Writes all open ISAM database buffers to disk in their current state.


Syntax

    CHECKPOINT


See Also

    ROLLBACK,  SAVEPOINT


Example

See the programming example for the  SEEKGT,  SEEKGE,  SEEKEQ statements,
which uses the  CHECKPOINT statement.




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


Action

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


Syntax

    CHR$( code%)


Remarks

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

    CHR$ also can be used to include a double quotation mark (") in a string.
The following line adds a double-quotation-mark character to the beginning
and the end of the string:

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


See Also

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


Example

The following example uses  CHR$ to display graphics characters in the
extended character set and uses these characters to draw boxes on the
screen:

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

' SUB procedure to display boxes.
' Parameters:
'  Urow%, Ucol%: Row and column of upper-left corner.
'  Lrow%, Lcol%: Row and column of lower-right corner.
CONST VERT=186, HORZ=205     ' Extended ASCII graphics characters.
CONST ULEFTC=201, URIGHTC=187, LLEFTC=200, LRIGHTC=188
SUB DBox (Urow%, Ucol%, Lrow%, Lcol%) STATIC
    LOCATE Urow%, Ucol% : PRINT CHR$(ULEFTC);' Draw top of box.
    LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORZ));
    LOCATE ,Lcol% : PRINT CHR$(URIGHTC);
    FOR I=Urow%+1 TO Lrow%-1' Draw body of box.
        LOCATE I,Ucol% : PRINT CHR$(VERT);
        LOCATE  ,Lcol% : PRINT CHR$(VERT);
    NEXT I
    LOCATE Lrow%, Ucol% : PRINT CHR$(LLEFTC);' Draw bottom of box.
    LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORZ));
    LOCATE ,Lcol% : PRINT CHR$(LRIGHTC);
END SUB




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


Action

Converts a numeric expression to an integer by rounding the fractional part
of the expression.


Syntax

    CINT( numeric-expression)


Remarks

If  numeric-expression is not between -32,768 and 32,767, inclusive,
BASIC generates the run-time error message Overflow.

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


See Also

    CCUR,  CDBL,  CLNG,  CSNG,  FIX,  INT


Example

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

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


Output

Angle in radians = 1.5708
Angle equals 90 degrees 0 minutes




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


Action

Draws an ellipse or circle with a specified center and radius.


Syntax

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

Remarks

The following list describes the parts of the  CIRCLE statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   The  STEP option specifies that
                                        x! and  y! are offsets relative to
                                        current graphics cursor position,
                                        enabling use of relative
                                        coordinates.

    x!, y!                                 The screen coordinates for the
                                        center of the circle or ellipse.

    radius!                                The radius of the circle or
                                        ellipse in the units of the
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        ellipse in the units of the
                                        current coordinate system, which
                                        is determined by the most recently
                                        executed  SCREEN statement, along
                                        with any  VIEW or  WINDOW
                                        statements.

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

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

                                        To convert values from degrees to
                                        radians, multiply the angle (in
                                        degrees) by π/180 (which equals
                                        .0174532925199433).

                                        If  start! is negative,  CIRCLE
                                        draws a radius to  start! and
                                        treats the angle as positive. If
                                        end! is negative,  CIRCLE draws a
                                        radius to  end! and treats the
                                        angle as positive. If both  start!
                                        and  end! are negative,  CIRCLE
                                        draws a radius to both  start! and
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        draws a radius to both  start! and
                                            end! and treats the angle as
                                        positive.

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

    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:

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

                                            aspect! = 4 * ( ypixels/xpixels
                                        )/3

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

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




To draw a radius to angle 0 (a horizontal line segment to the right), do not
give the angle as -0. Instead, use a very small non-zero value as
shown in the following code fragment, which draws a one-quarter wedge of a
circle.

SCREEN 2
CIRCLE (200,100),60,,-.0001,-1.57

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

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

If you omit a trailing argument, do not include its corresponding comma in
the statement.

The  CIRCLE statement updates the graphics cursor position to the center of
the ellipse or circle after drawing is complete.

You can use coordinates that are outside the screen or viewport. You can
show coordinates as absolutes, or you can 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 were (10,10), the statement
below would draw a circle with radius 75 and center offset 10 from the
current x coordinate and 5 from the current y coordinate. The circle's
center would be (20,15).

CIRCLE STEP (10,5), 75


Example

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

CONST PI=3.141593
SCREEN 2
' Draw a circle with the upper-left quarter missing.
' Use negative numbers so radii are drawn.
CIRCLE (320,100), 200,, -PI, -PI/2
' Use relative coordinates to draw a circle within the missing
' quarter.
CIRCLE STEP (-100,-42),100
' Draw a small ellipse inside the circle.
CIRCLE STEP(0,0), 100,,,, 5/25
' Display the drawing until a key is pressed.
LOCATE 25,1 : PRINT "Press any key to end.";
DO
LOOP WHILE INKEY$=""




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


Action

Reinitializes all program variables, closes any open files, and optionally
sets the stack size.


Syntax

    CLEAR «,,  stack&»


Remarks

The  CLEAR statement performs the following actions:

    ■   Closes all files and releases the file buffers.

    ■   Clears all common variables.

    ■   Sets numeric variables and arrays to zero.

    ■   Sets all string variables to null.

    ■   Reinitializes the stack and, optionally, changes its size.

The  stack& parameter sets aside stack space for your program.  BASIC
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 BASIC compatible with BASICA.
BASICA included an additional argument that set the size of the data
segment. Because BASIC 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 also may 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
a  GOSUB operation. This makes it impossible to execute a  RETURN statement
correctly, and BASIC generates a  RETURN without GOSUB run-time error
message. If you use a  CLEAR statement in a  SUB or  FUNCTION declaration,
BASIC  generates the run-time error message Illegal function call.


BASICA

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


See Also

    ERASE,  FRE,  SETMEM,  STACK Function


Example

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

CLEAR ,,2000




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


Action

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


Syntax

    CLNG( numeric-expression)


Remarks

If  numeric-expression is not between -2,147,483,648 and
2,147,483,647, inclusive, BASIC generates the error message Overflow.


See Also

    CCUR,  CDBL,  CINT,  CSNG


Example

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

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


Output

32767  32768




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


Action

Concludes I/O to a file, device, or ISAM table.


Syntax

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


Remarks

The  CLOSE statement complements the  OPEN statement.

The argument  filenumber% is the number used in the  OPEN statement to open
the file, device, or ISAM table. A  CLOSE statement with no arguments closes
all open files and devices, including all open ISAM tables.

The association of a file, device, or ISAM table with  filenumber% ends when
a  CLOSE statement is executed. You then can reopen the file, device, or
table using the same or a different file number.

Any ISAM operation that closes a table causes transactions to be committed.
For example, if a type mismatch occurs while you are opening an ISAM table,
the table is closed and a pending transaction is committed.

You may wish to code your programs so they first open all tables, then
perform all transactions, then close tables. Make sure any operation that
can close a table occurs outside a transaction.

Using a  CLOSE statement 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, device, or table.


The  CLEAR,  END,  RESET,  RUN, and  SYSTEM statements, and the  CHAIN
statement when used with the /O command-line option, also close all files,
devices, and tables.


Note

    CLOSE commits any pending ISAM transactions.


See Also

    END,  OPEN,  RESET,  STOP


Example

See the  FREEFILE function programming example, which uses the  CLOSE
statement.




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


Action

Clears various parts of the display screen.


Syntax

    CLS «{ 0 |  1 |  2}»


Remarks

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

╓┌──────────┌───────────────────────────────┌────────────────────────────────╖
Statement  Condition                       Operations performed
────────────────────────────────────────────────────────────────────────────
    CLS       Graphics-screen mode no         Clears default graphics
            user-defined graphics viewport  viewport; regenerates bottom
                                            text line; returns cursor to
                                            the upper-left corner of the
                                            screen.

            Graphics-screen mode            Clears user-defined graphics
            user-defined viewport           viewport; does not regenerate
                                            bottom text line; does not
                                            return the cursor to the
                                            upper-left corner of the screen.

            In screen mode 0 (text mode)    Clears text viewport;
                                            regenerates bottom text line;
Statement  Condition                       Operations performed
────────────────────────────────────────────────────────────────────────────
                                            regenerates bottom text line;
                                            returns the text cursor to the
                                            upper-left corner of the screen.

    CLS 0     Any screen mode, combination    Clears the screen of all text
            of viewports                    and graphics, except bottom
                                            text line; clears graphics
                                            viewport; regenerates bottom
                                            text line; returns the cursor
                                            to the upper-left corner of the
                                            screen.

    CLS 1     Graphics-screen mode with no    Clears default graphics
            user-defined graphics viewport  viewport; does not clear text
                                            viewport; regenerates bottom
                                            text line; returns the cursor
                                            to upper-left corner of the
                                            screen.

Statement  Condition                       Operations performed
────────────────────────────────────────────────────────────────────────────

            Graphics-screen mode with        Clears user-defined graphics
            user-defined graphics viewport  viewport; does not clear text
                                            viewport; does not regenerate
                                            bottom text line; does not
                                            return the cursor to the
                                            upper-left corner of the screen.

            In screen mode 0 (text mode)    Has no effect.

    CLS 2     Any screen mode                 Clears the text viewport (even
                                            if the user-defined text
                                            viewport includes the bottom
                                            line of text, it will not be
                                            cleared); does not clear the
                                            graphics viewport; does not
                                            regenerate the bottom text
                                            line; returns the cursor to
                                            upper-left corner of the screen.
Statement  Condition                       Operations performed
────────────────────────────────────────────────────────────────────────────
                                            upper-left corner of the screen.




The behavior of a particular  CLS statement depends on:

    ■   The  CLS statement argument: 0, 1, 2, or none.

    ■   The current screen mode.

    ■   Whether a  VIEW statement has been executed that has changed the
        graphics viewport from the default of the entire screen.

    ■   Whether a  VIEW  PRINT statement has been executed that established a
        user-defined viewport.

    ■   Whether a  KEY  ON statement has been executed that established the
        bottom text line as a list of function-key assignments. The bottom
        line on the screen may be 25, 30, 43, or 60, depending upon the
        current screen mode.


The following fundamentals about the graphics and text viewports determine
how the  CLS statement works:


    ■   Screen mode 0 has only a text viewport. All other screen modes have
        both a text and graphics viewport.

    ■   The default graphics viewport is the entire screen.

    ■   The default text viewport is the entire screen, except for the bottom
        line of text.

    ■   After a user-defined graphics viewport (or "clipping region") has been
        established by execution of a  VIEW statement, it is reset to the
        default by execution of any of these statements:  VIEW without
        arguments;  CLEAR; any  SCREEN statement that changes the screen
        resolution.

    ■   After a user-defined text viewport has been established by execution
        of a  VIEW  PRINT statement, it is reset to the default by execution
        of either a  VIEW  PRINT statement without arguments, or any
        text-oriented statement, such as  WIDTH, that changes the number of
        text columns or text lines on the screen.

    ■   If the  KEY  ON statement has been executed and the  CLS statement
        regenerates the bottom screen line, the  CLS statement regenerates the
        function-key assignment list. If the  KEY  ON statement has not been
        executed, the  CLS statement generates a line of blank characters.


See Also

    VIEW,  VIEW PRINT,  WINDOW


Example

The following example draws random circles in a graphics viewport and prints
to 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
LOCATE 25,1 : PRINT "Press any key to stop."
' Outside the text viewport.
Count=0
DO
CIRCLE (50,40),INT((35-4) * RND + 5),(Count MOD 4)
' Clear graphics viewport every 30 times.
IF (Count MOD 30)=0 THEN CLS 1
PRINT "Hello. ";
' Clear text viewport every 45 times.
IF (Count MOD 45)=0 THEN CLS 2
Count=Count+1
LOOP UNTIL INKEY$ <> ""




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


Action

Sets the foreground and background colors for the display.


Syntax 1

    COLOR  «foreground&»«, «background&»«, border&»»  Screen mode 0 (text only)

Syntax 2

    COLOR «background&»«, palette%»                   Screen mode 1

Syntax 3

    COLOR  «foreground&»                              Screen mode 4

Syntax 4

    COLOR  «foreground&»«, background&»               Screen modes 7-10

Syntax 5

    COLOR  «foreground&»                              Screen modes 12,13


Remarks

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

The  COLOR statement does not determine the range of available colors. The
combination of adapter, display, and screen mode determines the color range.
If you use  COLOR statement arguments outside these valid ranges, BASIC
generates the error message Illegal function call. For more information, see
the entry for the  SCREEN statement.

The  COLOR statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    foreground&                            Text color attribute in screen
                                        mode 0; text or line-drawing
                                        display color in screen mode 4;
                                        text and line-drawing color
                                        attribute in screen modes
                                        7-10, 12, and 13.

    background&                            Color code or color attribute for
                                        screen background.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        screen background.

    border&                                Color code for the area
                                        surrounding the screen.

    palette%                               In screen mode 1, one of two
                                        three-color palettes: is green,
                                        red, and brown; 1 is cyan, magenta,
                                        and bright white.





The different versions of syntax and their effects in different screen modes
are described in the following table:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Screen mode                             Syntax and description
Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────
0                                        COLOR «foreground&»«, «
                                        background&»«,  border&»»

                                        Modifies the current default text
                                        foreground and background colors
                                        and the screen border. The
                                        foreground& color value must be an
                                        integer expression between 0 and
                                        31, inclusive. It determines the
                                        foreground color in text mode --
                                        the default color of text. Sixteen
                                        colors can be selected with the
                                        integers 0-15. A blinking version
                                        of a color is specified by adding
                                        16 to the color number. For
                                        example, a blinking color 7 is
                                        equal to 7 + 16, or 23.

                                        The  background& color value is an
Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────
                                        The  background& color value is an
                                        integer expression between 0 and 7,
                                        inclusive, and is the color of the
                                        background for each text character.
                                        Blinking background colors are not
                                        supported.

                                        The  border& color, which fills
                                        the screen area outside the text
                                        area, is an integer expression
                                        between 0 and 15, inclusive. Note
                                        that the  border& argument has no
                                        effect with the following
                                        adapters: the IBM Enhanced
                                        Graphics Adapter (EGA), the IBM
                                        Video Graphics Array adapter (VGA),
                                        and the IBM Multicolor Graphics
                                        Array adapter (MCGA).

Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────

1                                        COLOR «background&»«, palette%»

                                        The  background& color value must
                                        be an integer expression between 0
                                        and 3, inclusive.

                                        The argument  palette% is an
                                        integer expression with an odd or
                                        even value between 0 and 255,
                                        inclusive. An even value makes
                                        available one set of three default
                                        foreground colors, and an odd
                                        value makes available a different
                                        default set.

                                        The default colors for  palette%
                                        are equivalent to the following
                                        PALETTE statements on a system
Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────
                                        PALETTE statements on a system
                                        equipped with an EGA:


' Definition of the even palette-number set.
COLOR ,0' In screen mode 1, an even palette
'   number is equivalent to:
PALETTE 1,2 ' EGA Attribute 1 = color 2 (green)
PALETTE 2,4 ' EGA Attribute 2 = color 4 (red)
PALETTE 3,6 ' EGA Attribute 3 = color 6 (yellow)

' Definition of the odd palette-number set.
COLOR ,1' In screen mode 1, an odd palette
'   number is equivalent to:
PALETTE 1,3 ' EGA Attribute 1 = color 3 (cyan)
PALETTE 2,5 ' EGA Attribute 2 = color 5 (magenta)
PALETTE 3,7 ' EGA Attribute 3 = color 7 (white)

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────
                                        Note that in screen mode 1, a
                                        COLOR statement overrides  PALETTE
                                        statements that were executed
                                        previously.

4                                        COLOR  «foreground&»

                                        The screen  foreground& color
                                        value must be an integer
                                        expression between 0 and 15,
                                        inclusive. This expression sets
                                        the display color associated with
                                        color attribute 1 only. The screen
                                        background color is fixed as black.

7-10                                     COLOR  «foreground&»«,
                                        background&»

                                        The argument  foreground&, the
Screen mode                             Syntax and description
────────────────────────────────────────────────────────────────────────────
                                        The argument  foreground&, the
                                        line-drawing color, is a color
                                        attribute. The argument
                                        background&, the screen color, is
                                        a display color.

12, 13                                   COLOR  «foreground&»

                                        The argument  foreground&, the
                                        line drawing color, is a color
                                        attribute.




BASIC generates the error message Illegal function call if the  COLOR
statement is used in screen modes 2, 3, or 11. Use the  PALETTE statements
to set the color in screen mode 11.

The foreground can be the same color as the background, making characters
and graphics invisible. The default background color is black for all
display hardware configurations and all screen modes. This background is
produced by the default display color of 0 associated with the background
color attribute of 0.

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 (an olive drab), you would use the following  PALETTE
statement:

PALETTE 0,8224

To make the background color bright red-violet, use the following  PALETTE
statement:

PALETTE 0, 4128831

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 color-attribute
ranges for the  foreground&,  background&, and  border& colors. For more
information, see the  PALETTE statement.


See Also

    PAINT,  PALETTE,  SCREEN Statement


Example

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

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 brown box.
LOCATE 12, 7: PRINT "Press any key to continue..."
DO : LOOP WHILE INKEY$ = ""
' Background& = 2 (green).
' Foreground& = odd palette number (white, magenta, cyan).
COLOR 2, 1
LINE (20, 20)-(300, 180), 3, B    ' Draw a bright white 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




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


Action

Enable, disable, or suspend event trapping at the COM port.


Syntax

    COM( n%)  ON
    COM( n%)  OFFn%)
    COM( n%)  STOP


Remarks

The argument  n% specifies the number of the COM (serial) port;  n% can be
either 1 or 2.

    COM( n%)  ON enables communications-event trapping on COM port  n%. If a
character arrives at a communications port after a  COM( n%)  ON statement,
the routine specified in the  ON  COM statement is executed.

    COM( n%)  OFF disables communications-event trapping on COM port  n%. No
communications trapping takes place until another  COM( n%)  ON statement is
executed. Events occurring while trapping is off are ignored.

    COM( n%)  STOP suspends communications-event trapping on COM port  n%. No
trapping takes place until a  COM( n%)  ON statement is executed. Events
occurring while trapping is suspended are remembered and processed when the
next  COM( n%)  ON statement is executed. However, remembered events are
lost if  COM( n%)  OFF is executed

When a communications-event trap occurs (that is, the  GOSUB operation is
performed), an automatic  COM( n%)  STOP is executed so that recursive traps
cannot take place. The  RETURN statement from the trapping routine
automatically executes a  COM( n%)  ON statement unless an explicit  COM(
n%)  OFF was performed inside the routine.

For more information, see Chapter 9, "Event Handling" in the  Programmer's
Guide.


See Also

    ON  event


Example


The following example opens COM1 and then monitors the COM1 port for input.
It uses the  ON COM statement to trap communications events.

CLS
' Set up error handling in case COM1 doesn't exist.
ON ERROR GOTO ErrHandler
OPEN "COM1:9600,N,8,1,BIN" FOR INPUT AS #1

COM(1) ON ' Turn on COM event processing.
ON COM(1) GOSUB Com1Handler' Set up COM event handling.
' Wait for a COM event to occur or a key to be pressed.
DO : LOOP WHILE INKEY$ = ""
COM(1) OFF' Turn off COM event handling.
CLS
END

Com1Handler:
    PRINT A$; "Something was typed on the terminal attached to COM1."
    RETURN

ErrHandler:
    SELECT CASE ERR
        CASE 68: PRINT "COM1 is unavailable on this computer.": END
        CASE ELSE: END
    END SELECT




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


Action

Returns the command line used to invoke the program.


Syntax

    COMMAND$


Remarks

The  COMMAND$ function returns the complete command line entered after your
BASIC program name, including optional parameters.  COMMAND$ removes all
leading blanks from the command line and converts all letters to uppercase
(capital letters).

The  COMMAND$ function can be used in stand-alone executable files or, if
you are executing from the QBX environment, by using the /CMD command-line
option, or by selecting Modify COMMAND$ on the Run menu.


Examples

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

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

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

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

' SUB procedure to get command line and split into arguments.
' Parameters:  NumArgs : Number of command-line args found.
'              Args$() : Array in which to return arguments.
'              MaxArgs : Maximum number of arguments array can return.
SUB Comline(NumArgs,Args$,MaxArgs) STATIC
CONST TRUE=-1, FALSE=0
NumArgs=0 : In=FALSE
Cl$=COMMAND$' Get the command line using the COMMAND$ function.
L=LEN(Cl$)' Go through the command line a character at a time.
FOR I=1 TO L
C$=MID$(Cl$,I,1)
' Test for character being a blank or a tab.
IF (C$<>" " AND C$<>CHR$(9)) THEN' Neither blank nor tab.
' Test to see if you're already inside an argument.
IF NOT In THEN' You've found the start of a new argument.
' Test for too many arguments.
IF NumArgs=MaxArgs THEN EXIT FOR
NumArgs=NumArgs+1
In=TRUE
END IF
' Add the character to the current argument.
Args$(NumArgs)=Args$(NumArgs)+C$
ELSE' Found a blank or a tab.
' Set "Not in an argument" flag to FALSE.
In=FALSE
END IF
NEXT I
END SUB


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

arg one  two   three    four     five      six


Output

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




COMMITTRANS Statement
────────────────────────────────────────────────────────────────────────────


Action

Commits all ISAM database operations since the most recent  BEGINTRANS
statement.


Syntax

    COMMITTRANS


Remarks

    COMMITTRANS commits a pending transaction (a series of ISAM database
operations).

Transactions are a way to group a series of operations so that you can
commit them as a whole, rescind them all, or rescind operations since a
designated savepoint. Use  BEGINTRANS to indicate the beginning of a
transaction. Use Savepoint to designate a savepoint. Use  ROLLBACK and
ROLLBACK  ALL to rescind all or part of a transaction's operations.

If you attempt to use  COMMITTRANS when there is no transaction pending,
BASIC generates the error message Illegal function call.

    COMMITTRANS commits only ISAM operations. It does not affect other BASIC
variables or file types.

Any ISAM operation that closes a table causes transactions to be committed.
For example, if a type mismatch occurs while you are opening an ISAM table,
the table is closed and a pending transaction is committed.

You may wish to code your programs so they first open all tables, then
perform all transactions, then close tables. Make sure any operation that
can close a table occurs outside a transaction.


See Also

    BEGINTRANS, checkpoint,  ROLLBACK,  SAVEPOINT


Example

See the  BEGINTRANS statement programming example, which uses the
COMMITTRANS statement.


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


Action

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


Syntax

    COMMON «SHARED»«/blockname/» variablelist


Remarks

The following list describes the parts of the  COMMON statement:

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

    blockname                              A valid BASIC identifier (up to 40
                                        characters) that identifies a
                                        group of variables. Use  blockname
                                        to share only specific groups of
                                        variables. You cannot use a
                                        type-declaration character ( %,  &,
                                            !,  #,  @, or  $) in the
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                            !,  #,  @, or  $) in the
                                        identifier.

                                        When  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" later in this entry.

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

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




The syntax of  variablelist is:

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

The following list describes the parts of  variablelist:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    variable                               Any valid BASIC variable name. It
                                        is either an array name followed
                                        by ( ), or a variable name.

    AS  type                               Declares the type of the variable.
                                        The type may be  INTEGER,  LONG,
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        The type may be  INTEGER,  LONG,
                                        SINGLE,  DOUBLE,  STRING (for
                                        variable-length strings),  STRING
                                        * length (for fixed-length
                                        strings),  CURRENCY, 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 BASIC 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                       OPTION BASE
CONST                        REM
DATA                         SHARED
DECLARE                      STATIC
DEFtype                      TYPE...END TYPE
DIM (for static arrays)      All metacommands

Variables in  COMMON blocks are matched by
position and type, not by name. Therefore, 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. The dimensions for a static array must be set with
integer-constant subscripts in a  DIM statement preceding the  COMMON
statement. The dimensions for a dynamic array must be set 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. For more
information about static and dynamic arrays, see Appendix B, "Data Types,
Constants, Variables, and Arrays" in the  Programmer's Guide.

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


The following program fragments show 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

The next sections discuss using named  COMMON blocks 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 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  SUB
procedures. The  SUB procedure Volume needs to share only the variables
representing the lengths of the sides (in  COMMON block Sides). The  SUB
procedure 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

' SUB procedure Volume in a separate module.
DIM S(3)
COMMON SHARED /Sides/ S()

SUB Volume STATIC
Vol=S(1)*S(2)*S(3)
.
.
.
END SUB

' SUB procedure 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 discarded. 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 a  COMMON block 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

When you compile a program with the /O option, common variables are not
preserved across the chain. To preserve values across a chain, you must
compile without the /O option (using BC) or by selecting the EXE Requiring
BRT Module option in the Make EXE File dialog box (using QBX).


See Also

    CALL (BASIC),  CHAIN,  FUNCTION,  SUB


Example

See the  CHAIN statement programming example, which uses the  COMMON
statement.




CONST Statement


Action

Declares symbolic constants for use in place of values.


Syntax

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


Remarks

The  CONST statement uses the following arguments:

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

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




If you use a type-declaration character in the name, you can 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  DEF type 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 referred to. 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


Note

You cannot use ASCII 01 and 02 in string constants if you are going to
compile to an executable program. The compiler (BC.EXE) uses ASCII 01 and 02
internally to represent End-of-Statement and End-of-Line, respectively. You
can, however, still use 1 and 2 within the QBX environment.


Constants declared in a  SUB or  FUNCTION procedure are local to that
procedure. 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 such as the following
(any non-zero value represents "true"):

TRUE=-1

Using constants offers several advantages over using variables for constant
values:

    ■   You only need define constants once for an entire module.

    ■   Constants cannot be inadvertently changed.

    ■   In stand-alone programs, using constants produces faster and often
        smaller code than
        variables.

    ■   Constants make programs easier to modify.


Example

The following 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. The program counts
words, lines, and characters in a text file. 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 filename from the command line.
FileName$=COMMAND$
IF FileName$="" THEN
    INPUT "Enter input filename: ",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.
        InaWord=YES' Count the word and set the flag.
        Words=Words+1
    END IF
LOOP
PRINT Characters, Words, Lines
END




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


Action

Returns the cosine of an angle given in radians.


Syntax

    COS( x)


Remarks

The argument  x can be of any numeric type.

The cosine of an angle in a right triangle is the ratio between the length
of the side adjacent to the angle and the length of the hypotenuse.

    COS is calculated in single precision if  x is an integer or
single-precision value. If you use any other numeric data type,  COS is
calculated in double precision.

To convert values from degrees to radians, multiply the angle (in degrees)
times π/180
(or .0174532925199433). To convert a radian value to degrees, multiply it by
180/π (or 57.2957795130824). In both cases, π ≈ 3.141593.


See Also

    ATN,  SIN,  TAN


Example

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

CONST PI = 3.141593
SCREEN 1 : COLOR 7' Gray background.
WINDOW (-4,-6)-(8,2) ' Define window large enough for biggest spiral.
LINE (0,0)-(2.2 * PI,0),1' Draw line from origin to the right.

' Draw 10 spirals.
FOR N = 1.1 TO .1 STEP -.1
    PSET (0,0)' Plot starting point.
    FOR Angle = 0 TO 2 * PI STEP .04
        R = N * Angle' Polar equation for spiral.
        ' Convert polar coordinates to Cartesian coordinates.
        X = R * COS(Angle)
        Y = R * SIN(Angle)
        LINE -(X,Y),1' Draw line from previous point to new point.
    NEXT Angle
NEXT N




CREATEINDEX Statement
────────────────────────────────────────────────────────────────────────────


Action

Creates an index consisting of one or more columns of an ISAM table.


Syntax

    CREATEINDEX «#»filenumber%, indexname$, unique%, columnname$«,
columnname$»...


Remarks

The  CREATEINDEX statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the table.

    indexname$                             The  indexname$ is the name of the
                                        index until the index is
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        index until the index is
                                        explicitly deleted. It follows the
                                        ISAM naming conventions (details
                                        are provided later in this entry).

    unique%                                A non-zero value for  unique%
                                        indicates the index is
                                        unique--no two indexed values
                                        can be the same. A value of zero
                                        for  unique% means the indexed
                                        values need not be unique.

    columnname$                            Names the column or columns to be
                                        indexed. The name follows the ISAM
                                        naming conventions. If more than
                                        one column name is given,
                                        CREATEINDEX defines an index based
                                        on the combination of their values.
                                        The argument  columnname$ must
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        The argument  columnname$ must
                                        appear in the  TYPE statement used
                                        when the table was created.



When you initially open a table, the current index is the null index. The
null index  represents the order in which records were added to the file.
Once an index has been created, it can be used any number of times until it
is deleted from the database.

Use  SETINDEX to make an index the current index and impose its order on the
presentation of records in a table.


Note

Columns that are arrays, user-defined types, or strings longer than 255
characters cannot be indexed.


ISAM names use the following conventions:

    ■   They have no more than 30 characters.

    ■   They use only alphanumeric characters (A-Z, a-z, 0-9).

    ■   They begin with an alphabetic character.

    ■   They include no BASIC special characters.


See Also

    DELETEINDEX,  GETINDEX$,  SETINDEX


Example

This example uses the  CREATEINDEX,  SETINDEX and  DELETEINDEX statements to
index an ISAM file in several ways. It displays records from the file using
the  GETINDEX$ and  BOF functions and the  MOVEFIRST,  MOVELAST,  MOVENEXT,
and  MOVEPREVIOUS statements.

The program uses a file called BOOKS.MDB, the sample ISAM file that SETUP
copies to your disk.

DEFINT A-Z
TYPE BookRec
    IDNum AS DOUBLE             ' Unique ID number for each book.
    Title AS STRING * 50        ' Book's title.
    Publisher AS STRING * 50    ' Book's publisher.
    Author AS STRING * 36       ' Book's author.
    Price AS CURRENCY           ' Book's price.
END TYPE

DIM Library AS BookRec          ' Record structure variable.
DIM msgtxt AS STRING

CONST Database = "BOOKS.MDB"    ' Name of the disk file.
CONST TableName = "BooksStock"  ' Name of the table.
tablenum = FREEFILE             ' File number.

OPEN Database FOR ISAM BookRec TableName AS tablenum
CREATEINDEX tablenum, "A", 0, "Author"
CREATEINDEX tablenum, "I", 1, "IDnum"
CREATEINDEX tablenum, "T", 0, "Title"
CREATEINDEX tablenum, "C", 0, "Price"

' Display static instructions.
CLS : LOCATE 13, 30
PRINT "Choose a key:"
PRINT SPC(9); "Move to:"; TAB(49); "Order by: X"
PRINT : PRINT SPC(9); "F - First record"; TAB(49); "A - Author"
PRINT : PRINT SPC(9); "L - Last record"; TAB(49); "I - ID Number"
PRINT : PRINT SPC(9); "N - Next record"; TAB(49); "T - Title"
PRINT : PRINT SPC(9); "P - Previous record"; TAB(49); "C - Cost"
PRINT : PRINT SPC(9); "Q - Quit"; TAB(49); "X - No order"
LOCATE 3, 1: PRINT TAB(37); "Books"
PRINT STRING$(80, "-");
VIEW PRINT 5 TO 10          ' Set viewport for displaying records.age.
MOVEFIRST tablenum
DO
    ' Display current record.
    CLS
    RETRIEVE tablenum, Library
    PRINT "Author:    "; Library.Author;
    PRINT TAB(49); "ID #"; Library.IDNum
    PRINT "Title:     "; Library.Title
    PRINT "Publisher: "; Library.Publisher
    PRINT "Cost:     "; Library.Price
    PRINT SPC(30); msgtxt
    PRINT STRING$(64, "-");
    IF GETINDEX$(tablenum) = "" THEN
        PRINT STRING$(15, "-");
    ELSE
        PRINT "Index in use: "; GETINDEX$(tablenum);
    END IF

    ' Get keystroke from user.
    validkeys$ = "FLNPQATICX"
    DO
        Keychoice$ = UCASE$(INKEY$)
    LOOP WHILE INSTR(validkeys$, Keychoice$) = 0 OR Keychoice$ = ""
    msgtxt = ""

    ' Move to appropriate record, or change indexes.
    SELECT CASE Keychoice$
    CASE "F"
        MOVEFIRST tablenum
    CASE "L"
        MOVELAST tablenum
    CASE "N"
        MOVENEXT tablenum
        IF EOF(tablenum) THEN
            MOVELAST tablenum
            BEEP: msgtxt = "** At last record **"
        END IF
    CASE "P"
        MOVEPREVIOUS tablenum
        IF BOF(tablenum) THEN
            MOVEFIRST tablenum
            BEEP: msgtxt = "** At first record **"
        END IF
    CASE "Q"
        EXIT DO
    CASE ELSE           'User chose an index.
        VIEW PRINT
        LOCATE 13, 59: PRINT Keychoice$;
        VIEW PRINT 5 TO 10
        IF Keychoice$ = "X" THEN Keychoice$ = ""
        SETINDEX tablenum, Keychoice$
        MOVEFIRST tablenum
    END SELECT
LOOP

' User wants to quit, so reset viewport, delete indexes and close files.
VIEW PRINT
DELETEINDEX tablenum, "A"
DELETEINDEX tablenum, "I"
DELETEINDEX tablenum, "T"
DELETEINDEX tablenum, "C"
CLOSE
END




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


Action

Converts a numeric expression to a single-precision value.


Syntax

    CSNG( numeric-expression)


Remarks

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

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


See Also

    CCUR,  CDBL,  CINT,  CLNG


Example

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

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


Output

975.3421115  975.3421  975.3421555  975.3422




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


Action

Returns the current line (row) position of the cursor.


Syntax

    CSRLIN


Remarks

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


See Also

    LOCATE,  POS


Example

The following example uses a  SUB procedure that prints a message on the
screen without disturbing the current cursor position:

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

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




CURDIR$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the path currently in use for the specified drive.


Syntax

    CURDIR$«( drive$)»


Remarks

The argument  drive$ is a string expression that specifies a drive.

The argument  drive$ must be in the range A to  lastdrive, where  lastdrive
is  the maximum drive letter you set in your CONFIG.SYS file.

If no drive is specified or if  drive$ is a null string,  CURDIR$ returns
the path for the currently selected drive. This is similar to using the
CHDIR command at the system prompt without specifying a path.

BASIC generates an error if the first character in  drive$ lies outside the
range A to  lastdrive, unless you are working in a networked environment.
BASIC also generates an error if the first character in  drive$ corresponds
to a drive that does not exist, or if the first character of  drive$ is not
a letter.

    CURDIR$ is not case sensitive. "C" is the same as "c."


See Also

    CHDIR,  CHDRIVE,  DIR$


Example

See the example for the  CHDRIVE statement, which uses the  CURDIR$
function.




CVI, CVL, CVS, CVD, and CVC Functions
────────────────────────────────────────────────────────────────────────────


Action

Converts strings containing numeric values to numbers.


Syntax

    CVI( 2-byte-string)

    CVL( 4-byte-string)

    CVS( 4-byte-string)

    CVD( 8-byte-string)

    CVC( 8-byte-string)


Remarks

    CVI,  CVL,  CVS,  CVD, and  CVC are used with a  FIELD statement to read
numbers from a random-access file. These 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$,  MKL$,  MKS$,  MKD$,
and  MKC$.

The following table describes these string conversion functions:

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

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





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


Action

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


Syntax

    DATA  constant«,  constant»...


Remarks

The  constant arguments can be any valid numeric or string constant.


Note

You cannot use ASCII 01 and 02 in data strings if you are going to compile
to an executable program. The compiler (BC.EXE) uses ASCII 01 and 02
internally to represent End-of-Statement and End-of-Line respectively. You
can, however, still use 1 and 2 within the QBX environment.


Names of symbolic constants (defined in a  CONST statement) that appear in
DATA statements are interpreted as strings, rather than as 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 can contain as many constants as will fit on a line. The
constants are separated by commas. You can use any number of  DATA
statements.


Note

If a string constant contains commas, colons, or leading or trailing spaces,
enclose the string in double quotation marks.


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

DATA 1,2,,4,5

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

When working in the QBX environment,  DATA statements can be entered only in
the module-level code. BASIC moves all  DATA statements not in the
module-level code to the module-level code when it reads a source file.
READ 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 can reread  DATA statements by using the  RESTORE statement.

    REM statements that appear at the end of  DATA statements must be preceded
by a colon. Without a colon, BASIC interprets trailing  REM statements as
string data.


See Also

    READ,  RESTORE


Examples

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

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

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

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



Output

Today is September 21, 1989

The following example shows how null data items are handled:

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


Output

abc                     def
1           0           2




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


Action

Returns a string containing the current date.


Syntax

    DATE$


Remarks

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


See Also

    DATE$ Statement


Example

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

PRINT DATE$



Output

04-21-1989




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


Action

Sets the current date in your computer's system.


Syntax

    DATE$ =  stringexpression$


Remarks

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

If you use the  DATE$ statement to set the date, the change remains in
effect until you change it again or reboot your computer.

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

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


See Also

    DATE$ Function , TIME$ Statement


Example

The following example prompts you to supply the month, date, and year, then
resets the system date on your computer. Note that if you change the system
date, any files you create or revise will be stamped with the new date.

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




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


Action

Declares references to BASIC procedures and invokes argument type checking.


Syntax

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


Remarks

The  DECLARE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    name                                   The name that will be used to
                                        invoke the procedure. The argument
                                            name is limited to 40 characters.
                                            FUNCTION procedure names can end
                                        in one of the type-declaration
                                        characters ( %,  &,  !,  #,  @, %
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        characters ( %,  &,  !,  #,  @, %
                                        or  $) to indicate the type
                                        of value returned.

    parameterlist                          A list of parameters that
                                        indicates the number and type of
                                        arguments to be used to call 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
procedure defined in another module. For more information about invoking
procedures without the  CALL keyword,  see Chapter 2, "SUB and FUNCTION
Procedures" in the  Programmer's Guide.

A  DECLARE statement also causes the compiler to check the number and type
of arguments used to invoke the procedure. QBX 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 procedure) and affects the entire module.

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

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

The argument  variable is any
valid BASIC variable name. If the variable is an array, it can be followed
by the number of dimensions in parentheses, as in this fragment:

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,  CURRENCY,  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 also can 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:

DECLARE SUB First

You can omit the parentheses only if the  SUB or  FUNCTION procedure is
separately compiled. No argument checking is done.

DECLARE SUB First ()

First has no parameters. If you use arguments in a call to First, BASIC
generates an error. An empty parameter list indicates that the  SUB or
FUNCTION procedure has no parameters and that argument checking should be
done.

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

DECLARE also can be used to declare references to
procedures written in other programming languages, such as C. See the entry
for the  DECLARE statement (Non-BASIC).


See Also

    CALL (BASIC),  DECLARE (Non-BASIC),  FUNCTION,  SUB


Example


In this program, use of the  DECLARE statement allows a  SUB procedure to be
invoked without using the  CALL keyword:

' Generate 20 random numbers, store them in an array, and sort.
DECLARE SUB Sort (A() AS INTEGER, N AS INTEGER)
DIM Array1(1 TO 20) AS INTEGER
DIM I AS INTEGER
' Generate 20 random numbers.
RANDOMIZE TIMER

CLS
FOR I% = 1 TO 20
    Array1(I%) = INT(RND * 100)
NEXT I%

' Sort the array, calling Sort without the CALL keyword.
' Notice the absence of parentheses around the arguments in
' the call to Sort.
Sort Array1(), 20

' Print the sorted array.
FOR I% = 1 TO 20
    PRINT Array1(I%)
NEXT I%
END

' Sort subroutine.
SUB Sort (A%(), N%)
    FOR I% = 1 TO N% - 1
        FOR J% = I% + 1 TO N%
            IF A%(I%) > A%(J%) THEN SWAP A%(I%), A%(J%)
        NEXT J%
    NEXT I%
END SUB




DECLARE Statement (Non-BASIC Procedures)
────────────────────────────────────────────────────────────────────────────


Action

Declares calling sequences for external procedures written in other
languages.


Syntax

    DECLARE FUNCTION name «CDECL» «ALIAS "aliasname"» «(«parameterlist»)»

    DECLARE SUB name «CDECL» «ALIAS "aliasname"» «(«parameterlist»)»


Remarks

The following list describes the parts of the  DECLARE statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    FUNCTION                               Indicates that the external
                                        procedure returns a value and can
                                        be used in an expression.

    SUB                                    Indicates that the external
                                        procedure is invoked in the same
                                        way as a BASIC  SUB procedure.

    name                                   The name used in the BASIC program
                                        to invoke the procedure. Names can
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        to invoke the procedure. Names can
                                        have up to 40 characters.
                                        FUNCTION procedure names can
                                        include an explicit type character
                                        ( %,  &,  !,  #,  @, or  $)
                                        indicating the type of value the
                                        procedure returns.

    CDECL                                  Indicates that the procedure uses
                                        the C-language argument order and
                                        naming conventions.  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 statement,
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        clause in the  DECLARE statement,
                                        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
                                        ALIAS,  aliasname is used as is.

    ALIAS                                  Indicates that the procedure being
                                        called has another name in the
                                        .OBJ or library file..

    aliasname                              The name the procedure has in the
                                        file or library.

    parameterlist                          The parameters to be passed to the
                                        invoked procedure.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        invoked procedure.



The argument parameterlist has the following syntax:

«{BYVAL|SEG}» variable «AS type» «, «{BYVAL|SEG}» variable «AS type»»...


The following list describes the parts of  parameterlist:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    BYVAL                                  Indicates the parameter is passed
                                        by value, not reference. Reference
                                        is the default.  BYVAL can be used
                                        only with  INTEGER,  LONG,  SINGLE,
                                            DOUBLE, and  CURRENCY types.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                            DOUBLE, and  CURRENCY types.

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

    variable                               A valid BASIC variable name. Only
                                        the variable's type is significant.
                                        If the variable is an array, it
                                        can be followed by the number of
                                        dimensions in parentheses (to
                                        maintain compatibility with older
                                        versions of BASIC). For example:
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        versions of BASIC). For example:

                                        DECLARE SUB EigenValue (A(2) AS
                                        DOUBLE)

    AS type                                Indicates the variable's type. The
                                        argument  type can be  INTEGER,
                                        LONG,  SINGLE,  DOUBLE,  STRING,
                                        CURRENCY,  ANY, or a user-defined
                                        type. You also can 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
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        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.




When neither  BYVAL nor  SEG is used, arguments are passed as near addresses
(offsets).

This form of the  DECLARE statement lets you refer to 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, as described in the following declarations:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
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. If you use
                                        arguments in a call to First, BASIC
                                        generates an error. Empty
                                        parentheses indicate that the  SUB
                                        or  FUNCTION procedure has no
                                        parameters and that argument
                                        checking should be done.

DECLARE SUB First CDECL (X AS LONG)   First takes one long-integer
                                        argument. When a parameter list
                                        appears, the number and type of
                                        arguments are checked each
                                        invocation.
Declaration                           Meaning
────────────────────────────────────────────────────────────────────────────
                                        invocation.



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


See Also

    CALL,  CALLS Statements  (Non-BASIC);  DECLARE (BASIC)


Example

The following example shows a BASIC program that calls a short C function.
The C program is compiled separately and stored in a Quick library or
explicitly linked to form the .EXE file.

DEFINT A-Z
DECLARE FUNCTION addone CDECL (BYVAL n AS INTEGER)
INPUT x
y = addone(x)
PRINT "x and y are "; x; y
END


The following function uses C argument passing and takes a single integer
argument passed by value.

/* C function addone. Returns one more than its integer argument. */
int far addone(int n)
{
    return(n+1);
}




DEF FN Statement
────────────────────────────────────────────────────────────────────────────


Action

Defines and names a function.


Syntax 1

    DEF FNname«(parameterlist)» = expression


Syntax 2

    DEF FNname«(parameterlist)»
    « statementblock»
        FNname =  expression
    « statementblock»
    « EXIT DEF»
    « statementblock»
    END DEF


Remarks

The  DEF FN statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    name                                   A legal variable name, which is
                                        always prefixed with  FN (for
                                        example: FNShort). The name
                                        (including the  FN prefix) can be
                                        up to 40 characters long and 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:

Argument                                Description
────────────────────────────────────────────────────────────────────────────

                                        FNString$
                                        FNString%
                                        FNString#

                                        To return a value from a function
                                        defined by  DEF FN, 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.
                                        Functions defined by  DEF FN do
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        Functions defined by  DEF FN do
                                        not accept arrays, records, or
                                        fixed-length strings as arguments.

    expression                             In both versions of syntax,
                                        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 0 for a numeric  DEF
                                        FN function, and the null string
                                        ("") for a string  DEF FN function.



The argument  parameterlist has the following syntax:

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

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               Any valid BASIC variable name.

    AS  type                               The argument  type is  INTEGER,
                                        LONG,  SINGLE,  DOUBLE,  CURRENCY,
                                        or  STRING. You also can 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 statement. For more information, see the  FUNCTION entry in this book and
Chapter 2, "SUB and FUNCTION Procedures" in the  Programmer's Guide.


    DEF FN must define a function before the function is used. If you call a
DEF FN function before it is defined, BASIC generates the error message
Function not defined.  DEF FN function definitions cannot appear inside
other  DEF FN definitions. In addition, functions defined by  DEF  FN cannot
be recursive.


The  EXIT DEF statement causes an immediate exit from the executing  DEF FN
function. Program execution continues where the  DEF FN function was
invoked.

    DEF FN functions can be used only in the module in which they are defined.

A function defined by  DEF FN can share variables with the module-level
code. Variables not in  parameterlist are global--their values are
shared with the module-level code. 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. If you assign a numeric value to a string function
name or assign a string value to a numeric function name, BASIC generates
the error message Type mismatch.

If the function is numeric,  DEF FN name returns a value with the precision
specified by  name. For example, if  name specifies a double-precision
variable, then the value returned by  DEF FN name is double precision,
regardless of the precision of  expression.


Because BASIC may
rearrange arithmetic expressions for greater efficiency, avoid using
functions defined by  DEF FN that change program variables in expressions
that may be reordered. The following example may give unpredictable 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 usually can avoid this problem
by isolating the  DEF FN function call:

I = 1 : X = FNShort : PRINT X + I + I

Embedding I/O operations in  DEF FN-defined  functions used in I/O
statements, or embedding graphics operations in  DEF FN-defined functions in
graphics statements, may cause similar problems.


See Also

    FUNCTION,  STATIC


Example

The following program uses a function defined by  DEF  FN to calculate the
factorial of a number (for example, the factorial of 3 is 3 times 2 times
1):

DEF FNFactorial# (X%)
    STATIC Tmp#, I%
    Tmp# = 1
    FOR I% = 2 TO X%
        Tmp# = Tmp# * I%
    NEXT I%
    FNFactorial# = Tmp#
END DEF

INPUT "Enter an integer: ", Num%
PRINT : PRINT Num%; "factorial is"; FNFactorial#(Num%)




DEFtype Statements
────────────────────────────────────────────────────────────────────────────


Action

Set the default data type for variables,  DEF FN functions, and  FUNCTION
procedures.


Syntax

    DEFINT  letterrange «,  letterrange»...
    DEFLNG  letterrange«,  letterrange»...
    DEFSNG  letterrange«,  letterrange»...
    DEFDBL  letterrange«,  letterrange»...
    DEFCUR  letterrange«,  letterrange»...
    DEFSTR  letterrange «,  letterrange»...


Remarks

The  letterrange argument has the form:

    letter1 «- letter2»

The arguments  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), currency ( CUR), 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. These three
statements are equivalent:

DEFINT I-N
DEFINT i-n
DEFINT i-N

A type-declaration character ( %,  &,  !,  #,  @, or  $) always takes
precedence over a  DEF type statement.  DEF type statements do not affect
record elements.


Note

I%, I&, I!, I#, I@, and I$ all are distinct variables, and each may hold a
different value.


BASICA

BASICA handles default data types differently. BASICA scans each statement
before executing it. If the statement contains a variable without an
explicit type (indicated by  %,  &,  !,  #,  @, or  $), the interpreter uses
the current default type.

In contrast, BASIC scans the text once only and after a variable appears in
a program line, its type cannot be changed.


Example

See the  ABS function programming example, which uses the  DEFDBL statement.




DEF SEG Statement
────────────────────────────────────────────────────────────────────────────


Action

Sets the current segment address for a subsequent  PEEK function,  BLOAD,
BSAVE,  Absolute routine, or  POKE statement.


Syntax

    DEF SEG «= address»


Remarks

For  Absolute,  BLOAD,  BSAVE,  PEEK, and  POKE,  address is used as the
segment. The argument  address is a numeric expression with an unsigned
integer value between 0 and 65,535, inclusive. If you use a value outside
this range, BASIC generates the error message Illegal function call. The
previous segment is retained if an error occurs. If  address is omitted,
DGROUP is used.

    DEF SEG remains in effect until changed. To reset the current segment to
the default data segment (DGROUP), use  DEF SEG without any argument.

Be sure to separate  DEF and  SEG with a space. Otherwise, BASIC interprets
the statement to mean "assign a value to the variable DEFSEG."

To set the current segment address to the address of data stored in far
memory, you can use  DEF SEG with the  SSEG or  VARSEG functions ( SSEG
returns the current segment address of a string;  VARSEG returns the current
segment address of numeric data). For example, this statement sets the
current address for a far string named a$ :

DEF SEG = SSEG(a$)

When using  DEF SEG in OS/2 protected mode, any  DEF SEG statement must
refer only to a valid selector. The  DEF SEG statement itself does not
generate any memory references using the selector, nor does it attempt to
validate the selector. If a misdirected  DEF SEG statement causes your
program to refer to an illegal memory address, the operating system may
generate a protection exception, or BASIC may generate the error message
Permission denied. The default  DEF SEG segment always constitutes a valid
memory reference. Use caution when altering this reference in protected
mode.

DEF SEG and Expanded Memory Arrays
Do not use  DEF  SEG to set the segment of
an expanded memory array. If you start QBX with the /Ea switch, any of these
arrays may be stored in expanded memory:

    ■         Numeric arrays less than 16K in size.

    ■         Fixed-length string arrays less than 16K in size.

    ■         User-defined-type arrays less than 16K in size.

If you want to use  DEF  SEG to set the segment of an array, first start QBX
without the /Ea switch. (Without the /Ea switch, no arrays are stored in
expanded memory.)

For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.


BASICA

In this version of BASIC, the  CALL and  CALLS statements do not use the
segment address set by  DEF SEG.


See Also

    SADD;  SSEG;  VARPTR,  VARSEG


Example

The following example uses  DEF  SEG,  PEEK, and  POKE to turn the Caps Lock
key on and off.

This program contains hardware-specific instructions. It works correctly on
IBM PC, XT, and AT computers.

DECLARE SUB CapsOn ()
DECLARE SUB CapsOff ()
DECLARE SUB PrntMsg (R%, C%, M$)
CLS
CapsOn
PrntMsg 24, 1, "<Caps Lock On>"
LOCATE 12, 10
LINE INPUT "Enter a string (all characters are caps): ", S$
CapsOff
PrntMsg 24, 1, "              "
PrntMsg 25, 1, "Press any key to continue..."
DO WHILE INKEY$ = "": LOOP
CLS
END

SUB CapsOff STATIC' Turn the Caps Lock key off.
    DEF SEG = 0' Set segment to low memory.
        POKE &H417, PEEK(&H417) AND &HBF' Turn off bit 6 of &H0417.
    DEF SEG ' Restore segment.
END SUB

SUB CapsOn STATIC' Turn Caps Lock on.
    DEF SEG = 0' Set segment to low memory.
        POKE &H417, PEEK(&H417) OR &H40' Turn on bit 6 of &H0417.
    DEF SEG ' Restore segment.
END SUB

SUB PrntMsg (Row%, Col%, Message$) STATIC
' Print message at Row%, Col% without changing cursor.
    CurRow% = CSRLIN: CurCol% = POS(0)' Save cursor position.
    LOCATE Row%, Col%: PRINT Message$;
    ' Restore cursor.
    LOCATE CurRow%, CurCol%
END SUB




DELETE Statement
────────────────────────────────────────────────────────────────────────────


Action

Removes the current record from an ISAM table.


Syntax

    DELETE «#»  filenumber%


Remarks

The argument  filenumber% is the number used in the  OPEN statement to open
the table.

If the record you delete is the last record according to the table's current
index, the current position is at the end of the table and there is no
current record. When you delete any other record in the table, the record
following the deleted record becomes current.  The record preceding the
deleted record remains the previous record.


See Also

    DELETEINDEX, DELETETABLE,  INSERT


Example

See the  BEGINTRANS statement programming example, which uses the  DELETE
statement.




DELETEINDEX Statement
────────────────────────────────────────────────────────────────────────────


Action

Permanently removes an index from an ISAM database.


Syntax

    DELETEINDEX «#»  filenumber%,  indexname$


Remarks

The  DELETEINDEX statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number of the open ISAM table
                                        that was used in the  OPEN
                                        statement.

    indexname$                             The name used in the  CREATEINDEX
                                        statement to create the index.




See Also

    CREATEINDEX,  GETINDEX$, SETINDEX


Example

See the  CREATEINDEX statement programming example, which uses the
DELETEINDEX statement.




DELETETABLE Statement
────────────────────────────────────────────────────────────────────────────


Action

Removes a table and deletes any indexes based on the table from an ISAM
database.


Syntax

    DELETETABLE  database$,  tablename$


Remarks

The  DELETETABLE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    database$                              A database filename or path. The
                                        argument  database$ specifies an
                                        optional device, followed by a
                                        filename or path conforming to the
                                        DOS naming conventions. The
                                        database$ specification must be
                                        the name of an ISAM file.

    tablename$                             The name used in the  OPEN
                                        statement to open the table.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        statement to open the table.



If the specified file is not an ISAM database file, BASIC generates the
error message Bad file mode.


Warning

Use  DELETETABLE with caution.  DELETETABLE  permanently removes the
specified table from the database.


See Also

    CLOSE,  DELETE,  DELETEINDEX,  OPEN


Example

See the programming example for the  SEEKGT,  SEEKGE, and  SEEKEQ
statements, which uses the  DELETETABLE statement.




DIM Statement
────────────────────────────────────────────────────────────────────────────


Action

Declares a variable and allocates storage space.


Syntax

    DIM «SHARED» variable«(subscripts)» «AS type» «, variable«(subscripts)» «AS
type»»...


Remarks

The following list describes the parts of the  DIM statement:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    SHARED                                 The optional  SHARED attribute
                                        allows all procedures in a module
                                        to share arrays and simple
                                        variables. This differs from the
                                        SHARED statement, which affects
                                        only variables within a single
                                        SUB or  FUNCTION procedure.

    variable                               A BASIC variable name.

    subscripts                             The dimensions of the array.
                                        Multiple dimensions can be
                                        declared. The subscript syntax is
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        declared. The subscript syntax is
                                        described below.

    AS  type                               Declares the type of the variable.
                                        The type may be  INTEGER,  LONG,
                                        SINGLE,  DOUBLE,  STRING (for
                                        variable-length strings),  STRING
                                        *  length (for fixed-length
                                        strings),  CURRENCY, or a
                                        user-defined type.


The argument  subscript in the  DIM statement has 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)

Subscripts can be negative.  TO can be used to specify any range of
subscripts between -32,768 and 32,767, inclusive:

DIM A(-4 TO 10)
DIM B(-99 TO -5,-3 TO 0)

If you use an implicitly dimensioned array (that is, any array that has not
been declared with the  DIM statement), the maximum value of each subscript
in the array is 10. If you use a subscript that is greater than the
specified maximum and if run-time error checking is in effect, BASIC
generates the error message Subscript out of range.


Note

Run-time error checking is in effect when:

    ■   You run a program from the QBX environment.

    ■   You have created an .EXE file in the QBX environment and you have
        selected the Run-Time Error Checking option in the Make EXE File
        dialog box.

    ■   You have compiled your program with BC using the /D option to select
        run-time error checking.


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 declare a dimension for an array variable with a  DIM
statement after you have referred to the array, BASIC generates the error
message 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):
╓┌───────────────────────────────────────────────────────────────┌───────────╖
How array is declared                                           Allocation
────────────────────────────────────────────────────────────────────────────
Declared first in a  COMMON statement                           Dynamic

Implicitly dimensioned arrays                                   Static

Dimensioned with numeric constants or CONST statement           Static
constants

Dimensioned with variables as subscripts                        Dynamic


The following list shows examples of different  DIM statements and results:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Statement                               Result
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, the array is
                                        a dynamic array and is allocated
                                        only when the program reaches the
                                        DIM statement.



For more information about static and dynamic arrays, see Appendix B, "Data
Types, Constants, Variables, and Arrays" in the  Programmer's Guide.


Note

If the array size exceeds 64K, if the array is not dynamic, and if the /AH
option was not used, BASIC may generate the error message Subscript out of
range or 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 also can 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 way to declare 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 also can declare arrays of records:

TYPE Card
Suit AS STRING * 9
Value AS INTEGER
END TYPE

DIM Deck(1 TO 52) AS Card


Note

BASIC now supports the  CURRENCY data type (type suffix  @). This can be
used in the  AS  type clause of the  DIM statement. Also, BASIC now supports
static arrays in user-defined types.


BASICA

BASICA executes a  DIM statement when it encounters the statement in the
program. The array is allocated only when the statement is executed, so all
arrays in BASICA are dynamic.


See Also

    ERASE,  OPTION  BASE,  REDIM


Example

The following example finds and prints the maximum and minimum of a set of
values:

' Declare the dimensions for an array to hold the values.
CONST MAXDIM=20
DIM A(1 TO MAXDIM)
' Use DIM to set up two integer variables. Other variables are SINGLE.
DIM NumValues AS INTEGER, I AS INTEGER

' Get the values.
NumValues=0
PRINT "Enter values one per line. Type END to end."
DO
    INPUT A$
    IF UCASE$(A$)="END" OR NumValues>=MAXDIM THEN EXIT DO
    NumValues=NumValues+1
    A(NumValues)=VAL(A$)
LOOP

' Find the maximum and minimum values.
IF NumValues>0 THEN
    Max=A(1)
    Min=A(1)
    FOR I=1 TO NumValues
        IF A(I)>Max THEN Max=A(I)
        IF A(I)<Min THEN Min=A(I)
    NEXT I
    PRINT "The maximum is ";Max;" The minimum is ";Min
ELSE
    PRINT "Too few values."
END IF


Output

Enter values one per line. Type END to end.
? 23.2
? 11.3
? 1.6
? end
The maximum is  23.2  The minimum is  1.6




DIR$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a filename that matches the specified pattern.


Syntax

    DIR$«( filespec$)»


Remarks

The argument  filespec$ is a string expression that specifies a filename or
path.

The path and filename can include a drive and DOS wildcard characters.

BASIC generates the error message Illegal function call if you don't specify
    filespec$ when you first call  DIR$.

    DIR$ returns the first filename that matches  filespec$. To retrieve
additional filenames that match the  filespec$ pattern, call  DIR$ again
with no argument. When no filenames match,  DIR$ returns a null string.

You do not have to retrieve all of the filenames that match a given
filespec$ before calling  DIR$ again with a new  filespec$.

Because filenames are retrieved in no particular order, you may want to
store filenames in a dynamic array and sort the array.

    DIR$ is not case sensitive. "C" is the same as "c."


See Also

    CURDIR$


Example

The following example demonstrates use of the  DIR$ function:

DECLARE FUNCTION GetFileCount& (filespec$)
filespec$ = "*.*"
count = GetFileCount(filespec$)
PRINT count; "files match the file specification."

' Function that returns number of files that match file specification.
FUNCTION GetFileCount& (filespec$)
DIM FileCount AS LONG
    IF LEN(DIR$(filespec$)) = 0 THEN     ' Ensure filespec$ is valid.
        FileCount& = 0
    ELSE
        FileCount = 1
        DO WHILE LEN(DIR$) > 0
            FileCount& = FileCount& + 1
        LOOP
    END IF
    GetFileCount = FileCount&
END FUNCTION




DO...LOOP Statement
────────────────────────────────────────────────────────────────────────────


Action

Repeats a block of statements while a condition is true or until a condition
becomes true.


Syntax 1

    DO «{ WHILE |  UNTIL}  condition»
    « statementblock»
    « EXIT DO»
    « statementblock»
    LOOP

Syntax 2

    DO
    « statementblock»
    « EXIT DO»
    « statementblock»
    LOOP «{ WHILE |  UNTIL}  condition»


Remarks

The argument  condition is a numeric expression that BASIC evaluates as true
(nonzero) or false (zero).

The program lines between the  DO and  LOOP statements will be repeated as
long as  condition is true.

You can use a  DO... LOOP statement instead of a  WHILE... WEND statement.
The  DO... LOOP is more versatile because it can test for a condition at the
beginning or at the end of a loop.


Examples

The following examples show how placement of the condition affects the
number of times the block of statements is executed:

' Test at the beginning of the loop. Because I is not less than 10,
' the body of the loop (the statement block) is never executed.
I = 10
PRINT "Example 1:": PRINT
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

' Test at the end of the loop, so the statement block executes
' at least once.
I = 10
PRINT : PRINT : PRINT "Example 2:": PRINT
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


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. The program
illustrates testing at the end of a loop:

CONST NOEXCH = -1' Set up a value to indicate no exchanges.
DIM Exes(12)
DIM I AS INTEGER
' Load the array and mix it up.
FOR I = 1 TO 12 STEP 2
    Exes(I) = 13 - I
    Exes(I + 1) = 0 + I
NEXT I
Limit = 12
PRINT
PRINT "This is the list of numbers to sort in ascending order:"
PRINT
FOR I = 1 TO 12
    PRINT USING " ### "; Exes(I);
NEXT I
PRINT

' In the following DO...LOOP, INKEY$ is tested at the bottom of
' the loop. When the user presses a key, INKEY$ is no longer a
' null string and the loop terminates, continuing program execution.
PRINT : PRINT "Press any key to continue."
DO
LOOP WHILE INKEY$ = ""

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:": PRINT
FOR I = 1 TO 12
    PRINT USING " ### "; Exes(I);
NEXT I
END




DRAW Statement
────────────────────────────────────────────────────────────────────────────


Action

Draws an object described by a string of drawing commands.


Syntax

    DRAW  stringexpression$


Remarks

The argument  stringexpression$ contains one or more drawing commands. The
drawing commands combine many of the capabilities of the other graphics
statements (such as  LINE and  COLOR) into a graphics macro language, as
described below.

There are three types of drawing commands:

    ■         Line-drawing and cursor-movement commands.

    ■         Rotation, color, and scale-factor commands.

    ■         The substring command.



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            Plot, but return to original position when done.


The following commands specify movement in terms of units. The default unit
size is one pixel. Unit size can be modified by the S command, which sets
the scale factor (see "Rotation, Color, and Scale-Factor Commands" later in
this entry). If no unit argument is supplied, the graphics cursor is moved
one unit.

Each of the cursor-movement commands initiate movement from the current
graphics position, which is usually the coordinate of the last graphics
point plotted with a  DRAW macro-language command or another graphics
command (such as  LINE or  PSET). The current position defaults to the
center of the screen when a program begins execution. The cursor-movement
commands have the following effects:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Command                                 Effects
────────────────────────────────────────────────────────────────────────────
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
Command                                 Effects
────────────────────────────────────────────────────────────────────────────
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 movement is
                                        to that point.

                                        If no sign precedes  x, the
                                        movement is absolute. Movement is
                                        from the current cursor position
                                        to the point with coordinates  x,
                                        y.
Command                                 Effects
────────────────────────────────────────────────────────────────────────────
                                        y.



Rotation, 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 rotation. 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 on a monitor screen with a
                                        4:3 aspect ratio.

TA  n                                   Turn an angle of  n degrees. The
Command                                 Description
────────────────────────────────────────────────────────────────────────────
TA  n                                   Turn an angle of  n degrees. The
                                        value of  n must be between  -360
                                        and 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 the drawing (foreground) color
                                        to n. See the COLOR, PALETTE,
                                        and SCREEN statements for
                                        discussion of valid colors,
                                        numbers, and attributes.

Command                                 Description
────────────────────────────────────────────────────────────────────────────

P  p,  b                                The value  p is the paint color
                                        for the figure's interior, while
                                        b is the paint color for the
                                        figure's border. See the PAINT
                                        statement for more information
                                        about painting an area with a
                                        graphic pattern.

S  n                                    Set scale factor  n, which can
                                        range from 0 to 255, inclusive.
                                        Increase or decrease length of
                                        moves. The default for n is 4,
                                        which causes no scaling. The scale
                                        factor multiplied by
                                        movement-command arguments
                                        (divided by 4) gives the actual
                                        distance moved.

Command                                 Description
────────────────────────────────────────────────────────────────────────────

X  stringexpression$                    Execute substring. This command
                                        allows you to execute a second
                                        substring from a DRAW command
                                        string. You can have one string
                                        expression execute another, which
                                        executes a third, and so on.

                                        Numeric arguments to macro
                                        commands within stringexpression$
                                        can be constants or variable names.
                                        BASIC requires the following
                                        syntax:

                                        "X" + VARPTR$(stringexpression)




BASICA

Some  DRAW statements that are allowable in BASICA programs require
modification when used with the BASIC compiler. Specifically, the compiler
requires the  VARPTR$ form for variables. One example is this
BASICA statement (in which ANGLE is a variable):

DRAW "TA = Angle"

For the BASIC compiler, you would change that to:

DRAW "TA =" + VARPTR$(Angle)

The compiler does not support the BASICA X  stringexpression$ command.
However, you can 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 QBX environment.

DRAW "X" + VARPTR$(A$)
DRAW "XA$"


See Also

    PALETTE,  SCREEN Statement,  VARPTR$


Examples

The first example draws the outline of a triangle in magenta and paints the
interior cyan:

SCREEN 1
DRAW "C2"             ' Set color to magenta.
DRAW "F60 L120 E60"   ' Draw a triangle.
DRAW "BD30"           ' Move down into the triangle.
DRAW "P1,2"           ' Paint interior.

The next example shows how to use the M macro command with absolute and
relative movement, and 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"

This program draws a clock on the screen using the  TIME$ unction:

@AS@%' Declare procedure.
DECLARE SUB Face (Min$)

' Select 640 x 200 pixel high-resolution graphics screen.
SCREEN 2
DO
    CLS
    Min$ = MID$(TIME$, 4, 2)' Get string containing minutes value.
    Face Min$' Draw clock face.
    ' Wait until minute changes or a key is pressed.
    DO
        ' Print time at top of screen.
        LOCATE 2, 37
        PRINT TIME$
        Test$ = INKEY$' Test for a key press.
    LOOP WHILE Min$ = MID$(TIME$, 4, 2) AND Test$ = ""
LOOP WHILE Test$ = ""' End program when a key is pressed.
END

SUB Face (Min$) STATIC' Draw the clock face.
    LOCATE 23, 30
    PRINT "Press any key to end"
    CIRCLE (320, 100), 175
    ' Convert strings to numbers.
    Hr = VAL(TIME$)
    Min = VAL(Min$)
    ' Convert numbers to angles.
    Little = 360 - (30 * Hr + Min / 2)
    Big = 360 - (6 * Min)
    ' Draw the hands.
    DRAW "TA=" + VARPTR$(Little) + "NU40"
    DRAW "TA=" + VARPTR$(Big) + "NU70"
END SUB




END Statement
────────────────────────────────────────────────────────────────────────────


Action

Stops a BASIC program, procedure, or block.


Syntax 1

    END «{ DEF |  FUNCTION |  IF |  SELECT |  SUB |  TYPE}»

Syntax 2

    END « n%»


Remarks

There are a number of ways to use the  END statement, as described in the
following list:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Statement                               Description
────────────────────────────────────────────────────────────────────────────
    END  DEF                               Ends a multiline  DEF FN function
                                        definition. You must use  END  DEF
                                        with a multiline  DEF FN.

    END  FUNCTION                          Ends a  FUNCTION procedure
                                        definition. You must use  END
                                        FUNCTION with  FUNCTION.

    END  IF                                Ends a block  IF... THEN... ELSE
                                        statement. You must use  END  IF
                                        with block  IF... THEN... ELSE.

    END  SELECT                            Ends a  SELECT CASE block. You
Statement                               Description
────────────────────────────────────────────────────────────────────────────
    END  SELECT                            Ends a  SELECT CASE block. You
                                        must use  END  SELECT with a
                                        SELECT CASE statement.

    END  SUB                               Ends a BASIC  SUB procedure. You
                                        must use  END  SUB with  SUB.

    END  TYPE                              Ends a user-defined type
                                        definition ( TYPE statement). You
                                        must use  END  TYPE with  TYPE.

    n%                                     Ends a program and returns the
                                        value  n% to the operating system
                                        (if  n% is omitted, the value of
                                        n% is set to 0).  END is not
                                        required at the end of a program.
                                        In Syntax 2,  n% accepts a range
                                        of integers from -32768 through
                                        32767, inclusive.
Statement                               Description
────────────────────────────────────────────────────────────────────────────
                                        32767, inclusive.

                                        The value  n% can be used by DOS
                                        or OS/2 batch files or by
                                        non-BASIC programs. Untrapped
                                        errors and fatal errors set the
                                        value of  n% to -1.



By itself, the  END statement stops program execution and closes all files.
In a stand-alone program,  END returns control to the operating system. In
the QBX environment,  END returns to that environment. You can place an  END
statement anywhere in the program to terminate execution.


See Also

    DEF  FN,  FUNCTION,  IF... THEN... ELSE,  SELECT CASE,  STOP,  SUB,
SYSTEM,  TYPE


Example

See the on error statement programming example, which uses the  END
statement.




ENVIRON$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns an environment string from the DOS or OS/2 environment-string table.


Syntax 1

    ENVIRON$ ( environmentstring$)

Syntax 2

    ENVIRON$ ( n%)


Remarks

The  ENVIRON$ function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    environmentstring$                     A string constant or variable that
                                        contains the name of an
                                        environment variable. The name of
                                        the environment variable must be
                                        uppercase. For example, ENVIRON$
                                        ("PATH") returns the path
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        ("PATH") returns the path
                                        environment variable; ENVIRON$
                                        ("path") returns a null string.

    n%                                     a numeric expression that
                                        indicates that the  nth string
                                        from the environment string table
                                        should be returned.



If you specify an environment-string name, but it cannot be found in the envi

Otherwise,  ENVIRON$ returns the text following the equal sign in the environ

If you specify a numeric argument ( n%), the  nth string in the environment-s

In this case, the string includes all of the text, including  environmentstri

If the  nth string does not exist,  ENVIRON$ returns a null string. The argum


See Also

    ENVIRON Statement


Example

See the ENVIRON statement programming example, which uses the
ENVIRON$ function.




ENVIRON Statement
────────────────────────────────────────────────────────────────────────────


Action

Modifies or adds a parameter in the DOS or OS/2 environment-string table.


Syntax

    ENVIRON  stringexpression$


Remarks

The argument  stringexpression$ is a string constant or variable that
contains the name of the environment variable, such as PATH or PROMPT. It
can have the form  parameterID= text, or  parameterID  text. Everything to
the left of the equal sign or space is assumed to be a parameter, and
everything to the right, text.

The argument  parameterID must contain all uppercase letters. For example:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
This statement:                         Has this effect:
────────────────────────────────────────────────────────────────────────────
This statement:                         Has this effect:
────────────────────────────────────────────────────────────────────────────
ENVIRON "PATH=C:\SALES"                 Changes the path.

ENVIRON "path=C:\SALES"                 Does not change the path. (It
                                        creates a new environment
                                        parameter not usable by the
                                        operating system.)



If  parameterID did not previously exist in the environment-string table, it
is appended to the end of the table. If  parameterID exists in the table
when the  ENVIRON statement is executed, it is deleted and the new
parameterID value is appended to the end of the table.

The text string is the new parameter text. If the text is a null string ("")
or a semicolon (";"), the existing parameter is removed from the
environment-string table and the remaining body of the table is compressed.

DOS or OS/2 discards the environment-string table modified by this function
when your program ends. The environment-string table is then the same as it
was before your program ran.


Note

You cannot increase the size of the environment-string table when using the
ENVIRON statement. This means that before you can add a new environment
variable or increase the size of an existing environment variable you must
first delete or decrease the size of existing environment variable(s).


You can 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 process by creating a new environment variable.

BASIC generates the error message Out of memory when no more space can be
allocated to the environment-string table. The amount of free space in the
table usually is quite small.


See Also

    ENVIRON$,  SHELL Function


Example

The following example uses the  ENVIRON$ function to get a copy of the
current DOS path variable. The path variable is then changed using the
ENVIRON statement. The contents of the environment-string table are then
displayed using the  ENVIRON$ function.

DEFINT A-Z
' Initialize variables.
Path$ = "PATH="
I% = 1
' Store the old PATH.
OldPath$ = ENVIRON$("PATH")
ENVIRON "PATH=C:\BIN;C:\DOS;C:\BUSINESS\ACCOUNTING\RECEIVABLES\MAY"
' Display the entire environment-string table.
PRINT "Your current environment settings are:"
PRINT
DO WHILE ENVIRON$(I%) <> ""
    PRINT ENVIRON$(I%)
    I% = I% + 1
LOOP
' Change the PATH back to original.
ENVIRON Path$ + OldPath$
' Verify the change.
PRINT
PRINT "Your PATH has been restored to:"
PRINT
PRINT ENVIRON$("PATH")




EOF Function
────────────────────────────────────────────────────────────────────────────


Action

For an ISAM table, tests whether the current position is at the end of a
table. For a non-ISAM file, tests for the end-of-file condition.


Syntax

    EOF( filenumber%)


Remarks

The argument  filenumber% is the number used in the  OPEN statement to open
the file or ISAM table.

The  EOF function returns true (nonzero) if the end of a non-ISAM file has
been reached or if the current position in an ISAM table is at the end of
the table. The end of an ISAM table is the position immediately following
the last record according to the current index. Use the  EOF function with
sequential files to test for the end of a file. This helps you avoid the
Input past end of file error message.

When used with random-access or binary files,  EOF returns true if the last
executed  GET statement was unable to read an entire record.

When you use  EOF with a communications device, the definition of the
end-of-file condition depends 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( filenumber%)=0), where
filenumber% is the number of the device. It becomes false when the input
queue is not empty.


Note

    EOF cannot be used with the BASIC devices SCRN, KYBD, CONS, LPT n, or PIPE.


See Also

    BOF,  LOC,  LOF,  OPEN


Example

See the  INPUT# statement programming example, which uses the  EOF function.




ERASE Statement
────────────────────────────────────────────────────────────────────────────


Action

Reinitializes the elements of static arrays; deallocates dynamic arrays.


Syntax

    ERASE  arrayname «,  arrayname»...


Remarks

The  arrayname arguments are the names of arrays to erase. It is important
to know if this array is static or dynamic.  ERASE sets the elements of an
array as follows:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
If type of array is:                    ERASE sets array elements to:
────────────────────────────────────────────────────────────────────────────
Numeric static array                    Zeros.

String static array                     Null strings ("").

Array of records                        Zeros [mdash] all elements of each
                                        record, including fixed-string
                                        elements.


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 redeclare the
array's dimensions with a  DIM or  REDIM statement. If you redeclare the
array's dimensions with a  DIM statement without first erasing it, BASIC
generates the run-time error message Array already dimensioned. The  ERASE
statement is not required when dimensions are redeclared with  REDIM.


See Also

    CLEAR,  DIM,  REDIM


Example

The following example shows the use of  ERASE with the  $DYNAMIC and
$STATIC metacommands:

REM $DYNAMIC
DIM A(100, 100)
' Deallocate array A.
ERASE A
' Redeclare dimensions for array A.
REDIM A(5, 5)

REM $STATIC
DIM B(50, 50)
' Set all elements of B equal to zero. (B still has the dimensions
' assigned by DIM.)
ERASE B




ERDEV, ERDEV$ Functions
────────────────────────────────────────────────────────────────────────────


Action

Provide device-specific status information after an error.


Syntax

    ERDEV
ERDEV$


Remarks

    ERDEV is an integer function that returns an error code from the last
device that generated a critical error.  ERDEV$ is a string function that
returns the name of the device that generated the error. Because  ERDEV and
ERDEV$ return meaningful information only after an error, they usually are
used in error-handling routines specified by an  ON ERROR statement.

    ERDEV$ contains the 8-byte character device name if the error is on a
character device, such as a printer, or the 2-byte block name (A:, B:, etc.)
if the device is not a character device. It contains the 3-byte block name
(COM) if the communications port experiences a timeout.

    ERDEV is set by the critical error handler (interrupt 24H) when DOS detects
a critical DOS call error. It also is set by a timeout error on the
communications port and indicates which option in the  OPEN  COM statement
(CD, CS, or DS) is experiencing the timeout.

    ERDEV returns an integer value that contains information about the error.
For block and character device errors, the low byte of  ERDEV contains the
DOS error code. For block devices only, the high byte contains
device-attribute information.

For  COM timeout errors,  ERDEV returns a value corresponding to the source
of the timeout. For more information, see the entry for the  OPEN  COM
statement.

Assuming an  ERDEV return value of x, the following program lines generate
the DOS error code (low byte) and device attribute information (high byte).

DosErrCode = x AND &HFF' Low byte of ERDEV.
DevAttr = (x AND &HFF00) \ 256   ' High byte of ERDEV.

For more information about device-attribute words, see the  Microsoft MS-DOS
    Programmer's  Reference, or books such as  The Peter Norton Guide to the
IBM PC or  Advanced MS-DOS.


Use  ERDEV only in DOS.


Example

The following example prints the values of  ERDEV and  ERDEV$ after the
program generates an error attempting to open a file:

DEFINT A-Z
ON ERROR GOTO ErrorHandler' Indicate first line of error handler.
OPEN "A:JUNK.DAT" FOR INPUT AS #1' Attempt to open the file.
END

ErrorHandler:
PRINT "ERDEV value is "; ERDEV
PRINT "Device name is "; ERDEV$
ON ERROR GOTO 0

Output
Running the program with drive A unlatched produces the following output (2 i

ERDEV value is  2
Device name is A:




ERR, ERL Functions
────────────────────────────────────────────────────────────────────────────


Action

Return error status.


Syntax

    ERR

    ERL


Remarks

After an error, the  ERR function returns an integer that is the run-time
code for the error. The  ERL function returns an integer that is the line
number where the error occurred, or the closest line number before the line
where the error occurred. Because  ERR and  ERL return mean-ingful values
only after an error, they usually are used in error-handling routines to
determine the error and the corrective action.

The value returned by the  ERR function can be directly set by using the
ERR statement. Both the values returned by  ERR and  ERL can be set
indirectly with the  ERROR statement.

The  ERL function returns only the line number, not line labels, located at
or before the line producing the error. If your program has no line numbers,
or there is no line number in the program before the point where the error
occurred,  ERL returns 0.

    ERL values differ between programs compiled with BC and those run under
QBX. In programs compiled with BC,  ERL is set to the last numbered line in
the source file preceding the line where the error occurred. When QBX
detects an error in a procedure, it looks for a line number only within the
immediate procedure. If the procedure doesn't contain a numbered line, QBX
returns 0 for  ERL.

You can make your programs run identically with both BC and QBX by always
including a line number at the beginning of a procedure where an error might
occur.


See Also

    ERROR;  ON  ERROR;  RESUME; Table 4.1, "Run-Time Error Codes"


Example

See the  ON ERROR statement programming example, which uses the  ERR
function.




ERR Statement
────────────────────────────────────────────────────────────────────────────


Action

Sets  ERR to a specific value.


Syntax

    ERR =  n%



Remarks

The argument  n% is an integer expression with a value between 1 and 255,
inclusive, that specifies a run-time error code, or 0.

When running an application program, BASIC uses  ERR to record whether or
not a run-time error has occurred and what the error was. When a program
starts running,  ERR is 0; when and if a run-time error occurs, BASIC sets
ERR to the error code for that error.

You may want to use the  ERR statement to set  ERR to a non-zero value to
communicate error information between procedures. For example, you might use
one of the run-time codes not used by BASIC as an application-specific error
code. See Table 4.1, "Run-Time Error Codes," for a list of the run-time
error codes that BASIC uses; they are a subset of the integers between 1 and
255, inclusive.

Besides the  ERR statement, the following BASIC statements set  ERR whenever
they execute:

    ■   Any form of the  RESUME statement sets  ERR to 0.

    ■    EXIT  SUB,  EXIT  FUNCTION, or  EXIT  DEF sets  ERR to 0 if executed
        within a procedure-level error handler.

    ■   All uses of the  ON ERROR or  ON  LOCAL  ERROR statements syntax set
        ERR to 0.

    ■   The  ERROR statement can be used to set  ERR to any value as part of
        simulating any run-time error.


See Also

    ERR,  ERL;  ERROR; Table 4.1, "Run-Time Error Codes"


Example

See the  ON ERROR statement programming example, which uses the  ERR
statement.




ERROR Statement
────────────────────────────────────────────────────────────────────────────


Action

Simulates the occurrence of a BASIC error or a user-defined error.


Syntax

    ERROR  integerexpression%


Remarks

The argument  integerexpression% represents the error code. It must be
between 1 and 255, inclusive. If  integerexpression% is an error code
already used by BASIC, the  ERROR statement simulates the occurrence of that
error.

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 avoid
compromising compatibility with future Microsoft BASIC error codes.) In
general, the error codes used by BASIC are between 1 and 100 (although not
all these are used).

If an error statement is executed when no error-handling routine is enabled,
BASIC generates an error message and stops program execution. If the  ERROR
statement specified an error code that is not used by BASIC, the message
Unprintable error is generated.


See Also

    ERR,  ERL;  ON ERROR;  RESUME


Example

See the  ON ERROR statement programming example, which uses the  ERROR
statement.




EVENT Statements
────────────────────────────────────────────────────────────────────────────


Action

Enable or disable trapping of events.


Syntax

    EVENT ON

    EVENT OFF


Remarks

    EVENT  ON enables trapping of events until BASIC encounters the next  EVENT
OFF statement.

    EVENT OFF disables trapping of events until BASIC encounters the next
EVENT ON statement.

The  EVENT statements affect compiled code generation. When  EVENT OFF is in
effect, the compiler will not generate any event-checking code between
statements.  EVENT OFF is equivalent to compiling a program without /V or
/W.  EVENT OFF can be used to create small and fast code that still supports
event trapping.

If your program contains event-handling statements and you are compiling
from the BC command line, use the BC /W or /V option. (The /W option checks
for events at every label or line number; the /V option checks at every
statement.) If you do not use these options and your program contains event
traps, BASIC generates the error message ON event without /V or /W on
command line.

    EVENT OFF and  EVENT ON can be used to bracket sections of code where
events do not need to be detected and trapped, and fast performance is
required. Events still could be detected and tracked if a subroutine using
EVENT ON were called from a section of  EVENT OFF code.

If an event occurs while  EVENT OFF is in effect, this event still is
remembered and then is handled as soon as an  EVENT ON block is entered.


See Also

    ON  event


Example

See the  STRIG statements programming example, which uses the  EVENT
statements.




EXIT Statement
────────────────────────────────────────────────────────────────────────────


Action

Exits a  DEF FN function, a  DO... LOOP or  FOR... NEXT loop, or a  FUNCTION
or  SUB procedure.


Syntax

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


Remarks

There are a number of ways to use the  EXIT statement, as described in the
following list:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Statement                               Description
────────────────────────────────────────────────────────────────────────────
    EXIT DEF                               Causes an immediate exit from the
                                        executing  DEF FN function.
                                        Program execution continues where
                                        the  DEF FN function was invoked.

    EXIT DO                                Provides an alternative exit from
                                        a  DO... LOOP statement.  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
Statement                               Description
────────────────────────────────────────────────────────────────────────────
                                        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
                                        procedure was invoked. Can be used
                                        only in a  FUNCTION procedure.

    EXIT SUB                               Immediately exits a  SUB procedure.
                                        Program execution continues with
                                        the statement after the  CALL
                                        statement. Can be used only in a
                                        SUB procedure.



None of the  EXIT statements defines the end of the structure in which it is
used.  EXIT statements provide only an alternative exit from the structure.


See Also

    DEF FN,  DO... LOOP,  FOR... NEXT,  FUNCTION,  SUB


Example

The following example demonstrates the use of a variety of  EXIT statements.
A loop is continuously executed until a key is pressed. Once a key is
pressed, the next  EXIT statement that executes will cause the program to
end.

DECLARE SUB ExitDemo ()
CLS
DO
PRINT : PRINT "Entering/Re-entering ExitDemo"
ExitDemo
SLEEP 1
LOOP WHILE INKEY$ = ""
PRINT "Exiting EXIT statement programming example."
END

SUB ExitDemo
DO
FOR I% = 1 TO 1000
Num% = INT(RND * 100)
SELECT CASE Num%
CASE 7
PRINT "Exiting FOR...NEXT loop in ExitDemo SUB"
EXIT FOR
CASE 29
PRINT "Exiting DO...LOOP in ExitDemo SUB"
EXIT DO
CASE 54
PRINT "Exiting ExitDemo SUB"
EXIT SUB
CASE ELSE
END SELECT
NEXT I%
LOOP
END SUB




EXP Function
────────────────────────────────────────────────────────────────────────────


Action

Calculates the exponential function.


Syntax

    EXP( x)


Remarks

The  EXP function returns  e (the base of natural logarithms) to the power
of  x.

The exponent  x must be less than or equal to 88.02969 when you are using
single-precision values and less than or equal to 709.782712893 when you are
using double-precision values. If you use a value of  x that isn't within
those limits, BASIC generates the error message Overflow.

    EXP is calculated in single precision if  x is an integer or
single-precision value. If you use any other numeric data type,  EXP is
calculated in double precision.


See Also

    LOG


Example

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


Output

Initial bacterial population? 10000
Growth rate per day as a percentage of population? 10

Day        Population
    0           10,000
    5           16,487
10           27,183
15           44,817


FIELD Statement
────────────────────────────────────────────────────────────────────────────


Action

Allocates space for variables in a random-access file buffer.


Syntax

    FIELD «#»  filenumber%,   fieldwidth%  ASstringvariable$ «,   fieldwidth%
ASstringvariable$»...


Remarks

The  FIELD statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    fieldwidth%                            The number of characters in a
                                        field.

    stringvariable$                        The string variable that contains
                                        the data 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 you specified when opening the file. Otherwise,
BASIC generates an error message that reads FIELD overflow. (The default
record length is 128 bytes.)

Any number of  FIELD statements can 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.


Note

Do not use a variable name defined as a field in an  INPUT or assignment
statement if you want 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.


BASIC's record variables and extended  OPEN statement syntax provide a more
convenient way to use random-access files. See Chapter 3, "File and Device
I/O" in the  Programmer's Guide for an extended discussion of using record
variables for file I/O.


BASICA

When a random-access file is closed with a  CLOSE or  RESET statement in a
compiled program, all variables that are fields associated with that file
are reset to null strings. When a random-access file is closed in a BASICA
program, variables that are fields retain the last value assigned to them by
a  GET statement.


See Also

    GET (File I/O),  LSET,  PUT (File I/O),  RSET
Example

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

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

' 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

' 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




FILEATTR Function
────────────────────────────────────────────────────────────────────────────


Action

Returns information about an open file or ISAM table.


Syntax

    FILEATTR( filenumber%,  attribute%)


Remarks

    FILEATTR returns information about an open file or ISAM table, such as the
DOS file handle and whether the file was opened for input, output, random,
append, or ISAM binary mode.

The  FILEATTR function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file or ISAM
                                        table. You can use a numeric
                                        expression as long as BASIC
                                        evaluates it to the number of an
                                        open file, device, or ISAM table.

Argument                                Description
────────────────────────────────────────────────────────────────────────────

    attribute%                             Indicates the type of information
                                        to return about the file or table.
                                        When  attribute% is 1,  FILEATTR
                                        returns a value indicating the
                                        file's mode (see below). When
                                        attribute% is 2 and  filenumber%
                                        indicates a file,  FILEATTR
                                        returns the DOS handle for the
                                        file. When  attribute% is 2 and
                                        filenumber% indicates an ISAM
                                        table,  FILEATTR returns 0.



The following table lists the return values and corresponding file modes
when  attribute% is 1:

╓┌────────────────────────────┌──────────────────────────────────────────────╖
Return value                 Mode
────────────────────────────────────────────────────────────────────────────
1                            Input
2                            Output
4                            Random access
8                            Append
32                           Binary
64                           ISAM


See Also

    OPEN (File I/O)


Example

The following example opens a file and displays its DOS file handle and
mode:

OPEN "tempfile.dat" FOR APPEND AS #1
PRINT "Handle: "; FILEATTR(1,2); "      Mode: "; FILEATTR(1,1)

Output

Handle:  5      Mode:  8




FILES Statement
────────────────────────────────────────────────────────────────────────────


Action

Prints the names of files residing on the specified disk.


Syntax

    FILES  «filespec$»


Remarks

The argument  filespec$ is a string variable or constant that includes
either a filename or a path, and an optional device name.

If no argument is specified, the  FILES statement lists all the files in the
current directory. You can use the DOS wildcard characters -- question
marks ( ?) or asterisks (*). A question mark matches any single character in
the filename or extension. An asterisk matches one or more characters
starting at that position.

If you use  filespec$ without an explicit path, the current directory is the
default.


Examples

The statements below illustrate the use of  FILES.

Note that execution halts if you try to run this example without a disk in
drive B or if the specified files cannot be found.

FILES' Show all files on the current directory.
FILES "*.BAS" ' Show all files with the extension .BAS.
FILES "B:*.*" ' Show all files in current directory of drive B.
FILES "B:" ' Equivalent to "B:*.*".
FILES "TEST?.BAS" ' Show 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.




FIX Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the truncated integer part of a numeric expression.


Syntax

    FIX( x#)


Remarks

The argument  x# is a numeric expression.  FIX( x#) is equivalent to SGN(
x#)*INT(ABS( x#)) . The difference between  FIX and  INT is that for
negative  x#,  FIX returns the first negative integer greater than  x#,
while  INT returns the first negative integer less than  x#.


See Also

    CINT,  INT


Example

The following statements illustrate the differences between  INT and  FIX:

PRINT INT(-99.8)
PRINT FIX(-99.8)
PRINT INT(-99.2)
PRINT FIX(-99.2)

Output

-100
-99
-100
-99




FOR...NEXT Statement
────────────────────────────────────────────────────────────────────────────


Action

Repeats a group of instructions a specified number of times.


Syntax

    FOR  counter =  start  TO  end   «STEP  increment»
    « statementblock»
    « EXIT  FOR»
    « statementblock»
    NEXT   «counter «,  counter»...»


Remarks

The  FOR statement takes the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    counter                                A numeric variable used as the
                                        loop counter. The variable cannot
                                        be an array element or a record
                                        element.

    start                                  The initial value of the counter.

    end                                    The final value of the counter.

    increment                              The amount the counter is changed
                                        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. BASIC checks this 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.

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  start and  end have the same value, the loop executes once, regardless
of the value of  STEP. Otherwise,  STEP value controls the loop as follows:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
STEP value                              Loop execution
────────────────────────────────────────────────────────────────────────────
Positive                                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
STEP value                              Loop execution
────────────────────────────────────────────────────────────────────────────
                                        loop is exited; execution
                                        continues with the statement
                                        following the  NEXT statement.

Negative                                The loop repeats until  counter is
                                        less than  end.

Zero                                    The loop repeats indefinitely.


Avoid changing the
value of  counter within the loop. Changing the loop counter is poor
programming practice; it can make the program more difficult to read and
debug.

You can nest  FOR... NEXT loops; that is, you can place a  FOR... NEXT loop
within another  FOR... NEXT loop. To ensure that nested loops work properly,
give each loop a unique variable name as its counter. The  NEXT statement
for the inside loop must appear before the  NEXT statement for the outside
loop. The following construction is correct:

FOR I = 1 TO 10
    FOR J = 1 TO 10
        FOR K = 1 TO 10
        .
        .
        .
        NEXT K
    NEXT J
NEXT I

A  NEXT statement with the form NEXT K, J, I is equivalent to the following
sequence of statements:

NEXT K
NEXT J
NEXT I

The  EXIT FOR statement is a convenient alternative exit from  FOR... NEXT
loops. See the entry for  EXIT.


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, BASIC generates the error message NEXT
without FOR.


BASICA

Unlike BASICA, BASIC supports double-precision control values ( start,  end,
and  counter) in its  FOR...NEXT loops. However, if the control values fall
within the range for integers, you should use integer control values for
maximum speed.


Example

The following example prints the first 11 columns of Pascal's Triangle, in
which each number is the sum of the number immediately above it and the
number immediately below it in the preceding column:

DEFINT A-Z
CLS ' Clear screen.
CONST MAXCOL = 11
DIM A(MAXCOL, MAXCOL)
PRINT "Pascal's Triangle"
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

Pascal's Triangle

                                                                1
                                                        1
                                                    1            10
                                            1           9
                                        1           8            45
                                1           7           36
                            1           6           28          120
                    1           5           21          84
                1           4           15          56          210
        1           3           10          35          126
    1           2           6           20          70          252
        1           3           10          35          126
                1           4           15          56          210
                    1           5           21          84
                            1           6           28          120
                                1           7           36
                                        1           8            45
                                            1           9
                                                    1            10
                                                        1
                                                                1




FRE Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a value representing the amount of available memory, depending upon
a given argument.


Syntax 1

    FRE( numeric- expression%)

Syntax 2

    FRE( stringexpression$)


Remarks

The argument for  FRE can be either a string or numeric expression . The
argument  stringexpression$ can be a string literal or a string variable.

The values returned for the different types of arguments depend on whether
you are using near strings or far strings, as described in the following
table:
╓┌──────────────────────┌─────────────────────────┌──────────────────────────╖
Function               Value returned if using   Value returned if using
                        near strings              far strings
────────────────────────────────────────────────────────────────────────────
FRE(a$)                Remaining space inDGROUP  Remaining space in  a$'s
                        (in bytes)                segment (in bytes)

FRE("string literal")  Remaining space inDGROUP  Remaining space for
                        (in bytes)                temporary strings (in
                                                    bytes)

FRE(0)                 Remaining space in        Error message: Illegal
                        DGROUP (in bytes)         function call

FRE(-1)                For DOS, remaining space  For DOS, remaining space
                        (in bytes) in far         (in bytes) in far memory;
                        memory; for OS/2, long    for OS/2, long integer
                        integer 2147483647        2147483647

FRE(-2)                Remaining stack space     Remaining stack space (in
                        (in bytes)                bytes)
Function               Value returned if using   Value returned if using
                        near strings              far strings
────────────────────────────────────────────────────────────────────────────
                        (in bytes)                bytes)

FRE(-3)                Remaining space in        Remaining space in
                        expanded memory (in       expanded memory (in
                        kilobytes)                kilobytes)

FRE(any other no.)     Error message: Illegal    Error message: Illegal
                        function call             function call




FRE(-2) returns the amount of stack space that was never used by the
program. For example, suppose a program uses a lot of stack space in a
recursive procedure and then returns to the main level to execute a FRE(-2).
The value returned will be the amount of stack space that was never used by
the program. Any space used by the recursive procedure is considered "used"
So FRE(-2) enables you to find out at the completion of your program what
the worst-case stack usage was for that program.


Using FRE(-3) and Expanded Memory
If expanded memory is not available, FRE(-3) generates the error message
Feature unavailable.

If you start QBX without the /E: n switch, you will be using all of the
expanded memory available on your computer. If you start QBX with the /E: n
switch, you can limit the amount of expanded memory available to your
program. For example, if your computer has 5 megabytes of expanded memory
but you want to use only 4 megabytes of expanded memory, you would start QBX
with this command line:

QBX /E:4096

If you have specified 4 megabytes of expanded memory as shown above, and
then you use 2 megabytes of expanded memory in your program, FRE(-3) will
return 2048.

If you are using BC to run a program with expanded memory overlays, the
value returned by FRE(-3) is based on the total amount of expanded memory
available. (When using overlays, you cannot limit the amount of expanded
memory used by your program.)

For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.


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 monitoring a variable.


Example

The following example demonstrates use of the  FRE function to report the
availability of memory resources. It also uses the  STACK function to
allocate stack space.

DECLARE SUB MakeSubString ()
DECLARE SUB Printit (A$)
DECLARE SUB Recursive (n!)
PRINT "Remaining space to begin with is:"
CALL Printit(A$)
String1$ = STRING$(32767, 90)' Create a 32K string.
PRINT " The remaining space after creating a 32K far string is:"
CALL Printit(String1$)
MakeSubString ' Make a substring and give report.
PRINT "The remaining space after returning from a SUB is:"
CALL Printit(String2$)
n = 50 ' Do 50 recursive calls to a SUB procedure.
CALL Recursive(n)
STACK (2048)
PRINT "After allocating 2K for the stack, the space is:"
CALL Printit(A$)
n = 50 ' Do another 50 recursive calls to a SUB procedure.
CALL Recursive(n)
'Dimension a 1001-element dynamic array in EMS.
REDIM A%(999)
PRINT "After dimensioning a 1000-element integer array, the space is:"
CALL Printit(A$)
PRINT "After dimensioning a second 1000-element integer array:"
CALL Printit(A$)

PRINT "Stack reset to default value: "; STACK

SUB MakeSubString
SHARED String1$
    String2$ = STRING$(32767, 90)
    PRINT "The space remaining after creating a 32K sub string is:"
    CALL Printit(String1$)
END SUB

SUB Printit (A$)
    PRINT : PRINT "Far Memory"; TAB(15); "Stack"; TAB(25);
    PRINT "String Segment";TAB(45);"Temporary Segment";TAB(65);"EMS Memory"
    PRINT FRE(-1); TAB(15); FRE(-2); TAB(25); FRE(A$); TAB(45); FRE("")
    PRINT TAB(65); FRE(-3); "K"
END SUB

SUB Recursive (n)
SHARED String1$
    n = n - 1
    IF n = 0 THEN
        PRINT "The remaining space after 50 recursive calls is:"
        CALL Printit(String1$)
        EXIT SUB
    ELSE
        CALL Recursive(n)
    END IF
END SUB




FREEFILE Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the next valid unused file number.


Syntax

    FREEFILE


Remarks

Use  FREEFILE when you need to supply a file number and you want to ensure
that the file number is not already in use.


See Also

    OPEN (File I/O)


Example

The following example uses  FREEFILE to obtain the next available file
number for opening a sequential file.  OPEN,  CLOSE, and  KILL also are
used.

DIM Filenum AS INTEGER
CLS
INPUT "Enter filename: ", filename$
Filenum% = FREEFILE
OPEN filename$ FOR OUTPUT AS Filenum%
PRINT
PRINT UCASE$(filename$); " opened for output as File #"; Filenum%
' Put something out to the file.
PRINT #Filenum%, "The quick brown fox jumped over the lazy dog."
' Close the file just opened.
CLOSE Filenum%
Filenum% = FREEFILE
OPEN filename$ FOR INPUT AS Filenum%
PRINT : PRINT UCASE$(filename$); " has been reopened for input."
LINE INPUT #Filenum%, L$
PRINT : PRINT "The contents of the file are:"; L$
CLOSE Filenum%
' Remove the file from disk.
KILL filename$




FUNCTION Statement
────────────────────────────────────────────────────────────────────────────


Action

Declares the name, the parameters, and the return type of a  FUNCTION
procedure.


Syntax

    FUNCTION  name «( parameterlist») « STATIC»
    « statementblock»
    « name =  expression»
    « statementblock»
    « EXIT  FUNCTION»
    « statementblock»
    END FUNCTION


Remarks

The following list describes the parts of the  FUNCTION statement:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    name                                   The name of the function.
                                        FUNCTION procedure names follow
                                        the same rules as are used for
                                        naming BASIC variables and can
                                        include a type-declaration
                                        character  (%,  &,  !,  #,  @,
                                        or  $). Note that the type of the
                                        name determines the data type the
                                        function returns. For example, to
                                        create a function that returns a
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        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,
                                        representing parameters, that will
                                        be passed to the function
                                        procedure when it is called.
                                        Multiple variables are separated
                                        by commas. 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
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        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 procedure but declared
                                        outside the procedure in  DIM or
                                        COMMON statements using the
                                        SHARED statement.

    expression                             The return value of the function.
                                        A  FUNCTION procedure returns a
                                        value by assigning a value to the
                                        function name. If no value is
                                        assigned to the  FUNCTION name,
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        assigned to the  FUNCTION name,
                                        the procedure returns a default
                                        value: a numeric function returns
                                        zero, and a string function
                                        returns the null string ("").

    EXIT FUNCTION                          Causes an immediate exit from a
                                        FUNCTION procedure. Program
                                        execution continues where the
                                        procedure was invoked. For more
                                        information, see the entry for the
                                            EXIT statement.



The argument  parameterlist has the following syntax:

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

The following list describes the parts of  parameterlist :
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               A BASIC variable name. Previous
                                        versions of BASIC required the
                                        number of dimensions in
                                        parentheses after an array name.
                                        In the current version of BASIC,
                                        the number of dimensions is not
                                        required.

    AS  type                               The type of the variable:  INTEGER,
                                            LONG,  SINGLE,  DOUBLE,  STRING,
                                        CURRENCY, or a user-defined type.
                                        You cannot use a fixed-length
                                        string, or an array of
                                        fixed-length strings, as a
                                        parameter. However, you can use a
                                        simple fixed-length string as an
                                        argument in a  CALL statement;
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        argument in a  CALL statement;
                                        BASIC converts a simple
                                        fixed-length string argument to a
                                        variable-length string argument
                                        before passing the string to a
                                        FUNCTION procedure.




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 procedure, a  FUNCTION procedure is used in an expression in
the same manner as a BASIC intrinsic function.

Like  SUB procedures,  FUNCTION procedures use local variables. Any variable
referred to within the body of the function is local to the  FUNCTION
procedure unless one of the following conditions is true:

    ■         The variable is declared within the function as a shared
            variable with a  SHARED statement.

    ■         The variable appears in a  DIM or  COMMON statement with the
            SHARED attribute at the module level.

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 attribute increases execution speed slightly.  STATIC
usually is not used with recursive  FUNCTION procedures.


Note

Avoid using I/O statements in a  FUNCTION procedure called from an I/O
statement; they can cause unpredictable results. Also, because BASIC may
rearrange arithmetic expressions to attain greater efficiency, avoid using
FUNCTION procedures that change program variables in arithmetic expressions.


    FUNCTION procedures are recursive -- they can call themselves to
perform a given task. See the example for more information.


See Also

    DECLARE (BASIC),  DEF FN,  STATIC Statement,  SUB


Example

The following example uses a recursive  FUNCTION procedure (a procedure that
calls itself) to find, and return as an integer, the length of a string:

DECLARE FUNCTION StrgLng% (X$).
INPUT "Enter a string: "; InString$
PRINT "The string length is"; StrgLng%(InString$)

FUNCTION StrgLng% (X$)
    IF X$ = "" THEN
        StrLng% = 0 ' The length of a null string is zero.
    ELSE
        StrgLng% = 1 + StrgLng%(MID$(X$, 2))  ' Make a recursive call.
    END IF
END FUNCTION




GET Statement (File I/O)
────────────────────────────────────────────────────────────────────────────


Action

Reads from a disk file into a random-access buffer or variable.


Syntax

    GET «#» filenumber%«,« recordnumber%» «,  variable»»


Remarks

Do not use  GET on ISAM files.

The  GET statement uses the following arguments:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    recordnumber%                          For random-access files, the
                                        number of the record to be read.
                                        For binary-mode files, the byte
                                        position where reading starts. The
                                        first record or byte position in a
                                        file is 1. If you omit
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        file is 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
                                        read into the buffer. The largest
                                        possible record number is 2to31 -1,
                                        or 2,147,483,647.

    variable                               The variable used to receive input
                                        from the file. If you specify a
                                        variable, you do not need to use
                                        CVI,  CVL,  CVS,  CVD, or  CVC to
                                        convert record fields to numbers.
                                        You cannot use a  FIELD statement
                                        with the file if you use the
                                        variable argument.

                                        For random-access files, you can
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        For random-access files, you can
                                        use any variable as long as the
                                        length of the variable is less
                                        than or equal to the length of the
                                        record. Usually, a record variable
                                        defined to match the fields in a
                                        data record is used.

                                        For binary-mode files, you can use
                                        any variable. 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
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        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 can omit  recordnumber%,  variable, or both. If you omit  recordnumber%
but include a variable, you must still include the commas:

GET #4,,FileBuffer

If you omit both arguments, do not include the commas:

GET #4

    GET and  PUT statements allow fixed-length input and output for BASIC
communication files. Use  GET carefully, because if there is a communication
failure,  GET waits indefinitely.


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 can use the  EOF function after a  GET statement to see if
the  GET operation went beyond the end of the file.


See Also

    CVI,  CVL,  CVS,  CVD,  CVC;  LSET;  MKI$,  MKL$,  MKS$,  MKD$,  MKC$; OPEN
(File I/O);  PUT (File I/O)


Example

The following example creates a random-access test file that contains five
names and corresponding test scores. It then displays the contents of the
file using the  GET statement.

' 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
DIM I AS LONG

' This part of the program creates a random-access file to be used by
' the second part of the program, which demonstrates the GET statement.
OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(Rec)
CLS
RESTORE
READ NameField$, ScoreField
I = 0
DO WHILE NameField$ <> "END"
    I = I + 1
    Rec.NameField = NameField$
    Rec.ScoreField = ScoreField
    PUT #1, I, Rec
    READ NameField$, ScoreField
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
DIM Max AS LONG
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
' Remove file from disk.
KILL "TESTDAT2.DAT"
END




GET Statement (Graphics)
────────────────────────────────────────────────────────────────────────────


Action

Stores graphic images from the screen.


Syntax


    GET   STEP( x1!,  y1!) -  STEP( x2!,  y2!),  arrayname(
indexes%)


Remarks

The list below describes the parts of the  GET statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
( x1!,  y1!),( x2!,  y2!)               Coordinates that mark a
Part                                    Description
────────────────────────────────────────────────────────────────────────────
( x1!,  y1!),( x2!,  y2!)               Coordinates that mark a
                                        rectangular area on the screen; an
                                        image within this rectangle will
                                        be stored. The  x1!,   y1!,   x2!,
                                        and  y2! are numeric expressions.
                                        The coordinates ( x1!,  y1!) and (
                                        x2!,  y2!) 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), 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
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        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.

    indexes%                               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:

size = 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 screen mode
set by the  SCREEN statement. The following table shows the number of
bits-per-pixel-per-plane and the number of planes for each screen mode:
╓┌────────────────────────┌─────────────────────────┌────────────────────────╖
Screen mode              Bits per pixel per plane  Planes
────────────────────────────────────────────────────────────────────────────
1                        2                         1
2                        1                         1
7                        1                         4
8                        1                         4
9 (64K of EGA  memory)   1                         2
9 (> 64K of EGA memory)  1                         4
Screen mode              Bits per pixel per plane  Planes
────────────────────────────────────────────────────────────────────────────
9 (> 64K of EGA memory)  1                         4
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.

    ■         Eight bytes for a currency 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 operation appear meaningless when inspected directly. Examining or
manipulating noninteger arrays containing graphics images may cause run-time
errors.

    GET and  PUT statements operating on the same image should be executed in
matching screen modes. These modes can be either the same screen mode or any
screen modes with the same values for planes and bits-per-pixel-per-plane.

One of the most useful things that can be done with  GET and  PUT statements
is animation. See Chapter 5, "Graphics" in the  Programmer's Guide for a
discussion of animation.


See Also

    PUT (Graphics)


Example

See the  BSAVE statement programming example, which uses the  GET statement.




GETINDEX$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the name of the current index for an ISAM table.


Syntax

    GETINDEX$ ( filenumber%)


Remarks

The  filenumber% is the number used in the  OPEN statement to open the
table.

    GETINDEX$ takes the number of an open ISAM table and returns the name of
the current index. If the current index is the null index , the value
returned is a null string.


See Also

    CREATEINDEX,  DELETEINDEX,  OPEN (File I/O),  SETINDEX


Example

See the  CREATEINDEX statement programming example, which uses the
GETINDEX$ function.




GOSUB...RETURN Statements
────────────────────────────────────────────────────────────────────────────


Action

Branch to, and return from, a subroutine.


Syntax

    GOSUB { linelabel1 |  linenumber1}
    .
    .
    .
    RETURN  «{ linelabel2 |  linenumber2}»


Remarks

The  GOSUB... RETURN statements use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    linelabel1, linenumber1                The line label or line number 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  better-structured
alternative to  GOSUB... RETURN subroutines.


In addition to  RETURN with no argument, BASIC supports  RETURN with a line
label or line number. This allows a return from a subroutine to the
statement having the specified line label or number, instead of returning to
the statement after the  GOSUB statement. Use this line-specific type of
return with care.

You can call a subroutine any number of times in a program. You also can
call a subroutine from within another subroutine. How deeply you can nest
subroutines is limited only by the available stack space (you can 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 return control to a statement in the
module-level code only, not in procedure-level code. See the example
program.

A subroutine can contain more than one  RETURN statement. A simple  RETURN
statement (without the  linelabel2,  linenumber2 option) in a subroutine
makes BASIC branch back to the statement following the most recent  GOSUB
statement.

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


Note

The preceding discussion of subroutines applies only to the targets of
GOSUB  statements, not procedures delimited by  SUB statements. For
information on entering and exiting  SUB procedures, see the entry for the
CALL statement (BASIC procedures).


See Also

    RETURN,  SUB


Example

The following example shows the use of the  GOSUB and  RETURN statements.

Note the  END statement before the module-level subroutine. If it is not
present, the PrintMessage subroutine will be executed after the return to
Label1. BASIC will generate the error message RETURN without GOSUB.

CLS
GOSUB PrintMessage
PRINT "This message is in module-level code"
GOSUB Sub1
PRINT "This line in module-level code should be skipped."
Label1:
    PRINT "This message is back in module-level code"
END

PrintMessage:
    PRINT "This program uses the GOSUB and RETURN statements."
    PRINT
    RETURN

Sub1:
    PRINT "This message is in Sub1."
    GOSUB Sub2
    PRINT "This line in Sub1 should be skipped."
Label2:
    PRINT "This message is back in Sub1."
    RETURN Label1

Sub2:
    PRINT "This message is in Sub2."
    RETURN Label2   ' Cannot return from here to module-level
                    ' code-only to SUB1.




GOTO Statement
────────────────────────────────────────────────────────────────────────────


Action

Branches unconditionally to the specified line.


Syntax

    GOTO { linelabel |  linenumber}


Remarks

The argument  linelabel or  linenumber indicates the line to execute next.
This line must be at the same level of the program. The  GOTO statement
provides a means for branching unconditionally to another line ( linelabel
or  linenumber). A  GOTO statement can branch only to another statement at
the same level within a program. You cannot use  GOTO to enter or exit a
SUB or  FUNCTION procedure 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... NEXT,  IF... THEN... ELSE,  SELECT CASE) instead of  GOTO
statements, because a program with many  GOTO statements can be difficult to
read and debug.


Example

The following example calculates the area of a circle. The program uses the
GOTO statement to repeat the operation.

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

Output

Input 0 to end.
? 5
Area = 78.5
? 0




HEX$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string that represents the hexadecimal value of the decimal
argument.


Syntax

    HEX$( numeric-expression&)


Remarks

The argument  numeric-expression&, which has a decimal value,  is rounded to
an integer or, if it is outside the integer range, a long integer, before
the  HEX$ function evaluates it.


See Also

    OCT$


Example

The following example displays the hexadecimal value of a decimal number:

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

Output

? 32
    32 decimal is 20 hexadecimal.




IF...THEN...ELSE Statement
────────────────────────────────────────────────────────────────────────────


Action

Allows conditional execution, based on the evaluation of a Boolean
expression.


Syntax 1

    IF  condition  THEN  thenpart  « ELSE  elsepart»

Syntax 2

    IF  condition1  THEN
    « statementblock-1»
« ELSEIF  condition2  THEN
    « statementblock-2»»
« ELSE
    « statementblock-n»»
    END  IF


Remarks

Single-Line IF...THEN...ELSE
The single-line form of the statement (Syntax 1) is best used for short,
straightforward tests where only one action is taken.

The single-line form is never required. Any program using single-line  IF...
THEN... ELSE statements can be written using block form.

The following list describes the parts of the single-line form:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    condition                              Any expression that BASIC
                                        evaluates as true (nonzero) or
                                        false (zero).

    thenpart,  elsepart                    The statements or branches
                                        performed when  condition is true
                                        ( thenpart) or false ( elsepart).
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        ( thenpart) or false ( elsepart).
                                        Both parts have the same syntax,
                                        which is described below.



The  thenpart and the  elsepart fields 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 program line label.


Note that  GOTO is optional with a line number, but is required with a line
label.

The  thenpart is executed if  condition is true; if  condition is false,
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, as in the following statement:

IF A > 10 THEN A=A+1:B=B+A:LOCATE 10,22:PRINT B,A

Block IF...THEN...ELSE
The block form (Syntax 2) provides several advantages:

    ■         The block form provides more structure and flexibility than the
            single-line form by allowing conditional branches across several
            lines.

    ■         With the block form, more complex conditions can be tested.

    ■         The block form lets you use longer statements and structures
            within the  THEN... ELSE portion of the statement.

    ■         The block form allows your program's structure to be guided by
            logic rather than by how many statements fit on a line.

Programs that use block  IF... THEN... ELSE are usually easier to read,
maintain, and debug.

The following list describes the parts of the block  IF... THEN... ELSE:
╓┌─────────────────────────────────────┌─────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
    condition1,  condition2              Any expression that BASIC evaluates
                                        as true (nonzero) or false (zero).

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


In executing a block  IF, BASIC tests  condition1, the first Boolean
expression. If the Boolean expression is true (nonzero), the statements
following  THEN are executed. If the first Boolean expression is false
(zero), BASIC begins evaluating each  ELSEIF condition in turn. When BASIC
finds a true condition, the statements following the associated  THEN are
executed. If none of the  ELSEIF conditions is true, the statements
following the  ELSE are executed. After the statements following a  THEN or
ELSE are executed, the program continues with the statement following the
END IF.

The  ELSE and  ELSEIF blocks are both optional. You can have as many  ELSEIF
clauses as you would like in a block  IF. Any of the statement blocks can
contain nested block  IF statements.

BASIC 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 have only a line number or line label in front of them.
The block  must end with an  END IF statement.

For more information, see Chapter 1, "Control-Flow Structures" in the
Programmer's Guide.


See Also

    SELECT CASE


Examples

The following 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"




$INCLUDE Metacommand
────────────────────────────────────────────────────────────────────────────


Action

Instructs the compiler to include statements from another file.


Syntax 1

    REM  $INCLUDE: 'filespec'

Syntax 2

    ' $INCLUDE: 'filespec'


Remarks

The argument  filespec is the name of a BASIC program file, which can
include a path. Use single quotation marks around  filespec. The metacommand
    $INCLUDE instructs the compiler to:

    ■   1. Temporarily switch from processing one file.

    ■   2. Read program statements from the BASIC file named in  filespec.

    ■   3. Return to processing the original file when the end of the included
            file is reached.

Because compilation begins with the line immediately following the line in
which  $INCLUDE occurred,  $INCLUDE should be the last statement on the
line. For example:

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

When you are running a program from the QBX environment, included files must
not contain  SUB or  FUNCTION statements. When you are compiling a program
from the BC command line, included files can contain  SUB or  FUNCTION
statements. Included files created with BASICA must be saved with the , A
option. Included files created with QBX must be in a text (not binary)
format.


Example

See the  DateSerial# function programming example, which uses the  $INCLUDE
metacommand. The  DateSerial# entry is in Part 2, "Add-On-Library
Reference."




INKEY$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a character from the keyboard or some other standard input device.


Syntax

    INKEY$


Remarks

The  INKEY$ function returns a 1- or 2-byte string that contains a character
read from the standard input device, which usually is the keyboard. A null
string is returned if there is no character to return. A one-character
string contains the actual character read from the standard input device,
while a two-character string indicates an extended code, the first character
of which is hexadecimal 00. For a complete list of these codes, see Appendix
A, "Keyboard Scan Codes and ASCII Character Codes."

The character returned by the  INKEY$ function is never displayed on the
screen; instead, all characters are passed through to the program except for
these key combinations:

╓┌─────────────┌──────────────────────────────┌──────────────────────────────╖
Character     Running under QBX              Stand-alone .EXE file
────────────────────────────────────────────────────────────────────────────
Ctrl+Break    Halts program execution.       Halts program execution if
                                                compiled with the /D option;
                                                otherwise, passed through to
                                                program.,

Ctrl+NumLock  Causes program execution to    Same as running under QBX if
                pause until a key is pressed;  compiled with the /D option;
Character     Running under QBX              Stand-alone .EXE file
────────────────────────────────────────────────────────────────────────────
                pause until a key is pressed;  compiled with the /D option;
                then the next key pressed is   otherwise, it is ignored (the
                passed through to the program.  program does not pause and no
                                                keystroke is passed).

Shift+PrtSc   Prints the screen contents.    Prints the screen contents.

Ctrl+Alt+Del  Reboots the system.            Reboots the system.


If you have assigned a string to a function key using the  KEY statement and
you press that function key when  INKEY$ is waiting for a keystroke,  INKEY$
passes the string to the program. Enabled keystroke trapping takes
precedence over the  INKEY$ function.

When you use  INKEY$ with ISAM programs, BASIC performs implicit  CHECKPOINT
operations to minimize data loss in the event of a power failure. The
CHECKPOINT is performed if  INKEY$ fails to successfully retrieve a
character after 65,535 calls, and 20 seconds has expired. A  CHECKPOINT
writes open database buffers to disk.


Example

The following 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$=""


INP Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the byte read from a hardware I/O port.


Syntax

    INP( port)


Remarks

The  INP function complements the  OUT statement, which sends a byte to a
hardware I/O port.

The argument  port identifies the hardware I/O port from which to read the
byte. It must be a numeric expression with an integer value between 0 and
65,535, inclusive.

The  INP function and the  OUT statement give a BASIC program direct control
over the system hardware through the I/O ports.  INP and  OUT must be used
carefully because they  directly manipulate the system hardware.


Note

The  INP function is not available in OS/2 protected mode.


See Also

    OUT,  WAIT


Example

See the  OUT statement programming example, which uses the  INP function.


INPUT$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string of characters read from the specified file.


Syntax

    INPUT$( n , #  filenumber% )


Remarks

The  INPUT$ statement uses the following arguments:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    n                                      The number of characters (bytes)
                                        to read from the file.

    filenumber%                            The number that was used in the
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number that was used in the
                                        OPEN statement 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,  n must be less than or
equal to 32,767.

If  filenumber% is omitted, 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.)

Unlike the  INPUT # statement,  INPUT$ returns all characters it reads.


Example

The following example uses I NPUT$ to read one character at a time from a
file. The input character is converted to standard printable ASCII, if
necessary, and displayed on the screen.

' ASCII codes for tab and line feed.


DEFINT A-Z


CONST HTAB = 9, LFEED = 10


CLS    ' Clear screen.


INPUT "Display which file"; Filename$


OPEN Filename$ FOR INPUT AS #1


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


LOOP


END


INPUT Statement
────────────────────────────────────────────────────────────────────────────


Action

Allows input from the keyboard during program execution.


Syntax



    INPUT ; " promptstring"{;|,}  variablelist

Remarks


The following list describes the parts of the  INPUT statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
;                                       Determines screen location of the
Part                                    Description
────────────────────────────────────────────────────────────────────────────
;                                       Determines screen location of the
                                        text cursor after the program user
                                        enters the last character of input.
                                        A semicolon immediately after
                                        INPUT keeps the cursor at the next
                                        character position. Otherwise, the
                                        cursor skips to the next line.

    promptstring                           A literal string that will be
                                        displayed on the screen before the
                                        program user enters data items
                                        into the data input field.

;                                       Prints a question mark at the end
                                        of  promptstring.

,                                       Prints  promptstring without a
                                        question mark.

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

    variablelist                           An ordered list of variables that
                                        will hold the data items as they
                                        are entered.





The  INPUT statement causes a running program to pause and wait for the user
to enter data from the keyboard.

The number and type of data items required from the user is determined by
the structure of  variablelist. The variables in  variablelist can be made
up of one or more variable names, each separated from the next by a comma.
Each name may refer to:

    ■   A simple numeric variable.

    ■   A simple string variable.

    ■   A numeric or string array element.

    ■   A record element.

The number of entered data items must be the same as the number of variables
in the list. The type of each entered data item must agree with the type of
the variable. If either of these rules is violated, the program will display
the prompt Redo from start and no assignment of input values will be made.

The  INPUT statement determines the number of entered data items in a list
as follows: 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. If this first character is a quotation mark ("), the item is typed as
string data and will consist of all characters between the first quotation
mark and the second. Not all strings have to start with a quotation mark,
however. If the first character of the string is not a quotation mark, it
terminates on a comma, carriage return, or line feed.


Input stored in a record must be entered as single elements. For example:

TYPE Demograph

FullName AS STRING * 25

Age AS INTEGER

END TYPE


DIM Person AS Demograph

INPUT "Enter name and age: "; Person.FullName, Person.Age


You may want to instruct the user on how it is possible to edit a line of
input before pressing the Enter key to submit the line to the program. The
following list describes the key combinations that allow you to move the
cursor, delete text, and insert text on the input line:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Keystrokes                              Edit function
────────────────────────────────────────────────────────────────────────────
Ctrl+M or Enter                         Store input line.

Ctrl+H or Backspace                     Delete the character to the left
                                        of the cursor, unless the cursor
                                        is at the beginning of the input,
                                        in which case it deletes the
                                        character at the cursor.

Ctrl+\ or Right Arrow                   Move cursor one character to the
                                        right.

Ctrl+] or Left Arrow                    Move cursor one character to the
                                        left..

Ctrl+F or Ctrl+Right Arrow              Move cursor one word to the right.

Ctrl+B or Ctrl+Left Arrow               Move cursor one word to the left.

Ctrl+K or Home                          Move cursor to beginning of input
Keystrokes                              Edit function
────────────────────────────────────────────────────────────────────────────
Ctrl+K or Home                          Move cursor to beginning of input
                                        line.

Ctrl+N or End                           Move cursor to end of input line.

Ctrl+R or Ins                           Toggle insert mode on and off.

Ctrl+I or Tab                           Tab right and insert (insert mode
                                        on), or tab right and overwrite
                                        (insert mode off).

Del                                     Delete the character at the cursor.

Ctrl+E or Ctrl+End                      Delete to the end of the line.

Ctrl+U or Esc                           Delete entire line, regardless of
                                        cursor position.

Ctrl+T                                  Toggle function key label display
Keystrokes                              Edit function
────────────────────────────────────────────────────────────────────────────
Ctrl+T                                  Toggle function key label display
                                        on and off at bottom of screen.

Ctrl+C or Ctrl+Break                    Terminate input (exit compiled
                                        program).



When you use  INPUT with ISAM programs, BASIC performs a  CHECKPOINT
operation every 20 seconds during an  INPUT polling loop. A  CHECKPOINT
writes open database buffers to disk.


If the user can be limited to using the Enter and Backspace keys for
editing, you can reduce the size of the .EXE file by linking with the stub
file NOEDIT.OBJ.

If the user will be entering decimal integers only, you can save between
1.6K and 11K in the size of a non-stand-alone .EXE file by linking with the
stub file NOFLTIN.OBJ. This places the following restrictions on user input:

    ■   Decimal numbers only (no leading &H, &O, or & base specifiers).

    ■   No trailing type specifiers ( %,  &,  !,  #,  @, or  $).

    ■   No decimal point, E, or D (for example 1.E2 cannot be used instead of
        the integer 100).


See Also

    INKEY$


Example

This example calculates the area of a circle from its radius. The program
uses the  INPUT statement to allow the user to supply values of the
variable.



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




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


INPUT # Statement
────────────────────────────────────────────────────────────────────────────


Action

Reads data items from a sequential device or file and assigns them to
variables.


Syntax



    INPUT # filenumber%,  variablelist


Remarks

The argument  filenumber% is the number used in the  OPEN statement to open
the file. The argument  variablelist contains the names of the variables
that are assigned values read from the file.

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.


See Also

    INPUT$ Function,  INPUT Statement


Example

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

DEFINT A-Z


DIM Total AS LONG


' Create the required input file.


OPEN "class.dat" FOR OUTPUT AS #1


PRINT #1, 98, 84, 63, 89, 100


CLOSE #1





' Open the file just created.


OPEN "class.dat" FOR INPUT AS #1


DO WHILE NOT EOF(1)'Do until end-of-file is reached.


    Count = Count + 1


    INPUT #1, Score'Get a score from file #1.


    Total = Total + Score


    PRINT Count; Score


LOOP


PRINT "Total students:"; Count; " Average score:"; Total / Count




Output

1  98


2  84


3  63


4  89


5  100


Total students: 5  Average score: 86.8


INSERT Statement
────────────────────────────────────────────────────────────────────────────


Action

Adds a new record to an ISAM table.


Syntax



    INSERT #  filenumber%,  recordvariable

Remarks


The  INSERT statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the table.

    recordvariable                         The record you wish to insert. It
                                        is a variable of the user-defined
                                        type corresponding to the table.





    INSERT places the contents of  recordvariable in the table, and updates the
table's indexes to include the new record. Insert has no effect on the
current position.

BASIC removes trailing spaces from strings used in an insert.


See Also

    DELETE,  OPEN (File I/O),  RETRIEVE


Example

See the programming example for the  SEEKGT,  SEEKGE, and  SEEKEQ
statements, which uses the  INSERT statement.


INSTR Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the character position of the first occurrence of a string in
another string.


Syntax



    INSTR( start%, stringexpression1$,  stringexpression2$)

Remarks


The  INSTR function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    start%                                 An optional offset that sets the
                                        position for starting the search;
                                        start% must be between 1 and
                                        32,767, inclusive. If  start% is
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        32,767, inclusive. If  start% is
                                        not given, the  INSTR function
                                        begins the search at the first
                                        character of  stringexpression1$.

    stringexpression1$                     The string being searched.

    stringexpression2$                     The string to look for.





The arguments  stringexpression1$ and  stringexpression2$ can be string
variables, string expressions, or string literals. The value returned by
INSTR depends on these conditions:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Condition                             Value returned
Condition                             Value returned
────────────────────────────────────────────────────────────────────────────
    stringexpression2$ found in          The position at which the match is
stringexpression1$                    found

    start% greater than length of        0
stringexpression1$

    stringexpression1$ is a null string  0

    stringexpression2$ cannot be found   0

    stringexpression2$ is a null string   start% (if given); otherwise, 1





Use the  LEN function to find the length of  stringexpression1$.


See Also

    LEN


Example


The following example uses  INSTR and  UCASE$ to determine a person's gender
from a courtesy title (Mr., Mrs., or Ms.):

CLS    ' Clear screen.


DO


    INPUT "Enter name with courtesy title (Mr., Mrs., or Ms.): ", Nm$


LOOP UNTIL LEN(Nm$) >= 3





Nm$ = UCASE$(Nm$) ' Convert lowercase letters to uppercase.


' 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 gender, query user.


    DO


        INPUT "Enter sex (M/F): ", Sex$


        Sex$ = UCASE$(Sex$)


    LOOP WHILE Sex$ <> "M" AND Sex$ <> "F"


END IF


PRINT "Sex is "; Sex$




Output

Enter name: Ms. Elspeth Brandtkeep


Sex is F





Enter name: Dr. Richard Science


Enter sex (M/F): M


Sex is M


INT Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the largest integer less than or equal to a numeric expression.


Syntax



    INT( numeric-expression)


Remarks

The  INT function removes the fractional part of its argument.


See Also

    CINT,  FIX


Example

The following example compares 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




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





Interrupt, InterruptX Routines
────────────────────────────────────────────────────────────────────────────


Action

Allow BASIC programs to perform DOS system calls.


Syntax



    CALL  Interrupt ( interruptnum%,  inregs,  outregs)


    CALL  InterruptX ( interruptnum%,  inregs,  outregs)

Remarks

The  Interrupt routines use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    interruptnum%                          A DOS interrupt number that is an
                                        integer between 0 and 255.

    inregs                                 The register values before the
                                        interrupt is performed;  inregs is
                                        declared as type RegType or
                                        RegTypeX. The user-defined types
                                        RegType and RegTypeX are described
                                        below.

    outregs                                The register values after the
                                        interrupt is performed;  outregs
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        interrupt is performed;  outregs
                                        is declared as type RegType or
                                        RegTypeX. The user-defined types
                                        RegType and RegTypeX are described
                                        below.



The following statement defines RegTypeX:

TYPE RegTypeX


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

The following statement defines RegType (the DS and ES registers are not
included):


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


END TYPE

Each element of the type corresponds to a CPU element.


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

The  Interrupt and  InterruptX routines 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.

To use  Interrupt or  InterruptX in the QBX environment, use the QBX.QLB
Quick library. To use  Interrupt or  InterruptX outside of the QBX
environment, link your program with the QBX.LIB file.

The QBX.BI header file contains the necessary declarations for  Interrupt
and  InterruptX .


Note

The  Interrupt and  InterruptX routines are not available in OS/2 protected
mode. For OS/2 protected mode, replace  Interrupt with the equivalent OS/2
function invocations. For more information about doing OS/2 calls from
BASIC, see Chapter 14, "OS/2 Programming" in the  Programmer's Guide.


Example

The following example uses  Interrupt to determine the current drive and the
amount of free space remaining on the drive.

To use  Interrupt, you must load the Quick library QBX.QLB using the /L
option when you begin QBX. You also must include the QBX.BI header file as
shown below:

' $INCLUDE: 'QBX.BI'


DIM regs AS RegType' Define registers.





' Get current drive info.


regs.ax = &H1900


CALL Interrupt(&H21, regs, regs)


' Convert drive info to readable form.


Drive$ = CHR$((regs.ax AND &HFF) + 65) + ":"





' Get disk's free space.


regs.ax = &H3600


regs.dx = ASC(UCASE$(Drive$)) - 64


CALL Interrupt(&H21, regs, regs)


' Decipher the results.


SectorsInCluster = regs.ax


BytesInSector = regs.cx


IF regs.dx >= 0 THEN


ClustersInDrive = regs.dx


ELSE


ClustersInDrive = regs.dx + 65536


END IF


IF regs.bx >= 0 THEN


ClustersAvailable = regs.bx


ELSE


ClustersAvailable = regx.bx + 65536


END IF


Freespace = ClustersAvailable * SectorsInCluster * BytesInSector





' Report results.


CLS


PRINT "Drive "; Drive$; " has a total of";


PRINT USING "###,###,###"; Freespace;


PRINT " bytes remaining free."


IOCTL$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns current status information from a device driver.


Syntax



    IOCTL$(#  filenumber%)

Remarks


The argument  filenumber% is the BASIC file number used to open the device.

The  IOCTL$ function is most frequently used to test whether an  IOCTL
statement succeeded or failed, or to obtain current status information.

You can 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 depends on the specific device driver. See the
device driver documentation to find out what status information the device
driver can send.

The  IOCTL$ function works only if all of the following conditions are met:

    ■         The device driver is installed.

    ■         The device driver states that it processes  IOCTL strings. See
            the documentation for the driver.

    ■         BASIC performed an  OPEN operation 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 whether the specific driver accepts the command. If the driver
does not process  IOCTL strings, BASIC generates the error message Illegal
function call.


Note

BASIC devices (LPT n, COM n, SCRN, CONS, PIPE) and DOS block devices (A
through Z) do not support  IOCTL.

The  IOCTL statement is not available in OS/2 protected mode. However, you
can achieve the same effect by directly invoking the DosDevIOCtl OS/2
functions.


See Also

    IOCTL Statement


Example

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

OPEN "\DEV\ENGINE" FOR OUTPUT AS #1


IOCTL #1, "RAW"' Tells the device that the data is raw.





' If the character driver "ENGINE" responds "false" from the raw data


' mode in the IOCTL statement, then the file is closed.


IF IOCTL$(1) = "0" THEN CLOSE 1


IOCTL Statement
────────────────────────────────────────────────────────────────────────────


Action

Transmits a control data string to a device driver.


Syntax



    IOCTL #  filenumber%,  string$

Remarks


The  IOCTL statement uses the following arguments:

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Argument          Description
────────────────────────────────────────────────────────────────────────────
    filenumber%      The BASIC file number used to open the device.
    string$          The command sent to the device.




Commands are specific to the device driver. See the documentation for the
device driver for a description of the valid  IOCTL commands. An  IOCTL
control data string can be up to 32,767 bytes long.

The  IOCTL statement works only if all of the following conditions are met:

    ■         The device driver is installed.

    ■         The device driver states that it processes  IOCTL strings. See
            the documentation for the driver.  You also can test for  IOCTL
            support through DOS function &H44 by using interrupt &H21 and
            the  INTERRUPT routine. For more information about interrupt
            &H21, function &H44, see see the  Microsoft MS-DOS  Programmer's
                Reference, or books such as  Advanced MS-DOS or  The Peter
            Norton Guide to the IBM PC.

    ■         BASIC performed an  OPEN operation 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 whether the specific driver accepts the command. If the driver
does not process  IOCTL strings, BASIC generates the error message Illegal
function call.


Note

BASIC devices (LPT n, COM n, SCRN, CONS, PIPE) and DOS block devices (A
through Z) do not support  IOCTL.

The  IOCTL statement is not available in OS/2 protected mode. However, you
can achieve the same effect by directly invoking the DosDevIOCtl OS/2
function.


See Also

    IOCTL$ Function


Example

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


KEY Statements (Assignment)
────────────────────────────────────────────────────────────────────────────


Action

Assign soft-key string values to function keys, then display the values and
enable or disable the function-key display line.


Syntax



    KEY  n%,  stringexpression$


    KEY ON

    KEY OFF
KEY LIST


Remarks


The argument  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 statements 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, BASIC generates the
error message Illegal function call, and the previous key string expression
is retained.

You can 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
Statement                               Action
────────────────────────────────────────────────────────────────────────────
                                        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$ all can be
used to read the string produced by pressing the soft key.

See Also

    ON  event; Appendix A, "Keyboard Scan Codes and ASCII Character Codes"


Examples

The following examples show how to assign values to soft keys. First 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.

KEY 4, "MENU" + CHR$(13) ' Assigns to soft key 4 the string

KEY LIST' "MENU" followed by a carriage return.

KEY 4, ""  ' Disables soft key 4.

KEY LIST

This is an example of using  KEY statements to set up one-key equivalents of
menu selections. For example, pressing the F1 key 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)   ' String followed by Enter.

NEXT I



' Print menu.

PRINT "                 Main Menu" : PRINT

PRINT "           Add to list (F1)"

PRINT "           Delete from list (F2)"

PRINT "           Quit (F3)" : PRINT



' Get input and respond.

DO

    LOCATE 7,1 : PRINT SPACE$(50);

    LOCATE 7,1 : INPUT "             Enter your choice:", R$

    SELECT CASE R$

        CASE "Add", "Delete"

            LOCATE 10,1 : PRINT SPACE$(15);

            LOCATE 10,1 : PRINT R$;

        CASE "Quit"

            EXIT DO

        CASE ELSE

            LOCATE 10,1 : PRINT "Enter first word or press key."

    END SELECT

LOOP




KEY Statements (Event Trapping)
────────────────────────────────────────────────────────────────────────────



Action

Enable, disable, or suspend trapping of specified keys.


Syntax



    KEY( n%)  ON


    KEY( n%)  OFF


    KEY( n%)  STOP


Remarks


The argument  n% is an integer expression that is the number of a function
key, a direction key, or a user-defined key. The values of  n% are as
follows:

╓┌──────────────────┌────────────────────────────────────────────────────────╖
    n%                Value
────────────────────────────────────────────────────────────────────────────
0                  All keys listed in this table
1-10               F1-F10
11                 Up Arrow key
12                 Left Arrow key
13                 Right Arrow key
14\~               Down Arrow key
15-25              User-defined keys
30-31              F11-F12 on 101-key keyboards




The  KEY( n%)  ON statement enables trapping of function keys, direction
keys, and user-defined keys. If key  n% is pressed after a  KEY( n%)  ON
statement, the routine specified in the  ON  KEY statement is executed.

    KEY( n%  OFF disables trapping of key  n%. No key trapping takes place
until another  KEY( n%)  ON statement is executed. Events occurring while
trapping is off are ignored.

    KEY( n%)  STOP suspends trapping of key  n%. No trapping takes place until
a  KEY( n%)  ON statement is executed. Events occurring while trapping is
suspended are remembered and processed when the next  KEY( n%)  ON statement
is executed. However, remembered events are lost if  KEY( n%)  OFF is
executed.

When a key-event trap occurs (that is, the  GOSUB is performed), an
automatic  KEY( n%)  STOP is executed so that recursive traps cannot take
place. The  RETURN operation from the trapping routine automatically
performs a  KEY( n%)  ON statement unless an explicit  KEY( n%)  OFF was
performed inside the subroutine.

For more information on event trapping, see Chapter 9, "Event Handling" in
the  Programmer's Guide.


In addition to providing the preassigned key numbers 1-14 (plus 30 and 31 on
the 101-key keyboard), BASIC enables you to create user-defined keys. You do
this by assigning the numbers 15-25 to any of the remaining keys on the
keyboard. Use the  KEY statement (assignment) to create user-defined keys.

You also can set a trap for "shifted" keys. A key is shifted when you press
it simultaneously with one or more of the special keys Shift, Ctrl, or Alt
after pressing NumLock or Caps Lock. Use the  KEY statement (assignment) to
define shifted keys before you trap them. The syntax for  KEY (assignment)
is:



    KEY  n%,  CHR$ ( keyboardflag) +  CHR$ ( scancode)

The argument  n% is in the range 15-25 to indicate a user-defined key. The
argument  keyboardflag can be any combination of the following values:


╓┌─────────────────────┌─────────────────────────────────────────────────────╖
Value                 Key
────────────────────────────────────────────────────────────────────────────
Value                 Key
────────────────────────────────────────────────────────────────────────────
0                     No keyboard flag
1, 2, or 3            Either Shift key
4                     Ctrl
8                     Alt
32                    NumLock
64                    Caps Lock
128                   101-key keyboard extended keys




You can add the values together to test for multiple shift states. A
keyboardflag value of 12 would test for both Ctrl and Alt being pressed, for
example.

To define Shift, Ctrl, Alt, NumLock, or Caps Lock as a user-defined key (by
itself, not in combination with another key), use a keyboard flag of 0. For
example, to define Alt as a user-defined key, use the following statement:

KEY CHR$(0) + CHR$(56)

To define Alt + Alt as a user-defined key (the second Alt will be trapped
when it is pressed only if the first Alt key is already being pressed), use
the following statement:

KEY CHR$(8) + CHR$(56)

Because key trapping assumes the left and right Shift keys are the same, you
can use 1, 2, or 3 to indicate a Shift key.

The argument  scancode is a number that identifies one of the 83 keys to
trap, as shown in the following table:


Keyboard Scan Codes
╓┌──────────┌─────┌────────────┌─────┌────────────┌──────────────────────────╖
Key        Code  Key          Code  Key          Code
────────────────────────────────────────────────────────────────────────────
Esc        1     Ctrl         29    Spacebar     57
! or 1     2     A            30    Caps Lock    58
Key        Code  Key          Code  Key          Code
────────────────────────────────────────────────────────────────────────────
! or 1     2     A            30    Caps Lock    58
@ or 2     3     S            31    F1           59
# or 3     4     D            32    F2           60
$ or 4     5     F            33    F3           61
% or 5     6     G            34    F4           62
^ or 6     7     H            35    F5           63
& or 7     8     J            36    F6           64
* or 8     9     K            37    F7           65
( or 9     10    L            38    F8           66
) or 0     11    : or ;       39    F9           67
_ or -     12    " or '       40    F10          68
+ or =     13    ~ or `       41    NumLock      69
Backspace  14    Left Shift   42    Scroll Lock  70
Tab        15    | or \       43    Home or 7    71
Q          16    Z            44    Up or 8      72
W          17    X            45    PgUp or 9    73
E          18    C            46    Gray  -      74
R          19    V            47    Left or 4    75
T          20    B            48    Center or 5  76
Key        Code  Key          Code  Key          Code
────────────────────────────────────────────────────────────────────────────
T          20    B            48    Center or 5  76
Y          21    N            49    Right or 6   77
U          22    M            50    Gray +       78
I          23    < or ,       51    End or 1     79
O          24    > or .       52    Down or 2    80
P          25    ? or /       53    PgDn or 3    81
{ or [     26    Right Shift  54    Ins or 0     82
} or ]     27    PrtSc or *   55    Del or .     83
Enter      28    Alt          56




Note


The scan codes in the preceding table are equivalent to the first column of
the scan code table in Appendix A, "Keyboard Scan Codes and ASCII Character
Codes." The codes in the other columns of the table in the appendix should
not be used for key trapping.


See Also


    KEY (Assignment),  ON  event


Example

The following example traps the Down Arrow key and Ctrl+s (Control key and
lowercase "s"). To trap the combination of the Ctrl key and uppercase "s",
trap Ctrl+Shift and

I = 0

CLS' Clear screen.

PRINT "Press Down Arrow key to end."

KEY 15, CHR$(&H4) + CHR$(&H1F)

KEY(15) ON ' Trap Ctrl+s.

KEY(14) ON ' Trap Down Arrow key.

ON KEY(15) GOSUB Keytrap

ON KEY(14) GOSUB Endprog

Idle: GOTO Idle' Endless loop.



Keytrap:   ' Counts the number of times Ctrl+s pressed.

I = I + 1

RETURN



Endprog:

PRINT "CTRL+s trapped"; I; "times"

END

RETURN


KILL Statement
────────────────────────────────────────────────────────────────────────────


Action

Deletes files from a disk.


Syntax



    KILL  filespec$


Remarks


The  KILL statement is similar to the DOS ERASE or DEL command.

    KILL is used for all types of disk files: program files, random-access data
files, and sequential data files. The  filespec$ is a string expression that
can contain a path and question marks (?) or asterisks (*) used as DOS
wildcards. A question mark matches any single character in the filename or
extension. An asterisk matches one or more characters.

    KILL deletes files only. To delete directories, use the DOS RMDIR command
or BASIC  RMDIR statement. 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 wildcards with  KILL. You can delete files
unintentionally with the wildcard characters.


See Also

    FILES,  RMDIR


Examples

The first example uses wildcard characters with  KILL. It will not work
properly 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.



The following example deletes the file specified on the command line:


DEFINT A-Z

CLS    ' Clear screen.

ON ERROR GOTO Errorhandle' Set up error handling.

FileName$ = COMMAND$ ' Get filename.

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


LBOUND Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the lower bound (smallest available subscript) for the indicated
dimension of an array.


Syntax



    LBOUND( array ,  dimension% )


Remarks


The  LBOUND function is used with the  UBOUND function to determine the size
of an array.  LBOUND takes the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    array                                  The name of the array variable to
                                        be tested.

Argument                                Description
────────────────────────────────────────────────────────────────────────────

    dimension%                             An integer ranging from 1 to the
                                        number of dimensions in  array;
                                        indicates which dimension's lower
                                        bound is returned. Use 1 for the
                                        first dimension, 2 for the second
                                        dimension, and so on. This
                                        argument is optional for
                                        one-dimensional arrays.





    LBOUND returns the values listed below for an array with the following
dimensions:

DIM A(1 TO 100, 0 TO 3, -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 can have any
integer value as a lower bound.

You can use the shortened syntax  LBOUND( array) for one-dimensional arrays,
because the default value for  dimension% is 1. Use the  UBOUND function to
find the upper limit of an array dimension.


See Also

    DIM,  OPTION BASE,  UBOUND


Example

See the  UBOUND function programming example, which uses the  LBOUND
function.


LCASE$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string with all letters in lowercase.


Syntax



    LCASE$ ( stringexpression$)


Remarks


The  LCASE$ function takes a string variable, string constant, or string
expression as its single argument.  LCASE$ works with both variable- and
fixed-length strings.

    LCASE$ and  UCASE$ are helpful in making string comparisons that are not
case sensitive.


See Also

    UCASE$


Example

The following example converts uppercase characters in a string to
lowercase:

CLS                ' Clear screen.

READ Word$

PRINT LCASE$(Word$);

DATA "THIS IS THE STRING in lower case."



Outputthis is the string in lower case.





LEFT$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string consisting of the leftmost  n characters of a string.


Syntax



    LEFT$( stringexpression$,  n%)


Remarks


The argument  stringexpression$ can be any string variable, 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 0, the null string (length zero) is returned.

If  n% is greater than or equal to the number of characters in
stringexpression$, the entire string is returned. To find the number of
characters in  stringexpression$, use  LEN( stringexpression$) .


See Also

    MID$ Function,  RIGHT$ Function


Example

The following example prints the leftmost five characters of A$:

CLS                ' Clear screen.

A$="BASIC LANGUAGE"

B$=LEFT$(A$, 5)

PRINT B$



Output

BASIC



LEN Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the number of characters in a string or the number of bytes required
by a variable.


Syntax 1

    LEN( stringexpression$)

Syntax 2

    LEN( variable)


Remarks


In the first form,  LEN returns the number of characters in the argument
stringexpression$. The second syntax returns the number of bytes required by
a BASIC variable. This syntax is particularly useful for determining the
correct record size of a random-access file.

When you pass a string length as an argument to a procedure that may change
the value of the argument, be sure to pass it by value instead of by
reference, which is the BASIC default. Do this by placing parentheses around
LEN(N$), e.g.,(LEN(N%)). Alternatively, you can use a temporary variable,
e.g. N% = LEN(N$), and pass the temporary variable in the standard way.
Failure to use these techniques will corrupt string space if you change the
value of the passed argument.


Example

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



Output

A string: 9


Integer: 2

Long: 4

Single: 4

Double: 8

EmpRec: 22


Let Statement
────────────────────────────────────────────────────────────────────────────


Action

Assigns the value of an expression to a variable.


Syntax



    LET  variable= expression


Remarks


Notice that the keyword  LET is optional. The equal sign in the statement is
enough to inform BASIC that the statement is an assignment statement.

The  LET statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               A variable.

    expression                             An expression that provides the
                                        value to assign to the variable.





    LET statements can be used with record variables only when both variables
are the same user-defined type. Use the  LSET statement to assign record
variables of different user-defined types.


See Also

    LSET


Examples

The first example below shows the use of the optional  LET keyword:

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:

D = 12

E = 12 - 2

F = 12 - 4

SUM = D + E + F

PRINT D E F SUM



Output

12 10 8 30



LINE Statement
────────────────────────────────────────────────────────────────────────────


Action

Draws a line or box on the screen.


Syntax



    LINE  STEP ( x1!, y1!)   -  STEP ( x2!, y2!)  ,  color&  , B F ,  style%


Remarks


The coordinates ( x1!, y1!) and ( x2!, y2!) specify the end points of the
line; note that the order in which these end points 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. For example, if the most-recent point referred to by the program were
(10,10), then the following statement would draw a line from (10,10) to the
point with an x coordinate equal to 10 + 10 and a y coordinate equal to 10 +
5, or (20,15):

LINE -STEP (10,5)

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

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
LINE -(50,50)                     Draws from (10,10) to (50,50).
LINE -STEP(50,50)                 Draws from (10,10) to (60,60).
LINE (25,25)-STEP(50,50)          Draws from (25,25) to (75,75).
LINE STEP(25,25)-STEP(50,50)      Draws from (35,35) to (85,85).
LINE STEP(25,25)-(50,50)          Draws from (35,35) to (50,50).




The argument  color% is the number of the color in which the line is drawn.
(If the B or BF option is used, the box is drawn in this color.) For
information on valid colors, see the  SCREEN statement.

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 argument  style% is a 16-bit integer mask used to put pixels on the
screen. Using  style% 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 zero 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 within the current viewport,
the line segment to that point is drawn to the border of the viewport.

For more information on the  LINE statement, see Chapter 5, "Graphics" in
the  Programmer's Guide.


See Also

    CIRCLE,  PSET,  SCREEN Statement


Examples

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

SCREEN 1' Set up the screen mode.



LINE -(X2, Y2)' Draw a line (in the foreground color)

' from the most recent point to X2,Y2.

DO: LOOP WHILE INKEY$ = ""

CLS

LINE(0, 0)-(319, 199)' Draw a diagonal line across the screen.

DO: LOOP WHILE INKEY$ = ""

CLS

LINE(0, 100)-(319, 100)' Draw a horizontal line across the screen.

DO: LOOP WHILE INKEY$ = ""

CLS

LINE(10, 10)-(20, 20), 2 ' Draw a line in color 2.

DO: LOOP WHILE INKEY$ = ""

CLS

FOR X = 0 to 319' Draw an alternating pattern

    LINE(X, 0)-(X, 199), X AND 1' (line on/line off) on mono-

NEXT' chrome display.

DO: LOOP WHILE INKEY$ = ""

CLS

LINE (0, 0)-(100, 100),, B' Draw a box in the foreground color

' (note that the color is not included).

DO: LOOP WHILE INKEY$ = ""

CLS

LINE STEP(0,0)-STEP(200,200),2,BF ' Draw a filled box in color

' 2 (coordinates are given as

' offsets with the STEP option).

DO: LOOP WHILE INKEY$ = ""

CLS

LINE(0,0)-(160,100),3,,&HFF00' Draw a dashed line from the

' upper-left corner to the

' center of the screen in color 3.


LINE INPUT Statement
────────────────────────────────────────────────────────────────────────────


Action

Enters an entire line (up to 255 characters) from the keyboard to a string
variable, without the use of delimiters.


Syntax



    LINE INPUT ; " promptstring";  stringvariable


Remarks


The argument  promptstring is a string constant. After  promptstring is
displayed on the screen, entry of data items into the data input field is
accepted. A question mark is not printed unless it is part of  promptstring.
All input from the end of  promptstring to the carriage return is assigned
to  stringvariable.

A semicolon immediately after the  LINE INPUT keywords keeps the cursor at
the next character position after the user presses Enter. Omitting a
semicolon causes the cursor to skip to the next line.

    LINE INPUT uses the same editing characters as  INPUT.


See Also

    INPUT$ Function,  INPUT Statement


Example

See the  DEF SEG statement programming example, which uses the  LINE INPUT
statement.


LINE INPUT # Statement
────────────────────────────────────────────────────────────────────────────


Action

Reads an entire line from a sequential file into a string variable.


Syntax



    LINE INPUT # filenumber%,  stringvariable$


Remarks


The  LINE INPUT  # statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    stringvariable$                        The variable the line is assigned
                                        to.

Argument                                Description
────────────────────────────────────────────────────────────────────────────



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.

    LINE INPUT # is especially useful if a text file is being read one line at
a time.


See Also

    INPUT$ Function,  INPUT Statement,  INPUT  # Statement,  LINE INPUT


Example

The following example creates a data file consisting of customer records
that include LAST NAME, FIRST NAME, AGE, and SEX. After the file is
complete, the  LINE  INPUT  # statement is used to read the individual
records so they can be displayed on the screen.

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.


    PRINT REC$            ' Print the records on the screen.


LOOP


' Remove file from disk.


CLOSE #1


KILL "LIST"




Output



CUSTOMER INFORMATION:





    LAST NAME:  Saintsbury


    FIRST NAME: Aloysius


    AGE:        35


    SEX:        m


Add another? y





    LAST NAME:  Frangio


    FIRST NAME: Louisa


    AGE:        27


    SEX:        f


Add another? n





Records in file:





"Saintsbury","Aloysius","35","M"


"Frangio","Louisa","27","F"


LOC Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the current position within an open file.


Syntax



    LOC( filenumber%)


Remarks


The argument  filenumber% is the number of an open file or device. 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 communications device,  LOC 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 an end-of-file is received. The
end-of-file itself is not queued and cannot be read. If you attempt to read
the end-of-file, BASIC generates the error message Input past end of file.
In binary mode, the end-of-file character is ignored and the entire file can
be read.

For a PIPE device,  LOC returns 1 if any data are available in the PIPE
queue.


Note

The  LOC function cannot be used on ISAM tables, or the SCRN, KYBD, or LPT n
devices.


See Also

    EOF,  LOF,  OPEN (File I/O)


Example

The following example stops the program if the current file position is
beyond 50. Note that this example is incomplete.

IF LOC(1) > 50 THEN STOP


LOCATE Statement
────────────────────────────────────────────────────────────────────────────


Action

Moves the cursor to the specified position on the screen.


Syntax



    LOCATE  row% ,  column% ,  cursor% ,  start% ,  stop%


Remarks


The  LOCATE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    row%                                   The number of a row on the screen;
                                            row% is a numeric expression
                                        returning an integer. If  row% is
                                        not specified, the row location of
                                        the cursor does not change.

    column%                                The number of a column on the
                                        screen;  column% is a numeric
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        screen;  column% is a numeric
                                        expression returning an integer.
                                        If  column% is not specified, the
                                        column location of the cursor does
                                        not change.

    cursor%                                A Boolean value indicating whether
                                        the cursor is visible or not. A
                                        value of 0 indicates cursor  off;
                                        a value of 1 indicates cursor  on.

    start%,  stop%                         The starting and ending raster
                                        scan lines of the cursor on the
                                        screen. The arguments  start% and
                                        stop% redefine the cursor size and
                                        must be numeric expressions
                                        returning an integer between 0 and
                                        31, inclusive.

Argument                                Description
────────────────────────────────────────────────────────────────────────────





You can omit any argument from the statement except that if  stop% is
specified,  start% also must be specified. When you omit  row% or  column%,
LOCATE leaves the cursor at the row or column where it was moved by the most
recently executed input or output statement (such as  LOCATE,  PRINT, or
INPUT). When you omit other arguments, BASIC 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. In OS/2 real mode and under DOS,  LOCATE assumes there are
eight lines (numbered 0 to 7) in the cursor. In OS/2 protected mode there
are 16 lines (numbered 0 to 15).

When  start% is greater than  stop%,  LOCATE produces a two-part cursor. If
the  start% line is given but the  stop% line is omitted,  stop% assumes the
same value as  start%. A value of 8 for both  start% and  stop% produces the
underline cursor. The maximum cursor size is determined by the character
block size of the screen mode in use. Setting  start% greater than  stop%
displays a full-height cursor on VGA-equipped systems.

For screen mode information, see the entry for the  SCREEN statement.

The last line on the screen is reserved for the soft-key display and is not
accessible to the cursor unless the soft-key display is off ( KEY OFF) and
LOCATE is used with  PRINT to write on the line.


See Also


    CSRLIN,  POS


Examples

The first example 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$ = ""


LOCATE 1,1 ' Moves cursor to upper-left corner of the screen.


PRINT "C"


DO


LOOP WHILE INKEY$ = ""


LOCATE , ,1' Makes cursor visible; position remains unchanged.


PRINT "C"


DO


LOOP WHILE INKEY$ = ""


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$ = ""


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$ = ""


END

The following example prints a menu on the screen, then waits for input in
the allowable range (1-4). If a number outside that range is entered, the
program continues to prompt for a selection.


Note that this program is incomplete.

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


SELECT CASE VAL(CH$)


CASE 1


CALL Add


CASE 2


CALL Search


CASE 3


CALL Hotel


CASE 4


CALL Quit


END SELECT


LOOP WHILE NOT ENDPROG


    .


    .


    .


END


LOCK...UNLOCK Statement
────────────────────────────────────────────────────────────────────────────


Action

Controls access by other processes to all or part of an opened file.


Syntax



    LOCK #  filenumber% ,{ record& |  start&  TO  end&}
.

.

.



    UNLOCK #  filenumber% ,{ record& |  start&  TO  end&}


Remarks


These statements are used in networked environments where several processes
might need access to the same file. The  LOCK and  UNLOCK statements use the
following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    record&                                The number of the record or byte
                                        to be locked. The argument
                                        record& can be any number from 1
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        record& can be any number from 1
                                        to 2,147,483,647 (equivalent to
                                        231 -1). A record can 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,  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,  record&,  start&, and  end& represent the number
of a record relative to the beginning of the file. The first record is
record 1.

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

The  LOCK and  UNLOCK statements are always used in pairs. The arguments to
LOCK and  UNLOCK must match exactly.

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& locks the entire file, while  UNLOCK
with no  record& unlocks the entire file.

    LOCK and  UNLOCK execute only at run time if you are using OS/2 or versions
of DOS that support networking (version 3.1 or later). In DOS, you must run
the SHARE.EXE program to enable locking operations. Using earlier versions
of DOS causes BASIC to generate the error message Feature unavailable if
LOCK and  UNLOCK are executed.


Warning

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.
Do not use  LOCK and  UNLOCK on devices or ISAM tables.


If you attempt to access a file that is locked, BASIC may generate the
following error messages:

Bad record number

Permission denied


Example

The following example illustrates the use of the  LOCK and  UNLOCK
statements. The program creates a sample data record in a random-access
file. Once the sample record is created and closed, the program again opens
the file to allow customer information to be updated. As a record is opened,
it is locked to prevent use by another terminal that has access to the same
file. After the update is complete, the record is unlocked, again allowing
modifications by others with access.

' Define the record.


TYPE AccountRec


    Payer AS STRING * 20


    Address AS STRING * 20


    Place AS STRING * 20


    Owe AS SINGLE


END TYPE





DIM CustRec AS AccountRec





' This section creates a sample record to use.


ON ERROR GOTO ErrHandler





OPEN "MONITOR" FOR RANDOM SHARED AS #1 LEN = LEN(CustRec)





CustRec.Payer = "George Washington"


CustRec.Address = "1 Cherry Tree Lane"


CustRec.Place = "Mt. Vernon, VA"


CustRec.Owe = 12!


PUT #1, 1, CustRec          ' Put one record in the file.


CLOSE #1





' This section opens the sample record for updating.


OPEN "MONITOR" FOR RANDOM SHARED AS #1 LEN = LEN(CustRec)


DO


    Number% = 0             ' Reset to zero.


    DO UNTIL Number% = 1    ' Force user to input 1.


        CLS : LOCATE 10, 10


        INPUT "Customer Number?   #"; Number%


    LOOP


    ' Lock the current record so another process


    ' doesn't change it while you're using it.


    LOCK #1, Number%


    GET #1, Number%, CustRec


    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%, CustRec


    ' Unlock the record.


    UNLOCK #1, Number%


    LOCATE 17, 10: INPUT "Update another? ", Continue$


    Update$ = UCASE$(LEFT$(Continue$, 1))


LOOP WHILE Update$ = "Y"


CLOSE #1


KILL "MONITOR"' Remove file from disk.


END





ErrHandler:


IF ERR = 70 THEN        ' Permission-denied error.


    CLS


    PRINT "You must run SHARE.EXE before running this example."


    PRINT "Exit the programming environment, run SHARE.EXE, and"


    PRINT "reenter the programming environment to run this"


    PRINT "example. Do not shell to DOS to run SHARE.EXE or you"


    PRINT "may not be able to run other programs until you reboot."


END IF


END


LOF Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the size of an open file (in bytes), the number of records in an
ISAM table, or, when used with the  OPEN  COM statement, the number of bytes
free in the output buffer.


Syntax



    LOF( filenumber%)


Remarks


The argument  filenumber% is the number used in the  OPEN statement to open
the file, device, or ISAM table.


Important

    LOF can be used only on disk files, ISAM tables, or COM devices. It cannot
be used with the BASIC devices SCRN, KYBD, CONS, LPT n, or PIPE.


See Also

    BOF,  EOF,  LOC,  OPEN (File I/O)


Example

See the programming example for the  SEEKGT,  SEEKGE, and  SEEKEQ
statements, which uses the  LOF function in the context of ISAM.


LOG Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the natural logarithm of a numeric expression.


Syntax



    LOG( numeric-expression)


Remarks


The argument  numeric-expression must be greater than zero. The natural
logarithm is the logarithm to the base  e. The constant  e is approximately
equal to 2.718282.

    LOG is calculated in single precision if  numeric-expression is an integer
or single-precision value. If you use any other numeric type,  LOG is
calculated in double precision.

You can calculate base-10 logarithms by dividing the natural logarithm of
the number by the natural logarithm of 10. The following  FUNCTION procedure
calculates base-10 logarithms:

FUNCTION Log10(X) STATIC

    Log10=LOG(X)/LOG(10#)

END FUNCTION


See Also


    EXP


Example

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


PRINT




Output



2.718282       1       2       3





LPOS Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the number of characters sent to the printer since the last carriage
return was sent.


Syntax



    LPOS( n%)


Remarks


The argument  n% is an integer expression with a value between 0 and 3 that
indicates one of the printers. For example, LPT1 would be tested with
LPOS(1) or LPOS(0), LPT2 would be tested with LPOS(2), and 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.


Example

See the  LPRINT statement programming example, which uses the  LPOS
function.


LPRINT, LPRINT USING Statements
────────────────────────────────────────────────────────────────────────────


Action

Print data on the printer LPT1.


Syntax



    LPRINT  expressionlist {;|,}


    LPRINT  USING  formatstring$;  expressionlist {;|,}


Remarks


These statements function in the same way as the  PRINT and  PRINT USING
statements except that output goes to the printer.

The following list describes the parts of the  LPRINT and  LPRINT USING
statements:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    expressionlist                         The values that are printed on
                                        printer LPT1.

    formatstring$                          Specifies the format, using the
                                        same formatting characters as the
                                        PRINT USING statement.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        PRINT USING statement.

{;|,}                                   Determines the location on the
                                        page of the first value printed by
                                        the next statement to use LPT1
                                        (such as the next  LPRINT
                                        statement or a  PRINT # or  WRITE
                                        # directing data to LPT1). The
                                        semicolon means to print
                                        immediately after the last value
                                        in this  LPRINT statement; the
                                        comma means to print at the start
                                        of the next unoccupied print zone.



The printer output from an  LPRINT statement will be the same as the screen
output from a  PRINT statement, if both statements have the same
expressionlist values and output-line width.

The printer output from an  LPRINT  USING statement will be the same as the
screen output from a  PRINT  USING statement, if both statements have the
same values for  formatstring$,  expressionlist, and output-line width.

The  LPRINT statement assumes an 80-character-wide printer. This width can
be changed with a  WIDTH statement.

If you use  LPRINT with no arguments, a blank line is printed.


Warning

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


BASICA

An LPRINT CHR$(13) statement actually outputs both CHR$(13) and CHR$(10).
This feature was created to provide compatibility with BASICA.


See Also


    PRINT, PRINT USING,  WIDTH


Example

The following example prompts the user for team names and the names of
players on each team. Then it 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


LPRINT : LPRINT "     ";  ' head is past column 55.


ELSE


LPRINT ", ";' Otherwise, print a comma.


END IF


END IF


NEXT P


LPRINT STRING$(80-LPOS(0)-LEN(TEAM$),"."); TEAM$


NEXT T


LSET Statement
────────────────────────────────────────────────────────────────────────────


Action

Moves data from memory to a random-access file buffer (in preparation for a
PUT statement), copies one record variable to another, or left-justifies the
value of a string in a string variable.


Syntax 1

    LSET  stringvariable$= stringexpression$

Syntax 2




    LSET  recordvariable1= recordvariable2


Remarks


The  LSET statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    stringvariable$                        Usually a random-access file field
                                        defined in a  FIELD statement,
                                        although it can be any string
                                        variable.

    stringexpression$                      The value that is assigned to
                                        stringvariable$ and is
                                        left-justified.

    recordvariable1                        A record variable of any data type.

    recordvariable2                        A record variable of any data type.





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 right-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  LSET or  RSET
statements.

You also can 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 following program lines will right-justify the string N$ in
a 20-character field:

A$=SPACE$(20)

RSET A$=N$

This can be useful for formatting printed output.


You can use  LSET with Syntax 2 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 also can be assigned using  LET. Also,
because RecOne is only two bytes long, only two bytes are copied from
RecTwo.  LSET copies only the number of bytes in the shorter of the two
record variables.



See Also

    LET;  MKI$,  MKL$,  MKS$,  MKD$,  MKC$;  PUT (File I/O);  RSET


Example

The following example shows the effects of using  LSET and  RSET to assign
values to fixed- and variable-length strings:

DIM TmpStr2 AS STRING * 25


CLS    ' Clear screen.





' Use RSET on variable-length string with a value.


TmpStr$ = SPACE$(40)


PRINT "Here are two strings that have been right and left "


PRINT "justified in a 40-character variable-length string."


PRINT





RSET TmpStr$ = "Right-|"


PRINT TmpStr$


LSET TmpStr$ = "|-Left"


PRINT TmpStr$


PRINT "^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^"


PRINT "12345678901234567890123456789012345678901234567890"


PRINT "         1         2         3         4         5"





' Use RSET on fixed-length string of length 25.


PRINT


PRINT


PRINT "Here are two strings that have been right and left"


PRINT "justified in a 25-character fixed-length string."


PRINT


RSET TmpStr2 = "Right-|"


PRINT TmpStr2


LSET TmpStr2$ = "|-Left"


PRINT TmpStr2$


PRINT "^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^"


PRINT "12345678901234567890123456789012345678901234567890"


PRINT "         1         2         3         4         5"




Output



Here are two strings that have been right and left

justified in a 40-character variable-length string.


                                    Right-|


|-Left


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


12345678901234567890123456789012345678901234567890


            1         2         3         4         5








Here are two strings that have been right and left

justified in a 25-character fixed-length string.


                    Right-|


|-Left


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


12345678901234567890123456789012345678901234567890


1         2         3         4         5


LTRIM$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a copy of a string with leading spaces removed.


Syntax



    LTRIM$( stringexpression$)


Remarks


The  stringexpression$ can be any string expression. The  LTRIM$ function
works with both fixed- and variable-length string variables.


See Also

    RTRIM$


Example

The following example copies a file to a new file, removing all leading and
trailing spaces:

' Get the filenames.


INPUT "Enter input filename:", InFile$


INPUT "Enter output filename:", OutFile$





OPEN InFile$ FOR INPUT AS #1


OPEN OutFile$ FOR OUTPUT AS #2





' Read, trim, and write each line.


DO WHILE NOT EOF(1)


    LINE INPUT #1, LineIn$


    ' Remove leading and trailing blanks.


    LineIn$ = LTRIM$(RTRIM$(LineIn$))


    PRINT #2, LineIn$


LOOP





CLOSE #1, #2


END


MID$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a substring of a string.


Syntax

    MID$( stringexpression$,  start%,  length%)

Remarks


The  MID$ function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    stringexpression$                      The string expression from which
                                        the substring is extracted. This
                                        can be any string expression.

    start%                                 The character position in
                                        stringexpression$ where the
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        stringexpression$ where the
                                        substring starts.

    length%                                The number of characters to
                                        extract.





The arguments  start% and  length% must be between 1 and 32,767, inclusive.
If  length% is omitted or if there are fewer than  length% characters in the
string (including the  start% character), the  MID$ function returns all
characters from the position  start% to the end of the string.

If  start% is greater than the number of characters in  stringexpression$,
MID$ returns a null string.

Use the  LEN function to find the number of characters in
stringexpression$.


See Also

    LEFT$,  LEN,  MID$ Statement,  RIGHT$


Example

The following 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).

INPUT "Binary number = ", Binary$' Input binary number as string.

Length = LEN(Binary$)' Get length of string.

Decimal = 0

FOR K = 1 TO Length

    Digit$ = MID$(Binary$, K, 1) ' Get digit from string.

    IF Digit$ = "0" OR Digit$ = "1" THEN' Test for binary digit.

        Decimal = 2 * Decimal + VAL(Digit$)' Convert digits to numbers.

    ELSE

        PRINT "Error--invalid binary digit: "; Digit$

        EXIT FOR

    END IF

NEXT

PRINT "Decimal number =" Decimal


MID$ Statement
────────────────────────────────────────────────────────────────────────────


Action

Replaces a portion of a string variable with another string.


Syntax



    MID$( stringvariable$,  start% ,  length%) =  stringexpression$

Remarks


The  MID$ statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    stringvariable$                        The string variable being modified.

    start%                                 A numeric expression giving the
                                        position in  stringvariable$ where
                                        the replacement starts.

    length%                                A numeric expression that gives
                                        the length of the string being
                                        replaced.

    stringexpression$                      The string expression that
                                        replaces part of  stringvariable$.





The arguments  start% and  length% are integer expressions. The argument
stringvariable$ is a string variable, but  stringexpression$ can be a string
variable, a string constant, or a string expression.

The optional  length% refers to the number of characters from the argument
stringexpression$ that are used in the replacement. If  length% is omitted,
all of  stringexpression$ is used. However, regardless of whether  length%
is omitted or included, the replacement of characters never goes beyond the
original length of  stringvariable$.


See Also

    MID$ Function


Example

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$



Output

Paris, France


Paris, Texas


MKDIR Statement
────────────────────────────────────────────────────────────────────────────


Action

Creates a new directory.


Syntax



    MKDIR  pathname$

Remarks


The  pathname$ is a string expression that specifies the name of the
directory to be created in DOS. The  pathname$ must be a string of fewer
than 64 characters.

The  MKDIR statement works like the DOS command MKDIR. However, the syntax
in BASIC cannot be shortened to MD, as it can in DOS.

You can use  MKDIR to create a DOS directory with a name that contains an
embedded space. However, although you can access that directory through DOS,
you can remove it only with the BASIC  RMDIR statement.


See Also

    CHDIR,  RMDIR


Example

See the  CHDIR statement programming example, which uses the  MKDIR
statement.


MKI$, MKL$, MKS$, MKD$, and MKC$ Functions
────────────────────────────────────────────────────────────────────────────


Action

Convert numeric values to string values.


Syntax



    MKI$( integer-expression%)


    MKL$( long-integer-expression&)


    MKS$( single-precision-expression!)


    MKD$( double-precision-expression#)


    MKC$( currency-expression@)

Remarks


    MKI$,  MKL$,  MKS$,  MKD$ and  MKC$ are used with  FIELD and  PUT
statements to write numbers to a random-access file. The functions convert
numeric expressions to strings that can be stored in the strings defined in
the  FIELD statement. These functions are the inverse of  CVI,  CVL,  CVS,
CVD, and  CVC.

The following table describes these numeric-conversion functions:

╓┌───────────┌───────────────────────────────────────────────────────────────╖
Function    Description
────────────────────────────────────────────────────────────────────────────
    MKI$       Converts an integer to a 2-byte string.
    MKL$       Converts a long-integer value to a 4-byte string.
    MKS$       Converts a single-precision value to a 4-byte string.
    MKD$       Converts a double-precision value to an 8-byte string.
Function    Description
────────────────────────────────────────────────────────────────────────────
    MKD$       Converts a double-precision value to an 8-byte string.
    MKC$       Converts a currency value to an 8-byte string.





Note

These BASIC record variables provide a more efficient and convenient way of
reading and writing random-access files than some older versions of BASIC.


See Also

    CVI,  CVL,  CVS,  CVD,  CVC;  GET (File I/O);  FIELD;  PUT (File I/O)


Example

See the programming example for the  CVI,  CVL,  CVS,  CVD, and  CVC
statements, which uses the  MKS$ function.


MKSMBF$, MKDMBF$ Functions
────────────────────────────────────────────────────────────────────────────


Action

Convert an IEEE-format number to a string containing a
Microsoft-Binary-format number.


Syntax



    MKSMBF$( single-precision-expression!)


    MKDMBF$( double-precision-expression#)

Remarks


These functions are used to write real numbers to random-access files using
Microsoft Binary format. They are particularly useful for maintaining data
files created with older versions of BASIC.

The  MKSMBF$ and  MKDMBF$ functions convert real numbers in IEEE format to
strings so they can be written to the random-access file.

To write a real number to a random-access file in Microsoft Binary format,
convert the number to a string using  MKSMBF$ (for a single-precision
number) or  MKDMBF$ (for a double-precision number). Then store the result
in the corresponding field (defined in the  FIELD statement) and write the
record to the file using the  PUT statement.

Currency numbers are not real numbers, so they cannot be converted to
strings that contain Microsoft-Binary-format numbers.


See Also

    CVSMBF,  CVDMBF;  CVI,  CVL,  CVS,  CVD,  CVC;  MKI$,  MKL$,  MKS$,  MKD$,
MKC$


Example

The following example stores real values in a file as
Microsoft-Binary-Format numbers:

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 names and scores from the console until the name is END.

DO WHILE UCASE$(NameIn$) <> "END"

    I=I+1

    RecBuffer.NameField=NameIn$

    RecBuffer.ScoreField=MKSMBF$(Score)   ' Convert to a string.

    PUT #1,I,RecBuffer

    INPUT NameIn$, Score

LOOP

PRINT I;" records written."

CLOSE #1


MOVEFIRST, MOVELAST, MOVENEXT, MOVEPREVIOUS Statements
────────────────────────────────────────────────────────────────────────────


Action

Make records current according to their relative position in an ISAM table.


Syntax



    MOVEFIRST #  filenumber%


    MOVELAST #  filenumber%


    MOVENEXT #  filenumber%


    MOVEPREVIOUS #  filenumber%

Remarks


The  filenumber% is the number used in the  OPEN statement to open the
table. The  MOVEFIRST,  MOVELAST,  MOVENEXT, and  MOVEPREVIOUS statements
allow you to make records current according to their relative position on
the current index in an ISAM table:

╓┌──────────────────────┌────────────────────────────────────────────────────╖
Statement              Effect
────────────────────────────────────────────────────────────────────────────
    MOVEFIRST             First record becomes current.
    MOVELAST              Last record becomes current.
    MOVENEXT              Next record becomes current.
    MOVEPREVIOUS          Previous record becomes current.


The action of these statements is made relative to the record that is
current according to the current index.

Using  MOVEPREVIOUS when the first indexed record is current moves the
current position to the beginning of the table. The beginning of an ISAM
table is the position before the first record according to the current
index.

Using  MOVENEXT when the last indexed record is current moves the current
position to the end of the table. The end of an ISAM table is the position
following the last record according to the current index.


See Also

    BOF;  EOF;  SEEKGT,  SEEKGE,  SEEKEQ


Example

See the  CREATEINDEX statement programming example, which uses the
MOVEFIRST,  MOVELAST,  MOVENEXT, and  MOVEPREVIOUS statements.


NAME Statement
────────────────────────────────────────────────────────────────────────────


Action

Changes the name of a disk file or directory.


Syntax



    NAME  oldfilespec$  AS  newfilespec$

Remarks


The  NAME statement is similar to the DOS RENAME command.  NAME can move a
file from one directory to another but cannot move a directory.

The arguments  oldfilespec$ and  newfilespec$ are string expressions, each
of which contains a filename and an optional path. If the path in
newfilespec$ is different from the path in  oldfilespec$, the  NAME
statement renames the file as indicated.

The file  oldfilespec$ must exist and  newfilespec$ must not be in use. Both
files must be on the same drive. If you use  NAME with different drive
designations in the old and new filenames, BASIC generates the error message
Rename across disks.

Using  NAME on an open file causes BASIC to generate the run-time error
message File already open. You must close an open file before renaming it.


Example

The following example shows how to use  NAME to rename a 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"




You also can 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 "\MYDIR\README.DOC"


OCT$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string representing the octal value of the numeric argument.


Syntax



    OCT$( numeric-expression)

Remarks


The argument  numeric-expression can be of any type. It is rounded to an
integer or long integer before the  OCT$ function evaluates it.


See Also

    HEX$


Example

The following 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)




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


ON ERROR Statement
────────────────────────────────────────────────────────────────────────────


Action

Enables an error-handling routine and specifies the location of that routine
in the program. The  ON  ERROR statement also can be used to disable an
error-handling routine.


Syntax



    ON  LOCAL  ERROR { GOTO  line |  RESUME  NEXT |  GOTO  0}

Remarks


If no  ON  ERROR statement is used in a program, any run-time error will be
fatal (BASIC generates an error message and program execution stops).

The following list describes the parts of the  ON ERROR statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    LOCAL                                  Used to indicate an error-handling
                                        routine in the same procedure. If
                                        not used, module-level error
                                        handlers are indicated.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        handlers are indicated.

    GOTO  line                             Enables the error-handling routine
                                        that starts at  line. Thereafter,
                                        if a run-time error occurs,
                                        program control branches to  line
                                        (a label or a line number). The
                                        specified line is either in the
                                        module-level code or in the same
                                        procedure (if the  LOCAL keyword
                                        is used). If not found in either
                                        place, BASIC generates a Label not
                                        defined compile-time error.

    RESUME NEXT                            Specifies that, when a run-time
                                        error occurs, control goes to the
                                        statement after the statement
                                        where the error occurred; the  ERR
                                        function then can be used to
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        function then can be used to
                                        obtain the run-time error code.

    GOTO 0                                 Disables any enabled module-level
                                        error-handling routine within the
                                        current module, or disables any
                                        enabled error handler within the
                                        current procedure (if used
                                        together with the  LOCAL keyword).






The  LOCAL keyword indicates an error-handling routine that is "local" to
the procedure within which the error-handling routine is located. A local
error-handling routine:

    ■   Overrides any enabled module-level error-handling routines.

    ■   Is enabled only while the procedure within which it is located is
        executing.

Notice that the local error handler remains enabled while any procedures
execute that are directly or indirectly called by the procedure within which
the error handler is located. One of those procedures may supersede the
local error handler.


Note

The module-level error-handling routines provided by previous versions of
BASIC may be all you need; you may never need to use the  LOCAL keyword.

Use of the  RESUME  NEXT option causes program execution to resume with the
statement immediately following the statement that caused the run-time
error. This enables your program to continue execution of a block of program
code, despite a run-time error, then check for the cause of the error. This
also enables you to build the error-handling code in line with the main
module code or procedure, rather than at a remote location in the program.


The statement form  ON  ERROR  GOTO  0 disables error handling. It does not
specify line 0 as the start of the error-handling code, even if the program
or procedure contains a line num-bered 0.


Notice that an error-handling routine is not a  SUB or  FUNCTION procedure
or a  DEF  FN function. An error-handling routine is a block of code marked
by a line label or line number.

An error handler is enabled when it is referred to by an  ON  ERROR  GOTO
line statement. Once an error handler is enabled, a run-time error causes
program control to jump to the enabled error-handling routine and makes the
error handler "active." An error handler is active from the time a run-time
error has been trapped until a  RESUME statement is executed in the handler.

Error-handling routines must rely on the value in  ERR to determine the
cause of the error. The error-handling routine should test or save this
value before any other error can occur or before calling a procedure that
could cause an error. The value in  ERR reflects only the last error to
occur.

If you use the BASIC command line to compile a program that has been
developed in the QBX environment and has error-handling routines, compile
with the /E or /X option. The Make EXE File command in the QBX environment
uses these options.

If an error occurs in a procedure or module that does not have an enabled
error-handling routine, BASIC searches for an enabled, inactive error
handler to trap the error. BASIC searches back through all the procedures
and modules that have called the procedure where the error occurred.

Using Module-Level Error Handlers
Once enabled by execution of an  ON  ERROR  GOTO  line statement, a
module-level error handler stays enabled unless explicitly disabled by
execution of an  ON  ERROR  GOTO  0 statement somewhere in the module.


In the following cases, BASIC searches back through the module-level code of
the calling modules, looking for an enabled, inactive error handler:

    ■         In a multiple-module program that contains only module-level
            error handlers, if an enabled and inactive error handler cannot
            be found in the module where the error occurred.

    ■         If an error occurs in a module-level error handler itself (BASIC
            does not automatically treat this as a fatal error).

    ■         If an  ON ERROR GOTO 0 statement is encountered while the
            current module's module-level error handler is active.





Procedure-Level Error Handlers
    SUB and  FUNCTION procedures and  DEF  FN functions can contain their own
error-handling routines.


To enable a local error handler, use the statement  ON LOCAL ERROR GOTO
line. The argument  line must be a label or line number in the same
procedure as the  ON LOCAL ERROR GOTO statement.

The local error handler is automatically disabled when the procedure
returns, or by execution of the statement  ON LOCAL ERROR GOTO 0.

You will want program flow to avoid the statements that make up the
error-handling routine. One way to keep the error-handling code from
executing when there is no error is to place an  EXIT  SUB,  EXIT  FUNCTION,
or  EXIT  DEF statement immediately ahead of the error-handling routine, as
in the following example:

SUB InitializeMatrix (var1, var2, var3, var4)


.


.


.


ON LOCAL ERROR GOTO ErrorHandler


.


.


.


EXIT SUB


ErrorHandler:


.


.


.


RESUME NEXT


END SUB

The example shows the error-handling code located after the  EXIT  SUB
statement and before the  END  SUB statement. This partitions the
error-handling code from the normal execution flow of the procedure.
However, error-handling code can be placed anywhere in a procedure.


In the QBX environment, or if the command-line compiler is used with the /O
option:

    ■         If a local error handler is active and an  END  SUB,  END
            FUNCTION, or  END  DEF statement is encountered, BASIC generates
            the run-time error message  No RESUME.

    ■         If an  EXIT  SUB,  EXIT  FUNCTION, or  EXIT  DEF statement is
            encountered, BASIC does not generate a run-time error; in other
            words, it is assumed that this does not represent a logic error
            in the program.

In a multiple-module program that contains only procedure-level (local)
error handlers, if an enabled and inactive error handler cannot be found in
the procedure where the error occurred, BASIC searches back through all the
calling procedures as well as the module-level code of all the calling
modules, looking for an enabled, inactive error handler.

Using Both Module-Level and Procedure-Level Error Handlers
For simplicity and clarity, avoid using both local- and module-level error
handlers in the same program, except for using an error handler in the main
module module-level code as the last line of defense against a fatal error.
If you need to, however, you can have both a module-level error handler and
a local error handler enabled at the same time. (In fact, you can enable
both local- and module-level error handling from within a procedure.)


While searching for an enabled, inactive error handler, BASIC may encounter
an active event handler. Unless an enabled error-handling routine is
provided in the same module-level code as the event handler, BASIC generates
a fatal error. Therefore, to produce completely bullet-proof BASIC code in
programs that trap events, make sure an error handler in the same
module-level code as the event handler is enabled at the time the event
occurs. Because event handlers can be located only at the module level, this
is another special case where you might mix module-level and procedure-level
error handlers.

Notice that when an error-handling routine is finished and program execution
resumes through execution of a  RESUME 0 or  RESUME  NEXT statement, the
resume location is based on the location of the error-handling routine, and
not necessarily on the location where the error occurred. For more
information, see the entry for  RESUME.


See Also

    ERL,  ERR;  ERROR;  RESUME


Example

The following program prompts the user for a disk drive designation. Once
the user has input the drive designation, the program attempts to write a
large file to the disk. A number of errors can occur.

DECLARE SUB ErrorMessage (Message$)

DECLARE SUB WriteBigFile (Filenum%)



ON ERROR GOTO ErrHandler

CLS

PRINT "This program will attempt to write a large file to a disk drive that"

PRINT "you have selected. The file will be erased when the program ends."

PRINT

DO

INPUT "Enter the letter of the drive where you want this file written"; DR$

DR$ = UCASE$(DR$)

LOOP UNTIL LEN(DR$) >= 1 AND LEN(DR$) <= 2 AND DR$ >= "A" AND DR$ <= "Z"

IF LEN(DR$) > 1 THEN

IF RIGHT$(DR$, 1) <> ":" THEN

DR$ = LEFT$(DR$, 1) + ":"

END IF

ELSE

DR$ = DR$ + ":"

END IF



' Put together a complete file specification.


FileSpec$ = DR$ + "BIGFILE.XXX"

' Get the next available file number.

Filenum% = FREEFILE

' Try an open the file

OPEN FileSpec$ FOR OUTPUT AS Filenum%

WriteBigFile Filenum%

CLOSE Filenum%

CLS

PRINT "Everything was OK. No errors occurred."

PRINT "Deleting the file that was created."

KILL FileSpec$

' Same as END, returns to operating system.

SYSTEM



ErrHandler:

SELECT CASE ERR

CASE 52'Bad file name or number.

END

CASE 53' File not found.

RESUME NEXT

CASE 57' Device I/O error.

ErrorMessage "You should probably format the disk."

END

CASE 64' Bad file name.

ErrorMessage "The drive name you specified was not correct."

END

CASE 68' Device unavailable

ErrorMessage "The drive you named is unavailable."

END

CASE 71' Drive not ready

ErrorMessage "The drive was not ready. Check the drive!"

END

CASE ELSE

ErrorMessage "An unexpected FATAL error has occurred."

STOP

END SELECT



SUB ErrorMessage (Message$)


ON LOCAL ERROR GOTO MessageError

CLS

PRINT Message$

PRINT "Cannot continue."

PRINT

PRINT "Press any key to exit."

DO

LOOP WHILE INKEY$ = ""

EXIT SUB

MessageError:

RESUME NEXT

END SUB



SUB WriteBigFile (Filenum%)

ON LOCAL ERROR GOTO LocalHandler

TEXT$ = STRING$(1024, "A")

FOR I% = 1 TO 400

PRINT #Filenum%, TEXT$

NEXT I%

EXIT SUB

LocalHandler:

SELECT CASE ERR

CASE 61 ' Disk full

ErrorMessage ("There is no room remaining on the disk.")

KILL "BIGFILE.XXX"

END

CASE ELSE

ERROR ERR

END SELECT

END SUB


ON event Statements
────────────────────────────────────────────────────────────────────────────


Action

Indicate the first line of an event-trapping routine.


Syntax



    ON  event  GOSUB { linenumber |  linelabel}

Remarks


The  ON  event statements let you specify a routine that is executed
whenever a specified type of event occurs on a specified device. The  ON
event statements use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    event                                  Specifies the event that causes a
                                        branch to the event-trapping
                                        routine. See below for more
                                        information about specific types
                                        of events.

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

                                        A  linenumber value of 0 disables
                                        event trapping and does not
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        event trapping and does not
                                        specify line 0 as the start of the
                                        routine.



The following list describes the events that can be trapped:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Event                                   Description
────────────────────────────────────────────────────────────────────────────
    COM( n%)                               Branches to the routine when
                                        characters are received at a
                                        communications port. The integer
                                        expression  n% indicates one of
                                        the serial ports, either 1 or 2.
                                        For more information, see "Using
                                        ON COM" later in this entry.

    KEY( n%)                               Branches to the routine when a
Event                                   Description
────────────────────────────────────────────────────────────────────────────
    KEY( n%)                               Branches to the routine when a
                                        specified key is pressed. The
                                        integer expression  n% is the
                                        number of a function key,
                                        direction key, or user-defined key.
                                        For more information, see "Using
                                        ON KEY" later in this entry.

    PEN                                    Branches to the routine when a
                                        lightpen is activated. For more
                                        information, see "Using ON PEN"
                                        later in this entry.

    PLAY( queuelimit%)                     Branches when there are fewer than
                                            queuelimit% notes in the
                                        background-music queue. A  PLAY
                                        event-trapping routine can be used
                                        with a  PLAY statement to play
                                        music in the background while a
Event                                   Description
────────────────────────────────────────────────────────────────────────────
                                        music in the background while a
                                        program is running. For more
                                        information, see "Using ON PLAY"
                                        later in this entry.

    SIGNAL( n%)                            Branches to the routine when an
                                        OS/2 protected-mode signal is
                                        received. For more information,
                                        see "Using ON SIGNAL" later in
                                        this entry.

    STRIG( n%)                             Branches to the event-trapping
                                        routine when a joystick trigger is
                                        pressed. The integer expression
                                        n% is the joystick trigger number.
                                        For more information, see "Using
                                        ON STRIG" later in this entry.

    TIMER( n&)                             Branches to the routine when  n
Event                                   Description
────────────────────────────────────────────────────────────────────────────
    TIMER( n&)                             Branches to the routine when  n
                                        seconds have passed. The numeric
                                        expression  n& is in the range 1
                                        to 86,400 (1 second to 24 hours).

    UEVENT                                 Branches to the event-trapping
                                        routine for a user-defined event.
                                        This event usually is a hardware
                                        interrupt (although it can be a
                                        software interrupt). For more
                                        information, see "Using ON UEVENT"
                                        later in this entry.



The  ON  event statement specifies only the start of an event-trapping
routine. Another set of statements determines whether or not the routine is
called. This set of statements turns event trapping on or off and determines
how events are handled when trapping is off. The following list describes
these statements in a general way. See the entries for particular statements
for more specific information.
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Event                                   Description
────────────────────────────────────────────────────────────────────────────
    event  ON                              Enables event trapping. Event
                                        trapping occurs only after an
                                        event  ON statement is executed.

    event  OFF                             Disables event trapping. No
                                        trapping takes place until the
                                        execution of another  event  ON
                                        statement. Events occurring while
                                        trapping is off are ignored.

    event  STOP                            Suspends 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
Event                                   Description
────────────────────────────────────────────────────────────────────────────
                                        processed when an  event  ON
                                        statement is executed.




When an event trap occurs and the routine is called, BASIC performs an
automatic  event  STOP that prevents recursive traps. The  RETURN statement
from the trapping routine automatically performs an  event  ON statement
unless an explicit  event  OFF is performed inside the routine.

If your program contains event-handling statements and you are compiling
from the BC command line, use the BC /W or /V option. (The /W option checks
for events at every label or line number; the /V option checks at every
statement.) If you do not use these options and your program contains event
traps, BASIC generates the error message ON events without /V or /W on
command line.


Note

Because of the implicit  event  STOP and  event  ON statements, events that
occur during execution of the trapping routine are remembered and processed
when the routine ends.

The  RETURN  linenumber or  RETURN  linelabel forms of  RETURN can be used
to return to a specific line from the trapping routine. Use this type of
return with care, however, because any  GOSUB,  WHILE, or  FOR statements
active at the time of the trap remain active. BASIC may generate error
messages such as NEXT without FOR. In addition, if an event occurs in a
procedure, a  RETURN  linenumber or  RETURN  linelabel statement cannot get
back into the procedure because the line number or label must be in the
module-level code.


The next sections contain additional information about the  ON COM,  ON KEY,
    ON PEN,  ON PLAY,  ON SIGNAL,  ON STRIG, and  ON UEVENT statements.


Using On Com
You can use  ON COM( n%)  to specify a routine to branch to when characters
are received at communications port  n%, which can be either 1 or 2.


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.

For an example of the  ON COM statement, see the  COM statements programming
example.

Using On Key
You can use  ON KEY( n%) to specify a routine to branch to when key  n% is
pressed. The argument  n% is the number of a function key, direction key, or
user-defined key.


Keys are processed in the following order:

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

    ■         Function keys and the 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.

    ■         Finally, the user-defined keys are examined.

The  ON KEY statement can trap any key, including break or system reset.
This makes it possible to prevent accidentally breaking out of a program or
rebooting the machine.

Note

After a key is trapped, the information on which key was trapped is no
longer available. This means that you cannot subsequently use the  INPUT
statement or  INKEY$ function to find out which key caused the trap. Because
you do not know which key press caused the trap, you must set up a different
event-handling routine for each key you want to trap.

For an example of the  ON KEY statement, see the  KEY statements programming
example.

Using On PEN
You can use  ON PEN to specify a routine to branch to when the lightpen is
activated.


    ON PEN is not available for OS/2 protected mode.

For an example of the  ON PEN statement, see the  PEN statements programming
example.

Using On PLAY
You can use  ON PLAY( queuelimit%) to specify a routine to branch to when
there are fewer than  queuelimit% notes in the background-music queue. The
argument  queuelimit% is an integer expression between 1 and 32, inclusive.


The following three rules apply to the use of  ON PLAY:

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

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

    ■         If  queuelimit% is a large number, event traps may occur often
            enough to slow down the program.





    ON PLAY is not available for OS/2 protected mode.

For an example of the  ON PLAY statement, see the  PLAY function programming
example.

Using On SIGNAL
You can use  ON SIGNAL to specify a routine to branch to when an OS/2
protected-mode signal is trapped.


The following table lists the numbers of the protected-mode signals:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
Number                Signal
────────────────────────────────────────────────────────────────────────────
1                     Ctrl+C
2                     Pipe connection broken
3                     Program terminated
4                     Ctrl+Break
5                     Process flag A
6                     Process flag B
7                     Process flag C


Process flag A, process flag B, and process flag C are used for
communicating between processes. Although BASIC has no built-in mechanism
for activating a process flag, you can activate the signal handler in a
separate process by invoking the OS/2 function DOSFLAGPROCESS.

The  ON SIGNAL statement is available only for OS/2 protected mode.

For an example of the  ON SIGNAL statement, see the  SIGNAL statements
programming example.

Using On STRIG
You can use  ON STRIG( n%) to specify a routine to branch to when the button
on the joystick is pressed. The argument  n% is the trigger number as
defined in the following table:
╓┌───┌───────┌───────────────────────────────────────────────────────────────╖
n%  Button  Joystick
────────────────────────────────────────────────────────────────────────────
0   Lower   First
2   Lower   Second
4   Upper   First
6   Upper   Second


    ON STRIG is not available for OS/2 protected mode.

For an example of the  ON STRIG statement, see the  STRIG statements
programming example.

Using On UEVENT
You can use  ON UEVENT to specify a routine to branch to when a user-defined
event occurs. The event usually is a hardware interrupt (although it also
can be a software interrupt).


When using DOS, at least two (and sometimes three) pieces of code are
needed. 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. For
more information, see "Event Handling" in the  Programmer's Guide.

If the initialization routine "steals" an interrupt used by another service
routine, the original address must be restored before your program
terminates.

These routines usually are written in assembly language. However, any
language whose compiler can generate interrupt-service routines and whose
object code can be linked with BASIC can be used.

There are four steps in creating a user-defined event:

    ■         Write an event-handling routine and add it to your BASIC
            program.

    ■         Execute the  ON UEVENT statement to specify the user-event
            handling routine.

    ■         Execute the  UEVENT ON statement to enable user-event trapping.

    ■         Call the interrupt-initialization routine to insert the address
            of the interrupt-service routine into the interrupt-vector
            table.

You're now ready for the interrupt when it occurs. The interrupt transfers
execution to the interrupt-service routine. The service routine collects and
stores the data the user wants. It then calls SetUEvent (see the entry for
SetUEvent for details).

SetUEvent sets a flag checked by BASIC 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.


For an example of the  ON UEVENT statement, see the  UEVENT statements
programming example.


See Also

    COM,  EVENT,  KEY (Event Trapping),  PEN,  PLAY (Event Trapping),  RETURN,
SIGNAL,  STRIG,  TIMER,  UEVENT


ON...GOSUB, ON...GOTO Statements
────────────────────────────────────────────────────────────────────────────


Action

Branches to one of several specified lines, depending on the value of an
expression.


Syntax 1

    ON  expression  GOSUB  line-label-list

Syntax 2

    ON  expression  GOTO  line-label-list

Remarks


The argument  expression can be any numeric expression between 0 and 255,
inclusive ( expression is rounded to an integer before the  ON... GOSUB or
ON... GOTO statement is evaluated). The argument  line-label-list consists
of a list of line numbers or line labels, separated by commas. The value of
expression determines which line the program branches to. For example, if
the value is 3, the third line specified in the list is the destination of
the branch.

The value of  expression should be greater than or equal to 1 and less than
or equal to the number of items in the list. If the value falls outside this
range, one of the following results occurs:
╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Value                                 Result
────────────────────────────────────────────────────────────────────────────
Number equal to 0 or greater than     Control drops to the next BASIC
number of items in list               statement.

Negative number or a number greater   BASIC generates the error
than 255                              messageIllegal function call.



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


Note

You can mix line numbers and labels in the same list. The  ON ... GOTO
statement accepts a maximum of 60 line labels or line numbers. The  SELECT
CASE statement provides a more powerful, convenient, and flexible way to
perform multiple branching.


See Also

    GOSUB,  RETURN,  SELECT CASE


Example


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


OPEN Statement (File I/O)
────────────────────────────────────────────────────────────────────────────


Action

Enables I/O to a file, device, or ISAM table.


Syntax 1

    OPEN  file$   FOR  mode  ACCESS  access  lock  AS #  filenumber%   LEN=
reclen%  OPEN  database$  FOR  ISAM  tabletype  tablename$  AS #
filenumber%

Syntax 2

    OPEN  mode$, #  filenumber%,  file$,  reclen%

Remarks


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.

The  OPEN statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    file$                                  A filename or path.

    mode                                   A keyword that specifies one of
                                        the following file modes: Random,
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        the following file modes: Random,
                                        Binary, Input, Output


    access                                 A keyword that specifies the
                                        operation performed on the open
                                        file:


    lock                                   A keyword that specifies the lock
                                        type:


    filenumber%                            An integer expression with a value
                                        between 1 and 255, inclusive. When
                                        an  OPEN statement is executed,
                                        the file number is associated with
                                        the file as long as it is open.
                                        Other I/O statements may use the
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        Other I/O statements may use the
                                        number to refer to the file.

    reclen%                                For random-access files, the
                                        record length; for sequential
                                        files, the number of characters
                                        buffered. The  reclen% is an
                                        integer expression less than or
                                        equal to 32,767 bytes.

    database$                              A database filename or path.

    tabletype                              The name of a type of table
                                        defined using the  TYPE statement.

    tablename$                             The name of the ISAM table being
                                        opened. It follows the ISAM naming
                                        conventions (listed later in this
                                        entry).
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        entry).



Syntax 1
The arguments  file$ and  database$ specify an optional device, followed by
a filename or path conforming to the DOS file-naming conventions. The
argument  database$ must be the name of an ISAM file.


For sequential files, if  file$ does not exist, it is created when opening a
file for anything but input [mdash] that is,  OUTPUT,  RANDOM,  BINARY, and
APPEND. For ISAM, a nonexistent  database$ or  tablename$ is created only
when using the PROISAMD library; with the PROISAM library, BASIC generates
the error message File Not Found if  database$ or  tablename$ does not
exist.


The argument  mode is a keyword that specifies one of the following file
modes:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Keyword                                 Description
────────────────────────────────────────────────────────────────────────────
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 and write

                                        2. Write only

                                        3. Read only

Binary                                  Specifies binary file mode. In
                                        binary mode, you can read or write
Keyword                                 Description
────────────────────────────────────────────────────────────────────────────
                                        binary mode, you can 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,
                                        following the same order as for
                                        random files.

Input                                   Sequential input mode.

Output                                  Sequential output mode.

Append                                  Sequential output mode. 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
Keyword                                 Description
────────────────────────────────────────────────────────────────────────────
                                        WRITE # statement then extends
                                        (appends to) the file.





If the  mode argument is omitted, the default random-access mode is assumed.

The argument  access is a keyword that 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 operation fails and BASIC
generates the error Permission denied. The  ACCESS clause works in an  OPEN
statement only if you are using a version of DOS that supports networking
(DOS version 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 the
error message Feature unavailable.

The argument  access 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 argument can be one of the following
keywords specifying the lock type:


╓┌───────────────────────────────────────┌───────────────────────────────────╖
Lock type                               Description
────────────────────────────────────────────────────────────────────────────
    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 that appears
                                        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
Lock type                               Description
────────────────────────────────────────────────────────────────────────────
                                        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.





If you do not specify a lock type, the file may be opened for reading and
writing any number of times by this statement, but other operations are
denied access to the file while it is opened.

When  OPEN is restricted by a previous process, BASIC generates error 70,
Permission denied.

The argument  reclen% is an integer expression less than or equal to 32,767
bytes. It specifies different settings for random-access or sequential
files:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
For random-access:                    For sequential files:
────────────────────────────────────────────────────────────────────────────
The argument  reclen% sets the        The argument  reclen% specifies the
record length (the number of          number of characters to be loaded
characters in a record).              into the buffer before the buffer is
                                        written to, or read from, the disk.

The default is 128 bytes.             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.
For random-access:                    For sequential files:
────────────────────────────────────────────────────────────────────────────
                                        I/O.

                                        The default is 512 bytes.





The  LEN clause and  reclen% are ignored if  mode is binary. For sequential
files,  reclen% need not correspond to an individual record size, because a
sequential file may have records of different sizes.

    ISAM is a keyword that specifies you are opening an ISAM table.


The argument  tabletype is the name of a user-defined type that defines a
subset of the table definition. (See the entry for the  TYPE statement.) The
argument  tablename$ is the name of the ISAM table being opened. It follows
the ISAM naming conventions:

    ■         It has no more than 30 characters.

    ■         It uses only alphanumeric characters (A-Z, a-z, 0-9).

    ■         It begins with an alphabetic character.

    ■         It includes no BASIC special characters.

Syntax 2
In the second (alternative) form of the  OPEN syntax,  mode$ is a string
expression that begins with one of the following characters and specifies
the file mode:


╓┌───────────────────────────────────────┌───────────────────────────────────╖
Mode                                    Description
────────────────────────────────────────────────────────────────────────────
    O                                      Sequential output mode.

    I                                      Sequential input mode.
Mode                                    Description
────────────────────────────────────────────────────────────────────────────
    I                                      Sequential input mode.

    R                                      Random-access file I/O mode.

    B                                      Binary file mode.

    A                                      Sequential output mode. 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

This alternative syntax does not support any of the access and file-sharing
options found in the primary syntax. It 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 argument  file$:

KYBD, SCRN, COM n, LPT n, CONS, PIPE.

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 device files is set to 1.


BASIC sends only a carriage return at the end of a line. If the device
requires a line feed, the driver must provide it. When writing to 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,
line-printer devices can be opened in binary mode by adding the  BIN
keyword:

OPEN "LPT1:BIN" FOR OUTPUT AS #1

Opening a printer in binary mode eliminates printing a carriage return at
the end of a line.


When you open an ISAM table, the next record is the first record in the
table and the current index is the null index.

Any ISAM operation that closes a table causes transactions to be committed.
For example, if a type mismatch occurs while you are opening an ISAM table,
the table is closed and a pending transaction is committed.

You may wish to code your programs so they first open all tables, then
perform all transactions, then close tables. Make sure any operation that
can close a table occurs outside a transaction.


Note

In input, random-access, and binary modes you can open a file under a
different file number without first closing the file. In output or append
mode you must close a file before opening it with a different file number.


See Also

    CLOSE,  FREEFILE,  TYPE


Example

See the  FREEFILE function programming example, which uses the  OPEN
statement.


OPEN COM Statement
────────────────────────────────────────────────────────────────────────────


Action

Opens and initializes a communications channel for I/O.


Syntax



    OPEN " COM n:  optlist1  optlist2"  FOR  mode  AS  #  filenum%  LEN=
reclen%

Remarks


The  OPEN COM statement must be executed before a device can be used for
communication using an RS232 interface.  COM n is the name of the device to
be opened. If there are any syntax errors in the  OPEN COM statement, BASIC
generates the error message Bad file name.

The  OPEN COM statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    n                                      The communications port to open,
                                        such as 1 for COM1 and 2 for COM2.

    optlist1                               The most-often-used communications
                                        parameters. The defaults are 300
                                        baud, even parity, 7 data bits,
                                        and 1 stop bit. The syntax of
                                        optlist1 and options are described
                                        later in this entry.

    optlist2                               Up to 10 other optional,
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    optlist2                               Up to 10 other optional,
                                        less-often-used data
                                        communications parameters. The
                                        parameters for  optlist2 are
                                        described later in this entry.

    mode                                   One of the keywords  OUTPUT,
                                        INPUT, or  RANDOM (the default).

    filenum%                               Any unused file number between 1
                                        and 255, inclusive.

    reclen%                                The size of a random-access-mode
                                        buffer (128 bytes is the default).





The argument  optlist1 specifies the communication-line parameters and has
this syntax:


    speed , parity , data , stop

The following table lists the valid values for  optlist1 options:
╓┌───────┌─────────────────────┌─────────────────────┌───────────────────────╖
Option  Description           Range                 Default
────────────────────────────────────────────────────────────────────────────
speed   Baud rate (bits per   75, 110, 150, 300,    300
        second) of the        600, 1200, 1800,
        device to be opened)   2400, 9600

parity  Method of parity      N, E, O, S, M         E
        checking (none, even,
        odd, space, mark)

data    Number of data bits   5, 6, 7, or 8         7
        per byte

Option  Description           Range                 Default
────────────────────────────────────────────────────────────────────────────

stop    Number of stop bits   1, 1.5, or 2          1 *

                                                    * The default value is
                                                    1 for baud rates
                                                    greater than 110. For
                                                    baud rates less than
                                                    or equal to 110, the
                                                    default value is 1.5
                                                    when data is 5;
                                                    otherwise, the value
                                                    is 2.




Options in this list must be entered in the order shown. Use comma
placeholders for defaults. For example:

OPEN "COM1: ,N,8," FOR INPUT AS #1




Only the baud rates shown are supported. Any other value for  speed is
invalid.


If any options from  optlist2 are chosen, comma placeholders still must be
used even if all of the  optlist1 options are defaults. For example:

OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1




If you set  data to 8 bits per byte, you must specify no parity ( N).



Note

Because BASIC uses complete bytes (8 bits) for numbers, you must specify 8
data bits when transmitting or receiving numeric data.

The  optlist2 options can be specified in any order, and must be separated
by commas. There are three types of options: data mode, buffer size, and
handshaking.

The data-mode options ( ASC,  BIN, and  LF) are described in the following
table:


╓┌───────────────────────────────────────┌───────────────────────────────────╖
Option                                  Description
────────────────────────────────────────────────────────────────────────────
ASC                                     Opens the device in ASCII mode. In
                                        ASCII mode, tabs are expanded to
                                        blanks, carriage returns are
                                        forced at end-of-line, and Ctrl+Z
                                        means end-of-file. When the
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        means 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 elected by default
                                        unless ASC is specified.

                                        In binary mode, tabs are not
                                        expanded to spaces, a carriage
                                        return is not forced at the end of
                                        a line, and Ctrl+Z is not treated
                                        as end-of-file. When the channel
                                        is closed, Ctrl+Z will not be sent
                                        over the RS232 line.

LF                                      Allows communication files to be
                                        printed on a serial line printer.
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        printed on a serial line printer.
                                        Effective only with the ASC option.
                                        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 communications file
                                        that was opened with the LF option,
                                        stop when they see a carriage
                                        return, ignoring the line feed.



The buffer-size options for sequential modes (RB and TB) are described in
the following table:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Option                                  Description
────────────────────────────────────────────────────────────────────────────
RB n                                    Sets the size of the receive
                                        buffer to  n bytes. The initial
                                        buffer size, if  n or the RB
                                        option is omitted, is 512 bytes,
                                        unless overridden by the /C option
                                        on the QBX or BC command line. The
                                        default value, if  n or the RB
                                        option is omitted, is the current
                                        receive-buffer size. The maximum
                                        size is 32,767 bytes.

TB n                                    Sets the size of the receive
                                        buffer to  n bytes. The initial
                                        buffer size, if  n or the TB
                                        option is omitted, is 512 bytes.
                                        The default value, if  n or the TB
                                        option is omitted, is the current
                                        receive-buffer size.
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        receive-buffer size.




Handshake and timing options (RS, CD, CS, DS, and OP) are described in the
table below:


╓┌───────────────────────────────────────┌───────────────────────────────────╖
Option                                  Description
────────────────────────────────────────────────────────────────────────────
RS                                      Suppresses detection of Request To
                                        Send (RTS).

CD m                                    Specifies the timeout period on
                                        the Data Carrier Detect line (DCD).
                                        If no signal appears on the DCD
                                        line (the DCD line remains low)
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        line (the DCD line remains low)
                                        for more than  m milliseconds, a
                                        device timeout occurs. If a CD
                                        timeout occurs,  ERDEV contains
                                        130 (82H).

                                        The range for  m, if specified, is
                                        0 - 65,535 milliseconds, inclusive.
                                        The default value is 0, if the CD
                                        option is not used, or if  m is
                                        omitted. When  m is 0, either by
                                        default or assignment, it means
                                        that the state of the DCD line is
                                        to be ignored.

CS m                                    Specifies the timeout period on
                                        the Clear To Send line (CTS). If
                                        no signal appears on the CTS line
                                        (the CTS line remains low) for
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        (the CTS line remains low) for
                                        more than  m milliseconds, a
                                        device timeout occurs. If a CS
                                        timeout occurs,  ERDEV contains
                                        128 (80H).

                                        The range for  m, if specified, is
                                        0 - 65,535 milliseconds, inclusive.
                                        The default value is 1,000
                                        milliseconds, if the CS option is
                                        not used, or if  m is omitted.
                                        When  m is 0, either by default or
                                        assignment, it means the state of
                                        the CTS line is to be ignored.

DS m                                    Specifies the timeout period on
                                        the Data Set Ready line (DSR). If
                                        no signal appears on the DSR line
                                        (the DSR line remains low) for
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        (the DSR line remains low) for
                                        more than  m milliseconds, a
                                        device timeout occurs. If a DS
                                        timeout occurs,  ERDEV contains
                                        129 (81H).

                                        The range for  m, if specified, is
                                        0 - 65,535 milliseconds, inclusive.
                                        (See Note below.) The default
                                        value is 1,000 milliseconds, if
                                        the  DS option is not used, or if
                                        m is omitted. When  m is 0, either
                                        by default or assignment, it means
                                        that the state of the DSR line is
                                        to be ignored.

OP m                                    Specifies how long the  OPEN
                                        statement waits for all
                                        communications lines to become
Option                                  Description
────────────────────────────────────────────────────────────────────────────
                                        communications lines to become
                                        active. The range for  m is 0 -
                                        65,535 milliseconds, inclusive.
                                        The default value for  m, if the
                                        OP option is not used, is 10 times
                                        the CD or DS timeout value,
                                        whichever is greater. If OP is
                                        specified, but with  m omitted,
                                        OPEN  COM waits for 10 seconds.
                                        Use a relatively large value for
                                        the OP option compared to the CS,
                                        DS, or CD options.






Note

Under OS/2, specifying DS0 to ignore the state of the Data Set Ready (DSR)
line does not work properly. In this case, you will have to either not
ignore the DSR line or you will have to jumper the DSR line to an active
high signal line. Refer to serial port information that specifically
pertains to your hardware, and perform any modifications at your own risk.

The argument  filenum% is the number used to open the file.

The argument  reclen% is effective only in random-access mode and specifies
the length of the random-access buffer (default is 128 bytes). 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 argument  mode is one of the following string expressions:


╓┌──────────────────┌────────────────────────────────────────────────────────╖
Mode               Description
────────────────────────────────────────────────────────────────────────────
    OUTPUT            Specifies sequential output mode.
Mode               Description
────────────────────────────────────────────────────────────────────────────
    OUTPUT            Specifies sequential output mode.
    INPUT             Specifies sequential input mode.
    RANDOM            Specifies random-access mode.




If  mode is omitted, it is assumed to be random-access input/output.

The  OPEN COM statement performs the following steps in opening a
communications device:

    ■         The communications buffers are allocated and interrupts are
            enabled.

    ■         The Data Terminal Ready line (DTR) is set high.

    ■         If either of the OP or DS options is nonzero, the statement
            waits for the timeout period for the Data Set Ready line (DSR)
            to go high. If a timeout occurs, the process goes to step 6.

    ■         If the RS option is not specified, the Request To Send line
            (RTS) is set high.

    ■         If either of the OP or CD options is nonzero, the statement
            waits for the timeout period for the Data Carrier Detect line
            (DCD) to go high. If a timeout occurs, the process goes to step
            6. Otherwise, the RS232 device has been successfully opened.

    ■         If there is a timeout, the open fails. The process deallocates
            the buffers, disables interrupts, clears all of the control
            lines, and generates the message Device timeout. In addition,
            for DOS, the process sets the value of  ERDEV$ to COM and sets
            ERDEV to a value that indicates the signal line that timed out,
            according to the following table:

╓┌────────────────────┌──────────────────────────────────────────────────────╖
ERDEV value          Signal line
────────────────────────────────────────────────────────────────────────────
128 (80H)            Clear to Send (CTS) timeout
ERDEV value          Signal line
────────────────────────────────────────────────────────────────────────────
128 (80H)            Clear to Send (CTS) timeout
129 (81H)            Data Set Ready (DSR) timeout
130 (82H)            Data Carrier Detect (DCD) timeout





Note

If there is not an  OPEN COM statement in your program, you can reduce the
size of the .EXE file by linking your program with the stub file NOCOM.OBJ.


Example

See the  COM statements programming example, which uses the  OPEN COM
statement.


OPTION BASE Statement
────────────────────────────────────────────────────────────────────────────


Action

Declares the default lower bound for array subscripts.


Syntax



    OPTION  BASE  n%

Remarks


The  OPTION  BASE statement is never required.

The value of  n% must be either 0 or 1. The default base is 0. If the
following statement is executed, the default lowest value of an array
subscript is 1.

OPTION BASE 1


Note


The  TO clause in the  DIM statement provides an easier, more flexible way
to control the range of an array's subscripts. If the lower bound of an
array subscript is not explicitly set, then  OPTION  BASE can be used to
change the default lower bound to 1.

The  OPTION  BASE statement can be used only once in a module (source file)
and can appear only in the module-level code. An  OPTION  BASE statement
must be used before you can declare the dimensions for any arrays.

Chained programs can have an  OPTION  BASE statement if no arrays are passed
between them in a  COMMON block, or if the specified base is identical in
the chained programs. The chained-to program inherits the  OPTION  BASE
value of the chaining program if  OPTION  BASE is omitted in the latter.


See Also

    DIM,  LBOUND,  UBOUND


Example

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

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)




Output



The base subscript in array A is 1


The upper bound subscript in array A is 20


OUT Statement
────────────────────────────────────────────────────────────────────────────


Action

Sends a byte to a hardware I/O port.


Syntax



    OUT  port,  data%

Remarks


The  OUT statement complements the  INP function, which returns the byte
read from a hardware I/O port. The  OUT statement uses the following
arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    port                                   A numeric expression with an
                                        integer value between 0 and 65,535,
                                        inclusive, that identifies the
                                        destination hardware I/O port.

    data%                                  A numeric expression with an
                                        integer value between 0 and 255,
                                        inclusive, that is the data to be
                                        sent to the port.



The  OUT statement and the  INP function give a BASIC program direct control
over the hardware in a system through the I/O ports.  OUT and  INP must be
used carefully because they  directly manipulate the system hardware.


Note

The  OUT statement is not available in OS/2 protected mode.


See Also

    INP,  WAIT

Example


The following example uses the  OUT and  INP statements to control the timer
and speaker to produce a note:

' Play a scale using speaker and timer.


CONST WHOLE = 5000!, QRTR = WHOLE / 4!


CONST C = 523!, D = 587.33, E = 659.26, F = 698.46, G = 783.99


CONST A = 880!, B = 987.77, C1 = 1046.5


CALL Sounds(C, QRTR): CALL Sounds(D, QRTR)


CALL Sounds(E, QRTR): CALL Sounds(F, QRTR)


CALL Sounds(G, QRTR): CALL Sounds(A, QRTR)


CALL Sounds(B, QRTR): CALL Sounds(C1, WHOLE)





SUB Sounds (Freq!, Length!) STATIC


' Ports 66, 67, and 97 control timer and speaker.


    ' Divide clock frequency by sound frequency


    ' to get number of "clicks" clock must produce.


    Clicks% = CINT(1193280! / Freq!)


    LoByte% = Clicks% AND &HFF


    HiByte% = Clicks% \ 256


    OUT 67, 182' Tell timer that data is coming.


    OUT 66, LoByte%' Send count to timer.


    OUT 66, HiByte%


    SpkrOn% = INP(97) OR &H3' Turn speaker on by setting


    OUT 97, SpkrOn%' bits 0 and 1 of PPI chip.


    FOR I! = 1 TO Length!: NEXT I!' Leave speaker on.


    SpkrOff% = INP(97) AND &HFC ' Turn speaker off.


    OUT 97, SpkrOff%


END SUB

PAINT Statement
────────────────────────────────────────────────────────────────────────────


Action

Fills a graphics area with the color or pattern specified.


Syntax

    PAINT  STEP ( x!, y!) , paint , bordercolor& ,  background$

Remarks


The following list describes the parts of the  PAINT statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   Keyword indicating that
                                        coordinates are 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 of 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,
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                            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.
                                        (See the  COLOR,  PALETTE, and
                                        SCREEN statements for discussions
                                        of valid colors, numbers, and
                                        attributes.)

                                        If the argument  paint is a string
                                        expression,  PAINT "tiles," 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.

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

    bordercolor&                           A numeric expression that
                                        identifies the color attribute to
                                        use to paint the border of the
                                        figure. When the border color is
                                        encountered, painting of the
                                        current line stops. If the border
                                        color is not specified, the  paint
                                        argument is used.

    background$                            A string value that gives 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
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        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 statement permits coordinates outside the screen or viewport.

"Tiling" is the design of a  PAINT pattern represented in string form. The
tile string is eight bits wide and up to 64 bytes long. Each byte masks
eight bits along the x axis when plotting points. The syntax for
constructing the tile mask is

A$ =  CHR$( arg1)+ CHR$( arg2)+...+ CHR$( argn)  PAINT ( x, y), A$

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 background tile slice.
If you specify more than two consecutive bytes, BASIC generates an error
message Illegal function call.

Tiling also can be done to produce various patterns of different colors. See
Chapter 5, "Graphics" in the  Programmer's Guide for a complete description
of how to do tiling.


See Also

    CHR$,  CIRCLE,  DRAW,  LINE,  SCREEN Statement


Example

The following 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 tail in magenta.
LINE -STEP (60, 20), 2
LINE -STEP (-60, 20), 2
PAINT (50, 100), 1, 2' Paint tail cyan.

CIRCLE (250,100),30,0,PI*3/4,PI* 5/4,1.5' Draw gills in black.
FOR Y = 90 TO 110 STEP 4
    LINE (40, Y)-(52, Y), 0' Draw comb in tail.
NEXT

PALETTE, PALETTE USING Statements
────────────────────────────────────────────────────────────────────────────


Action

Change one or more colors in the palette.


Syntax


    PALETTE  attribute%,  color&

    PALETTE USING  array-name ( array-index)

Remarks


The  PALETTE and  PALETTE USING statements use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    attribute%                             The palette attribute to be
                                        changed.

    color&                                 The display color number to be
                                        assigned to the attribute. The
                                        color& value must be a
                                        long-integer expression for the
                                        IBM Video Graphics Array adapter
                                        (VGA) and IBM Multicolor Graphics
                                        Array adapter (MCGA) in screen
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        Array adapter (MCGA) in screen
                                        modes 11 to 13. Integer or
                                        long-integer expressions can be
                                        used with the IBM Enhanced
                                        Graphics Adapter (EGA).

    array-name                             An array that contains more than
                                        one display color. It must be a
                                        long-integer array for VGA and
                                        MCGA adapters in screen modes 11
                                        to 13. Otherwise, it 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 arguments  array-name and
                                        array-index are used to change
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        array-index are used to change
                                        more than one palette assignment
                                        with a single  PALETTE  USING
                                        statement.





The  PALETTE statement works  only on systems equipped with the EGA, VGA, or
MCGA adapters. The  PALETTE statement is not supported in screen modes 3 or
4.

The  PALETTE statement provides a way of mapping display colors (the actual
binary values used by the adapter) to color attributes (a smaller set of
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, the 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. Changing the display color assigned to an attribute immediately
changes those colors currently displayed on the screen associated with that
attribute.

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 following  DRAW
statement selects attribute 3, and draws a line of 100 pixels using the
display color associated with attribute 3, in this case also 3:

DRAW "C3L100"

If the following statement is executed, the color associated with attribute
3 is changed to color 2:

PALETTE 3,2

All text or graphics currently on the screen displayed using attribute 3,
including the line that is 100 pixels long, are instantaneously changed to
color 2. Text or graphics subsequently dis-played with attribute 3 also are
displayed in color 2. The new palette of colors contains 0, 1, 2, and 2. A
PALETTE statement with no arguments sets the palette back to the default
color values.

With  PALETTE  USING, all entries in the palette can be modified in one
statement. Each attribute in the palette is assigned a corresponding color
from the array.

The dimensions for the array must be large enough to set all the palette
entries after  array-index. For example, if you are assigning colors to a
palette with 16 attributes and the  array-index argument is 5 (the first
array element to use in resetting the palette), then the dimensions for the
array must be declared to hold at least 20 elements (because the number of
elements from 5 to 20, inclusive, is 16):

DIM PAL%(20)
.
    .
    .
PALETTE USING PAL%(5)
Note that a  color& argument of -1 in the array leaves the attribute
unchanged in the palette. All other negative numbers are invalid values for
color.

Attribute 0 is always the screen background color. 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. You can also use the  COLOR
statement to change the screen background color in modes 1 and 7 through 10.

The 64 EGA colors are derived from four levels each of red, green, and blue.
For example, black is composed of red, green, and blue levels of (0,0,0),
bright white is (3,3,3), dark gray is (1,1,1), and so on. The best way to
see the Microsoft BASIC color code (0-63) associated with each combination
of red, green, and blue levels is to run the following program:


' Display the EGA color codes 1 through 63
' using color code 0 (black) as background.
DEFINT A-Z
SCREEN 9                      ' Establish EGA screen mode.
' Display a set of nine color bars.
FOR ColorCode% = 1 TO 9
LINE (((ColorCode% * 64) - 24), 40)-STEP(60, 140), ColorCode%, BF
NEXT ColorCode%
' Display seven sets of nine color bars.
' A new set is displayed each time user presses a key.
FOR Set% = 0 TO 6
FOR ColorBar% = 1 TO 9
DisplayCode% = (Set% * 9) + ColorBar%
LOCATE 15, (ColorBar% * 8)
PRINT DisplayCode%
PALETTE ColorBar%, DisplayCode%
NEXT ColorBar%
SLEEP
NEXT Set%
END
The following table lists attribute and color ranges for various adapter
types and screen modes. See the  SCREEN statement for the list of colors
available for various screen modes, monitor, and graphics-adapter
combinations.
╓┌───────────┌───────────┌───────────┌───────────┌───────────┌───────────────╖
Screen      Monitor     Adapter     Attribute   Color       PALETTE
mode        attached                range       range       supported
────────────────────────────────────────────────────────────────────────────
0           Monochrome  MDPA        0 - 15                  No

            Monochrome  EGA         0 - 15      0 - 2       Yes

            Color       CGA         0 - 15                  No

            Color/Enha  EGA         0 - 15      0 - 15 / 0  Yes
            nced1                               - 63

            Analog      VGA         0 - 15      0 - 63      Yes

            Color/Anal  MCGA        0 - 15      0 - 63      No
            og

1           Color       CGA         0 - 3       0 - 152     No

Screen      Monitor     Adapter     Attribute   Color       PALETTE
mode        attached                range       range       supported
────────────────────────────────────────────────────────────────────────────

            Color/Enha  EGA         0 - 3       0 - 15      Yes
            nced1

            Analog      VGA         0 - 3       0 - 15      Yes

            Color/Anal  MCGA        0 - 1       0 - 15      No
            og

2           Color       CGA         0 - 1                   No

            Color/Enha  EGA         0 - 1       0 - 15      Yes
            nced1

            Analog      VGA         0 - 1       0 - 15      Yes

            Color/Anal  MCGA        0 - 1       0 - 15      No
            og
Screen      Monitor     Adapter     Attribute   Color       PALETTE
mode        attached                range       range       supported
────────────────────────────────────────────────────────────────────────────
            og

3           Monochrome  HGC         0 - 1                   No

4           Color/Enha  OCGA/       0 - 1       0 - 153     No
            nced        OEGA/ OVGA

7           Color/Enha  EGA         0 - 15      0 - 15      Yes
            nced1

                        VGA         0 - 15      0 - 15      Yes

8           Color/Enha  EGA         0 - 15      0 - 15      Yes
            nced1

                        VGA         0 - 15      0 - 15      Yes

9           Enhanced1   EGA4        0 - 3       0 - 63      Yes
Screen      Monitor     Adapter     Attribute   Color       PALETTE
mode        attached                range       range       supported
────────────────────────────────────────────────────────────────────────────
9           Enhanced1   EGA4        0 - 3       0 - 63      Yes

            Enhanced1   EGA5        0 - 15      0 - 63      Yes

            Analog      VGA         0 - 16      0 - 63      Yes

10          Monochrome  EGA         0 - 3       0 - 8       Yes

            Analog      VGA         0 - 3       0 - 8       Yes

11          Analog      VGA         0 - 1       0 -         Yes
                                                262,1436

            Analog      MCGA        0 - 1       0 -         Yes
                                                262,1436

12          Analog      VGA         0 - 15      0 -         Yes
                                                262,1436
Screen      Monitor     Adapter     Attribute   Color       PALETTE
mode        attached                range       range       supported
────────────────────────────────────────────────────────────────────────────
                                                262,1436

13          Analog      VGA         0 - 255     0 -         Yes
                                                262,1436

            Analog      MCGA        0 - 255     0 -         Yes
                                                262,1436



    1  IBM Enhanced Color Display.
    2  Color range available for attribute 0 only.
    3  Color range available for attribute 1 only.
    4  With 64K of EGA memory.
    5  With more than 64K of EGA memory.
    6  Range of display colors is actually from 0 to 4,144,959, but only
        262,144 of these can be displayed.


To calculate a VGA 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 = 65,536 * blue + 256 * green + red

This formula yields integer values from 0 to 4,144,959, but 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 intensity value calculation would be gray value = (.11 * 45) + (.59 *
20) + (.30 * 20) = 22. The fractional part of the result is dropped.


See Also

    COLOR,  SCREEN Statement


Example

The following example illustrates the use of the  PALETTE and  PALETTE USING
statements:

DEFINT A-Z
DIM SHARED PaletteArray(15)
CONST ASPECT = 1 / 3
SCREEN 8' 640 x 200, 16 color resolution.
' Initialize PaletteArray.
FOR I = 0 TO 15
    PaletteArray(I) = I
NEXT I
' Draw and paint concentric ellipses.
FOR ColorVal = 15 TO 1 STEP -1
    Radius = 20 * ColorVal
    CIRCLE (320, 100), Radius, ColorVal, , , ASPECT
    PAINT (320, 100), ColorVal
NEXT
' Shift the palette until a key is pressed.
DO
    FOR I = 1 TO 15
        PaletteArray(I) = (PaletteArray(I) MOD 15) + 1
    NEXT I
    PALETTE USING PaletteArray(0)
    ' Map the black background to a random color.
    PALETTE 0, PaletteArray(INT(RND * 15))
LOOP WHILE INKEY$ = ""

PCOPY Statement
────────────────────────────────────────────────────────────────────────────


Action

Copies one video memory page to another.


Syntax


    PCOPY  sourcepage%,  destinationpage%

Remarks


The  PCOPY statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    sourcepage%                            A numeric expression with an
                                        integer value between 0 and  n
                                        that identifies a video memory
                                        page to be copied.

Argument                                Description
────────────────────────────────────────────────────────────────────────────

    destinationpage%                       A numeric expression with an
                                        integer value between 0 and  n
                                        that identifies the video memory
                                        page to be copied to.



The value of  n is determined by the current size of video memory and the
current screen mode. The number of video memory pages available depends on
the current screen mode, the graphics adapter, and how much screen memory is
available with the adapter.


Note

Multiple video pages are not available in OS/2 protected mode, so the  PCOPY
statement has no effect.

See the  SCREEN statement for more information about the number of pages
available in different modes


See Also

    CLEAR,  SCREEN Statement


Example

See the  SCREEN statement programming example, which uses the  PCOPY
statement.

PEEK Function
────────────────────────────────────────────────────────────────────────────


Action

Returns byte value stored at a specified memory location. Complements the
POKE statement.


Syntax


    PEEK( address)

Remarks


The returned value is an integer between 0 and 255, inclusive. The argument
address is a value between 0 and 65,535, inclusive.  The argument  address
is treated as the offset from the current default segment (as set by the
DEF SEG statement).

If  address is a single- or double-precision floating-point value, or a long
integer, it is converted to a 2-byte integer.

When using  PEEK to return a byte from a far-string array, use the  SSEG and
    SADD functions to obtain the current segment and offset. For example:

DEF SEG = SSEG(a$) ' Set current segment address to address of a$.

StringOffset = SADD(a$) ' Determine string's location within segment.

PEEK(StringOffset)' Return the byte stored at this location.

Direct string manipulation with  PEEK should be used cautiously, because
BASIC moves string locations during run time.


PEEK and Expanded Memory Arrays

Do not use  PEEK to return a byte from an expanded memory array. If you
start QBX with the /Ea switch, any of these arrays may be stored in expanded
memory:

    ■   Numeric arrays less than 16K in size.

    ■   Fixed-length string arrays less than16K in size.

    ■   User-defined-type arrays less than 16K in size.




If you want to use  PEEK to return a byte from an array, first start QBX
without the /Ea switch. (Without the /Ea switch, no arrays are stored in
expanded memory.)

For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.


Note

When programming with OS/2 protected mode, note that any address referred to
by  PEEK must be readable. If  PEEK refers to an address for which your
process does not have read permission, the operating system may generate a
protection exception, or BASIC may generate the error message Permission
denied.


See Also

    DEF SEG;  POKE;  SADD;  SSEG;  SSEGADD;  VARPTR,  VARSEG;  VARPTR$


Example

See the  DEF SEG statement programming example, which uses the  PEEK
statement.


PEN Function
────────────────────────────────────────────────────────────────────────────


Action

Returns lightpen status.


Syntax


    PEN( n%)

Remarks


The argument  n% is an integer value between 0 and 9, inclusive, that
specifies what information is to be returned about the status of the
lightpen.


Note

The  PEN function does not work when the mouse driver is enabled because the
mouse driver uses the  PEN function's BIOS calls. Use mouse function 14 to
disable the driver's lightpen emulation. Mouse function 13 turns emulation
back on. See your mouse manual for more information.

The following list describes the values for  n% and the corresponding values
returned by  PEN:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Value returned
────────────────────────────────────────────────────────────────────────────
0                                       Whether the pen was down since the
                                        last function call  (-1 if yes, 0
                                        if no).

1                                       The x coordinate of the last pen
                                        press.

2                                       The y coordinate of the last pen
                                        press.

3                                       The current pen switch status (-1
                                        if down, 0 if up).

4                                       The x coordinate where the pen
                                        last left the screen.

Argument                                Value returned
────────────────────────────────────────────────────────────────────────────

5                                       The y coordinate where the pen
                                        last left the screen.

6                                       The character row of the last pen
                                        press.

7                                       The character column of the last
                                        pen press.

8                                       The character row where the pen
                                        last left the screen.

9                                       The character column where the pen
                                        last left the screen.-



The light-pen coordinate system is identical to the current graphics screen
mode, without viewport or window considerations.


Note

The  PEN function is not available in OS/2 protected mode.


See Also

    PEN Statements


Example

See the  ON PEN statement programming example, which uses the  PEN function.


PEN Statements
────────────────────────────────────────────────────────────────────────────


Action

Enable, disable, or suspend lightpen-event trapping.


Syntax


    PEN ON

    PEN OFF

    PEN STOP

Remarks


The  PEN ON statement enables lightpen-event trapping. A lightpen event
occurs whenever the lightpen is activated by pressing the tip to the screen
or pressing the touch ring. If a lightpen event occurs after a  PEN  ON
statement, the routine specified in the  ON  PEN statement is executed.

The  PEN OFF statement disables lightpen-event trapping. No trapping takes
place until a  PEN  ON statement is executed. Events occurring while
trapping is off are ignored.

The  PEN  STOP statement suspends lightpen-event trapping. No trapping takes
place until a  PEN  ON statement is executed. Events occurring while
trapping is suspended are remembered and processed when the next  PEN  ON
statement is executed. However, remembered events are lost if  PEN  OFF is
executed.

When a lightpen-event trap occurs (that is, the  GOSUB is performed), an
automatic  PEN STOP is executed so that recursive traps cannot take place.
The  RETURN statement from the trapping routine automatically performs a
PEN ON statement unless an explicit  PEN OFF was performed inside the
routine.

A  PEN ON statement must be executed before you use the  PEN function. If a
Pen function is executed when the lightpen is off, BASIC generates the error
message Illegal function call.


Note

The lightpen requires an IBM Color Graphics Adapter.

The  PEN statements are not available for OS/2 protected mode.

For more information, see Chapter 9, "Event Handling" in the  Programmer's
Guide.


See Also

    ON  event


Example


The following example uses the  PEN statements and the  PEN function to
enable and display current lightpen status (up or down) and position (x and
y coordinates). The  ON PEN statement passes control to the PenReport
routine when a lightpen event occurs.

' Note: Do not run this program with your mouse driver enabled.
CLS                ' Clear screen.
COLOR 0, 7         ' Set black on white.
CLS                ' Clear screen.
PEN ON             ' Enable lightpen
ON PEN GOSUB PenReport
DO
    LOCATE 23, 12
    PRINT "Press the lightpen against the screen to see a report."
    LOCATE 24, 17
    PRINT "  Press the Spacebar to exit the program.     ";
LOOP UNTIL INKEY$ = " "
PEN OFF            ' Disable lightpen.
COLOR 7, 0         ' Set back to black on white.
CLS                ' Clean up the screen.
END

PenReport:
    DO
        P = PEN(3)
        ' Report lightpen status and get X and Y position.
        LOCATE 10, 27
        PRINT "A Pen event has occurred."
        LOCATE 24, 17
        PRINT "Press ANY key to exit the lightpen report.";
        LOCATE 12, 30
        PRINT "lightpen is ";
        IF P THEN
            PRINT "Down"
            X = PEN(4): Y = PEN(5)
        ELSE
            PRINT "Up  "
            X = 0: Y = 0
        END IF
        ' Report the X and Y position.
        LOCATE 14, 22
        PRINT "X Position ="; X; "   "
        LOCATE 14, 40
        PRINT "Y Position ="; Y; "   "
    LOOP WHILE INKEY$ = ""
    RETURN

PLAY Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the number of notes currently in the background-music queue.


Syntax


    PLAY ( n)

Remarks


The argument  n is a dummy argument and can be any numeric value.

    PLAY( n) will return 0 when music is running in the foreground.

The  PLAY function is not available for OS/2 protected mode.


See Also

    ON  event,  PLAY Statements (Event Trapping),  PLAY Statement (Music)


Example

The following example plays continuous music by calling an event-handling
routine when the background music buffer goes from three to two notes:

CLS
' Call routine Replay when the music buffer goes
    ' from 3 to 2 notes.
ON PLAY(3) GOSUB Replay
' Turn on event trapping for PLAY.
PLAY ON
' Define a string containing the melody.
FElise$ = "o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A"
PLAY "MB X" + VARPTR$(FElise$)
' Suspend event trapping until next PLAY ON but remember
    ' events that occur while event trapping is disabled.
PLAY STOP
' Introduce a variable-length delay.
LOCATE 23, 1: PRINT "Press any key to continue."
DO
LOOP WHILE INKEY$ = ""

' Re-enable play-event trapping, remembering that a play event

    ' has occurred.
PLAY ON
LOCATE 23, 1: PRINT "Press any key to stop.    "
' Loop until a key is pressed.
DO
    GOSUB BackGround
LOOP WHILE INKEY$ = ""
' Disable play-event processing.
PLAY OFF
' Count down to 0 notes in the queue.
DO
    GOSUB BackGround
LOOP UNTIL NoteCount = 0
END

' Play event-handling routine.
Replay:
    ' Increment and print a counter each time.
    Count% = Count% + 1
    LOCATE 3, 1: PRINT "Replay routine called"; Count%; "time(s)";
    ' Play it again to fill the buffer.
    PLAY "MB X" + VARPTR$(FElise$)
RETURN

' Background music queue reporting routine.
BackGround:
    ' Get a note count.
    NoteCount = PLAY(0)
    LOCATE 1, 1
    PRINT "Background queue notes remaining --> "; NoteCount
    ' Loop until Notecount changes or equals 0.
    DO
    LOOP UNTIL NoteCount <> PLAY(0) OR NoteCount = 0
RETURN

PLAY Statements (Event Trapping)
────────────────────────────────────────────────────────────────────────────


Action

Enable, disable, and suspend play-event trapping.


Syntax


    PLAY ON
    PLAY OFF
    PLAY STOP

Remarks


The  PLAY  ON statement enables play-event trapping. (A play event occurs
when the number of notes in the background music queue drops below the limit
you set with the  ON  PLAY statement.) If a play event occurs after a  PLAY
ON statement, the routine specified in the  ON  PLAY statement is executed.

The  PLAY  OFF statement disables play-event trapping. No trapping takes
place until a  PLAY  ON statement is executed. Events occurring while
trapping is off are ignored.

    PLAY  STOP suspends play-event trapping. No trapping takes place until a
PLAY  ON statement is executed. Events occurring while trapping is suspended
are remembered and processed when the next  PLAY  ON statement is executed.
However, remembered events are lost if  PLAY  OFF 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 operation from the trapping routine automatically executes a
PLAY ON statement unless an explicit  PLAY OFF was performed inside the
routine.

For more information, see Chapter 9, "Event Handling" in the  Programmer's
Guide.


Note

The  PLAY statements (event trapping) are not available for OS/2 protected
mode.


See Also

    ON  event,  PLAY Function,  PLAY Statements (Music)


Example

See the  PLAY function programming example, which uses the  PLAY ON
statement.


PLAY Statement (Music)
────────────────────────────────────────────────────────────────────────────


Action

Plays music as specified by a string.


Syntax


    PLAY  commandstring$

Remarks


The  commandstring$ argument is a string expression that contains one or
more music commands listed later in this entry.

The  PLAY statement uses a concept similar to  DRAW in that it embeds a
music macro language (described below) in one statement. A set of commands,
used as part of the  PLAY statement, specifies a particular action.

The  VARPTR$( variablename) form for variables must be used with  DRAW and
PLAY (music) statements in BASIC to execute substrings that contain
variables. BASICA supports both the  VARPTR$ syntax and the syntax
containing just the variable name. For example, consider these BASICA
statements:

PLAY "XA$"
PLAY "O = I"

For BASIC programs, those statements should be written like this:

PLAY "X" + VARPTR$(A$)
PLAY "O=" + VARPTR$(I)

The  commandstring$ music commands are described as follows:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Command                                 Action
────────────────────────────────────────────────────────────────────────────
Octave command

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 command

Command                                 Action
────────────────────────────────────────────────────────────────────────────

A - G                                   Plays a note in the range A - G.
                                        The number sign (#) or the plus
                                        sign (+) after a note specifies
                                        sharp; a minus sign (-) specifies
                                        flat.

N n                                     Plays note  n. The range for n is
                                        0 - 84 (in the seven possible
                                        octaves, there are 84 notes); an
                                        n value of 0 means a rest.



Duration command

L  n                                    Sets the length of each note. L4
                                        is a quarter note, L1 is a whole
                                        note, etc. The range for  n is 1 -
Command                                 Action
────────────────────────────────────────────────────────────────────────────
                                        note, etc. The range for  n is 1 -
                                        64. The length can also follow the
                                        note when a change of length only
                                        is desired for a particular note.
                                        For example, A16 can be equivalent
                                        to L16A.

MN                                      Sets "music normal" so that each
                                        note will play 7/8 of the time
                                        determined by the length (L).

ML                                      Sets "music legato" so that each
                                        note will play the full period set
                                        by length (L).

MS                                      Sets "music staccato" so that each
                                        note will play 3/4 of the time
                                        determined by the length (L).

Command                                 Action
────────────────────────────────────────────────────────────────────────────



Tempo command

P  n                                    Specifies a pause, ranging from 1
                                        to 64. This option corresponds to
                                        the length of each note, set with
                                        L  n.

T  n                                    Sets the "tempo," or the number of
                                        L4  quarter notes in one minute.
                                        The range for  n is 32-255. The
                                        default for  n is 120.

                                        Because of the slow
                                        clock-interrupt rate, some notes
                                        will not play at higher tempos
                                        (L64 at T255, for example).
Command                                 Action
────────────────────────────────────────────────────────────────────────────
                                        (L64 at T255, for example).



Mode command

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
Command                                 Action
────────────────────────────────────────────────────────────────────────────
                                        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.



Suffix

    # or +                                 Follows a specified note and turns
                                        it into a sharp.

    -                                      Follows a specified note and turns
                                        it into a flat..

    .                                      A period after a note causes the
                                        note to play one-and-a-half times
Command                                 Action
────────────────────────────────────────────────────────────────────────────
                                        note to play one-and-a-half times
                                        the length determined by L*T
                                        (length times 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.



Command                                 Action
────────────────────────────────────────────────────────────────────────────

Substring command

"X" + VARPTR$(string)                   Executes a substring. This
                                        powerful command enables you to
                                        execute a second substring from a
                                        string. You can have one string
                                        expression execute another, which
                                        executes a third, and so on.




Note

The  PLAY statement is not available in OS/2 protected mode.


See Also

    BEEP,  ON  event,  PLAY Function,  PLAY Statements (Event Trapping),  SOUND


Example

See the  PLAY function programming example, which uses the  PLAY statement.



PMAP Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the window coordinate equivalent to a specified viewport coordinate,
or the viewport coordinate equivalent to a specified window coordinate.


Syntax


    PMAP ( expression#,  n%)

Remarks
The argument   expression# specifies the known coordinate, either an x
coordinate or y coordinate, in the window or in the viewport. The argument
n% specifies the mapping function and can have one of the four following
values:
╓┌──────────────────────┌──────────┌─────────────────────────────────────────╖
If expression is       n must be  Returns:
────────────────────────────────────────────────────────────────────────────
Window x coordinate    0          Viewport x coordinate
Window y coordinate    1          Viewport y coordinate
Viewport x coordinate  2          Window x coordinate
Viewport y coordinate  3          Window y coordinate


The four  PMAP functions allow you to find equivalent point locations
between the window coordinates created with the  WINDOW statement and the
absolute screen coordinates or viewport coordinates as defined by the  VIEW
statement.

If no  VIEW statement has been executed, or the most recently executed  VIEW
statement has no arguments, the viewport coordinates are equivalent to the
absolute screen coordinates established by the most recently executed
SCREEN statement.


See Also

    POINT,  VIEW,  WINDOW


Example

See the  WINDOW statement programming example, which uses the  PMAP
function.

POINT Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the current horizontal or vertical position of the graphics cursor,
or the color of a specified pixel.


Syntax 1

    POINT ( x%,y%)

Syntax 2

    POINT ( number%)

Remarks


The coordinates  x% and  y% refer to the viewport coordinates of the pixel
being evaluated by the  POINT function;  POINT returns the color number of
the indicated pixel. If the specified pixel is out of range,  POINT returns
the value -1.

    POINT with the argument  number% allows the user to retrieve the current
graphics-cursor coordinates, as described in the following table:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Value returned
────────────────────────────────────────────────────────────────────────────
0                                       The current viewport x coordinate.

1                                       The current viewport y coordinate.

2                                       The current window x coordinate.
                                        This returns the same value as the
                                        POINT(0) function if the  WINDOW
                                        statement has not been used.

3                                       The current window y coordinate.
                                        This returns the same value as the
                                        POINT(1) function if the  WINDOW
                                        statement has not been used.
Argument                                Value returned
────────────────────────────────────────────────────────────────────────────
                                        statement has not been used.






See Also

Pmap, Screen Statement, VIEW, Window


Example


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

POKE Statement
────────────────────────────────────────────────────────────────────────────


Action

Writes a byte value into a specified memory location.


Syntax


    POKE  address,  byte%

Remarks


The  POKE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    address                                An offset into the memory segment
                                        specified by the current default
                                        segment (as set by the  DEF SEG
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        segment (as set by the  DEF SEG
                                        statement). The value of  address
                                        is between 0 and 65,535, inclusive.

    byte%                                  The data byte to be written into
                                        the memory location. The argument
                                        byte% is an integer value between
                                        0 and 255, inclusive. Any value
                                        for  byte% that must be
                                        represented in more than one byte
                                        (for instance, a long integer or
                                        any real number) is accepted;
                                        however, only the low order byte
                                        is used. The value of any high
                                        order bytes is ignored.





If  address is a single- or double-precision floating-point value, or a long
integer, it is converted to a 2-byte integer.

The  POKE statement complements the  PEEK function.

Before using  POKE to directly manipulate data stored in far memory, use the
    DEF SEG statement to set the current segment address. For example:

DEF SEG = SSEG(a$)' Set current segment address to address of a$.

Offset1 = SADD(a$)' Determine string's location within the segment.

' Write the byte stored in:

POKE Offset1, PEEK(Offset2)


Note



BASIC moves string locations during run time. Therefore, the  DEF SEG
statement must be executed immediately before using the  POKE statement.


POKE and Expanded Memory Arrays

Do not use  POKE to manipulate expanded memory arrays. If you start QBX with
the /Ea switch, any of these arrays may be stored in expanded memory:

    ■   Numeric arrays less than 16K in size.

    ■   Fixed-length string arrays less than 16K in size.

    ■   User-defined-type arrays less than 16K in size.





If you want to use  POKE to manipulate an array, first start QBX without the
/Ea switch. (Without the /Ea switch, no arrays are stored in expanded
memory.)


For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.

Any address referred to by  POKE in OS/2 protected mode must be open for
writing. If  POKE refers to a memory address for which your process does not
have write permission, the operating system may generate a protection
exception, or BASIC may generate the error message Permission denied.


Warning

Use  POKE carefully. If used incorrectly, it can cause BASIC or the
operating system to fail.


See Also

    DEF SEG;  PEEK;  VARPTR,  VARSEG;  VARPTR$


Example

See the  DEF SEG statement programming example, which uses the  POKE
statement.


POS Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the current horizontal position (column) of the text cursor.


Syntax


    POS( numeric-expression)

Remarks


If the screen cursor is in the leftmost column, this function returns a
value of 1. To return the current vertical-line position of the cursor, use
the  CSRLIN function. The argument  numeric-expression can be any numeric
expression; while it passes no information, it is required to maintain
consistent BASIC function syntax.


See Also

    CSRLIN,  LPOS


Example

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

PRESET Statement
────────────────────────────────────────────────────────────────────────────


Action

Draws a specified point on the screen.


Syntax


    PRESET  STEP( x%,  y%) ,  color&

Remarks


The following list describes the parts of the  PRESET statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   Indicates that  x% and  yc% are
                                        relative, not absolute. The
                                        coordinates are treated as
                                        distances from the most recent
                                        graphics cursor location, not
                                        distances from the (0,0) screen
                                        coordinate.

                                        For example, if the most recent
                                        graphics cursor location  were
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        graphics cursor location  were
                                        (10,10), PRESET STEP (10,5) would
                                        draw a point  at (20,15).

    x%                                     The x coordinate of the pixel that
                                        is to be set.

    y%                                     The y coordinate of the pixel that
                                        is to be set.

    color&                                 The color attribute for the
                                        specified pixel.



The valid range of screen coordinate values and color values depends on the
screen mode established by the most recently executed  SCREEN statement. If
a coordinate is outside the current viewport, no action is taken, nor is an
error message generated.

If you use  PRESET without  color&, the background color is selected. In
contrast, if you use  PSET without  color&, the foreground color is
selected. Otherwise, the two statements work exactly the same.


See Also

    PSET


Example

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

PRINT Statement
────────────────────────────────────────────────────────────────────────────


Action

Outputs data to the screen.


Syntax


    PRINT  expressionlist {;|,}

Remarks


If  expressionlist is omitted, a blank line is displayed. If  expressionlist
is included, the values of its expressions are printed on the screen.

The  PRINT statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    expressionlist                         The values that are displayed on
                                        the screen. The argument
                                        expressionlist can contain numeric
                                        or string expressions. String
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        or string expressions. String
                                        literals must be enclosed in
                                        quotation marks.

{;|,}                                   Determines the screen location of
                                        the text cursor for the next
                                        screen input or output statement:
                                        a semicolon means the text cursor
                                        is placed immediately after the
                                        last character displayed; a comma
                                        means the text cursor is placed at
                                        the start of the next print zone.





The  PRINT statement supports only elementary BASIC data types (integers,
long integers, single-precision real numbers, double-precision real numbers,
currency, and strings). To print information from a record, use individual
record-element names in the  PRINT statement, as in the following code
fragment:

TYPE MyType

Word AS STRING * 20

Count AS LONG

END TYPE

DIM Myrec AS MyType



PRINT Myrec.Word



Item-Format Rules

A printed number always is followed by a space. If the number is positive,
it also is preceded by a space; if the number is negative, it is preceded by
a minus sign (-). If a single-precision number can be expressed as seven or
fewer digits with no loss of accuracy, then it is printed in fixed-point
format; otherwise, floating-point format is used. For example, the number
1.1E-6 is output displayed as .0000011, but the number 1.1E-7 is output as
1.1E-7.

If a double-precision number can be expressed with 15 or fewer digits and no
loss of accuracy, it is printed in fixed-point format; otherwise,
floating-point format is used. For example, the number 1.1D-14 is displayed
as .000000000000011, but the number 1.1D-15 is output as 1.1D-15.


Print-Line Format Rules

The print line is divided into print zones of 14 spaces each. The position
of each printed item is determined by the punctuation used to separate the
items in  expressionlist: 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. Using one or more spaces or tabs between expressions has the
same effect as using a semicolon.

If a comma or a semicolon terminates the list of expressions, the next
PRINT statement to execute 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.


See Also

    PRINT #,  PRINT  USING,  WIDTH


Examples

The following examples show the use of commas and semicolons with  PRINT.

First 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


Output





10            0            -25            3125


In the second example, the semicolon at the end of the first  PRINT
statement makes the first two  PRINT statements display output 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



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


In the third 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


Output





5  10  10  20  15  30  20  40  25  50

PRINT # Statement
────────────────────────────────────────────────────────────────────────────


Action

Writes data to a sequential device or file.


Syntax


    PRINT #  filenumber%,  USING  formatstring$;  expressionlist{,|;}

Remarks


The  PRINT # statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number of an open sequential
                                        file.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        file.

    formatstring$                          Specifies the exact format in
                                        which values are written to the
                                        file; described under  PRINT
                                        USING.

    expressionlist                         Numeric or string expressions to
                                        be written to the file.



Spaces, commas, and semicolons in  expressionlist have the same meaning as
they have in a  PRINT statement.

If you omit  expressionlist, the  PRINT # statement prints a blank line in
the file.

    PRINT # works like  PRINT and writes an image of the data to the file, just
as the data would be displayed on the terminal screen. For this reason, be
careful to delimit the data so it is output correctly. If you use commas as
delimiters, the blanks between print fields are also written to the file.
For more information, see "File and Device I/O" in the  Programmer's Guide.


See Also

    OPEN (File I/O),  PRINT,  PRINT  USING,  WRITE #


Example

The following example shows the effects of using data delimiters with  PRINT
    #:

CONST A$ = "CAMERA, AUTOFOCUS", B$ = "September 20, 1989", C$ = "42"

Q$ = CHR$(34)

OPEN "INVENT.DAT" FOR OUTPUT AS #1' Open INVENT.DAT for writing.

PRINT #1, A$; B$; C$ ' Write without delimiters.

PRINT #1, Q$; A$; Q$; Q$; B$; Q$; Q$; C$; Q$' With delimiters.

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$

NEXT

CLOSE #1



Output





CAMERA                  AUTOFOCUSSeptember 20           198942
CAMERA, AUTOFOCUS       September 20, 1989              42

PRINT USING Statement
────────────────────────────────────────────────────────────────────────────


Action

Prints strings or numbers using a specified format.


Syntax


    PRINT USING  formatstring$;  expressionlist {;|,}

Remarks


The  PRINT  USING statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    formatstring$                          A string literal (or variable)
                                        that contains literal characters
                                        to print (such as labels) and
                                        special formatting characters. The
                                        latter determine the field and
                                        format of printed strings or
                                        numbers.

    expressionlist                         The values displayed on the screen.
                                        Commas, semicolons, spaces, or
                                        tabs can be used in
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        tabs can be used in
                                        expressionlist to separate items.
                                        In contrast with the  PRINT
                                        statement, delimiters in the
                                        expressionlist argument used with
                                        PRINT  USING have no effect on
                                        item placement.

{;|,}                                   Determines the screen location of
                                        the text cursor for the next
                                        screen input or output statement:
                                        a semicolon means the text cursor
                                        is placed immediately after the
                                        last character displayed; a comma
                                        means the text cursor is placed at
                                        the start of the next print zone.



When  PRINT USING is used to print strings, you can use one of three
formatting characters to format the string field, as described in the
following list:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Character                               Rules
────────────────────────────────────────────────────────────────────────────
!                                       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.
                                        For example, 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
Character                               Rules
────────────────────────────────────────────────────────────────────────────
                                        field and padded with spaces on
                                        the right.

&                                       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                               Rules
────────────────────────────────────────────────────────────────────────────
#                                       Represents each digit position.
                                        Digit positions are always filled.
Character                               Rules
────────────────────────────────────────────────────────────────────────────
                                        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 can 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.

+                                       Prints the sign of the number (+
                                        or -) before the number (if it
                                        appears at the beginning of the
Character                               Rules
────────────────────────────────────────────────────────────────────────────
                                        appears at the beginning of the
                                        format string) or after (if it
                                        appears at the end).

-                                       Prints a negative number with a
                                        trailing minus sign if it appears
                                        at the end of the format string.

**                                      Fills leading spaces in the
                                        numeric field with asterisks. Also
                                        specifies positions for two more
                                        digits.

$$                                      Prints a dollar sign to the
                                        immediate left of the formatted
                                        number. Specifies two more digit
                                        positions, one of which is the
                                        dollar sign.

Character                               Rules
────────────────────────────────────────────────────────────────────────────

**$                                     Combines effects of
                                        double-asterisk and
                                        double-dollar-sign symbols.
                                        Leading spaces are filled with
                                        asterisks and a dollar sign is
                                        printed before the number.
                                        Specifies 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 makes a comma print to
                                        the left of every third digit left
                                        of the decimal point. If the comma
Character                               Rules
────────────────────────────────────────────────────────────────────────────
                                        of the decimal point. If the comma
                                        appears at the end of the format
                                        string, it is printed as part of
                                        the string. Specifies another
                                        digit position. Has no effect if
                                        used with exponential (^^^^ or
                                        ^^^^^) format.

^^^^                                    Specifies exponential format. Five
                                        carets (^^^^^) allows D+ xxx to be
                                        printed for larger numbers. Any
                                        decimal point position can 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
Character                               Rules
────────────────────────────────────────────────────────────────────────────
                                        point to print a space or a minus
                                        sign.

    _                                      An underscore in the format string
                                        prints the next character as a
                                        literal character. A literal
                                        underscore is printed as the
                                        result of two underscores ( _ _ )
                                        in the format string.





If the number to be printed is larger than the 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, BASIC
generates the error message Illegal function call.



Examples

The following examples show the use of string- and numeric-formatting
characters with  PRINT  USING.

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



Output





LO
LOOKOUT
LOOK OUT  !!
LOUT


This example shows 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 "_!##.##_!"; 12.34

PRINT USING "##.##"; 111.22

PRINT USING ".##"; .999



Output





0.78
987.65
10.20    5.30   66.79    0.23
-68.95    +2.40   +55.60    -0.90
68.95-   22.45     7.01-
*12.4   *-0.9   765.1
    $456.78
***$2.34
1,234.50
    2.35E+02
.8889E+06-
+.12E+003
!12.34!
%111.22
%1.00

PSET Statement
────────────────────────────────────────────────────────────────────────────


Action

Draws a specified point on the screen.


Syntax


    PSET  STEP( x%,  y%) ,  color&

Remarks


The following list describes the parts of the  PSET statement:
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   Indicates that  x% and  y% are
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   Indicates that  x% and  y% are
                                        relative, not absolute.
                                        Coordinates are treated as
                                        distances from the most recent
                                        graphics cursor location, not
                                        distances from the (0,0) screen
                                        coordinate.

                                        For example, if the most recent
                                        graphics cursor location were
                                        (10,10), PSET STEP (10,5) would
                                        refer to the point at (20,15).

    x%                                     The x coordinate of the pixel that
                                        is to be set.

    y%                                     The y coordinate of the pixel that
                                        is to be set.

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

    color&                                 The color attribute for the
                                        specified pixel.



The valid range of screen coordinate values and color values depends on the
screen mode established by the most recently executed  SCREEN statement. If
a coordinate is outside the current viewport, no action is taken, nor is an
error message generated.

If you use  PSET without specifying  color&, the foreground color is
selected. In contrast, if you use  PRESET without specifying  color&, the
background color is selected. Otherwise, the two statements work exactly the
same.


See Also

    PRESET


Example

The following example draws a line from (0,0) to (100,100), then erases the
line by writing over it with the background color:

SCREEN 2

FOR I = 0 TO 100

    PSET (I, I)

NEXT I

LOCATE 16, 2: INPUT "Press the Return 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 "                                       "

PUT Statement (File I/O)
────────────────────────────────────────────────────────────────────────────


Action

Writes from a variable or a random-access buffer to a file.


Syntax


    PUT #  filenumber%,  recordnumber%,  variable

Remarks


Do not use  PUT on ISAM files.

The  PUT statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    recordnumber%                          For random-access files, the
                                        number of the record to be written.
                                        For binary-mode files, the byte
                                        position where writing is done.
                                        The first record or byte position
                                        in a file is 1. If you omit
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        in a file is 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 231 -1 or
                                        2,147,483,647.

    variable                               A variable that contains 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 specify a variable, you do
                                        not need to use  MKI$,  MKL$,
                                        MKS$,  MKD$, or  MKC$ to convert
                                        numeric fields before writing. You
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        numeric fields before writing. You
                                        cannot 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. A record
                                        cannot be longer than 32,767 bytes.

                                        For binary-mode files, you can use
                                        any variable.

                                        When you use a variable-length
                                        string variable, the statement
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        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 for more
                                        information about using variables
                                        rather than  FIELD statements for
                                        random-access files.





You can omit  recordnumber%,  variable, or both. If you omit  recordnumber%
but include a variable, you must still include the commas:


PUT #4,,FileBuffer

If you omit both arguments, do not include the commas:


PUT #4

    GET and  PUT statements allow fixed-length input and output for BASIC
communication files. Be careful using  GET and  PUT for communication
because  PUT writes a fixed number of characters and may wait indefinitely
if there is a communication failure.




Note


When using a file buffer defined by a  FIELD statement,  LSET,  RSET,  PRINT
# ,  PRINT #  USING, and  WRITE # can 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. If you
attempt to read or write past the end of the buffer, BASIC generates the
error message FIELD overflow.



See Also


    CVI,  CVL,  CVS,  CVD,  CVC;  GET (File I/O);  LSET;  MKI$,  MKL$,  MKS$,
MKD$,  MKC$;  OPEN (File I/O)



Example


The following example reads names and test scores from the console and
stores them in a random-access file:

' Define record fields.

TYPE TestRecord

    NameField  AS STRING * 20

    ScoreField AS SINGLE

END TYPE

DIM FileBuffer AS TestRecord

DIM I AS LONG

' Open the test data file.

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

KILL "TESTDAT.DAT"' Remove file from disk.

PUT Statement (Graphics)
────────────────────────────────────────────────────────────────────────────


Action

Places a graphic image obtained by a  GET statement onto the screen.


Syntax


    PUT  STEP ( x!,  y!),  arrayname# ( indexes%) ,  actionverb

Remarks


The list below describes the parts of the  PUT statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    STEP                                   Keyword indicating that the given
                                        x and y coordinates are relative
                                        to the most recently plotted point.
                                        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
                                        cursor location were (10,10) then
                                        the following statement would put
                                        the object stored in Ball at
                                        (20,15):

                                        PUT STEP (10,5),Ball
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        PUT STEP (10,5),Ball

( x!, y!)                               Coordinates that specify the
                                        top-left corner of the rectangle
                                        enclosing the image to be placed
                                        in the current output window. The
                                        entire rectangle to be put on the
                                        screen must be within the bounds
                                        of the current viewport.

                                        Note that if a  WINDOW statement
                                        without the argument  SCREEN
                                        appears in a program before  PUT,
                                        the coordinates refer to the
                                        lower-left corner of the rectangle.

    arrayname#                             The name of the array that holds
                                        the image. See the  GET statement
                                        for information about the number
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        for information about the number
                                        of elements that are required in
                                        the array, which can be
                                        multidimensional.

    indexes%                               Specifies that the image is
                                        retrieved starting from the
                                        designated array element, rather
                                        than at the first array element.

    actionverb                             Determines interaction between
                                        stored image and the one already
                                        on the screen. This allows display
                                        of the image with special effects.



The different values for  actionverb are described in the following list.
The default  actionverb value is  XOR.

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Verb                                    Description
────────────────────────────────────────────────────────────────────────────
    XOR                                    Causes the points on the screen to
                                        be inverted where a point exists
                                        in the array image. When an image
                                        is placed on the screen against a
                                        complex background twice, the
                                        background is restored. This
                                        behavior is exactly like that of
                                        the cursor. You can move an object
                                        around the screen without erasing
                                        the background, thus creating
                                        animation effects.

    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. The  PSET argument
Verb                                    Description
────────────────────────────────────────────────────────────────────────────
                                        with  GET. The  PSET argument
                                        draws the image as stored, wiping
                                        out any existing image.

    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
                                        merged image is the result of a
                                        logical-  AND operation on 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.
                                        Points that do not have the same
                                        color in both the existing image
Verb                                    Description
────────────────────────────────────────────────────────────────────────────
                                        color in both the existing image
                                        and the stored image do not.

    OR                                     Used to superimpose the image onto
                                        an existing image. The resulting
                                        image is the product of a logical-
                                        OR operation on the stored image
                                        and the screen image. The stored
                                        image does not erase the previous
                                        screen contents.







See Also

    GET (Graphics)


Example

The following 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)' Set the dimensions for an 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

RANDOMIZE Statement
────────────────────────────────────────────────────────────────────────────


Action

Initializes (reseeds) the random-number generator.


Syntax


    RANDOMIZE  expression%

Remarks


If you omit  expression%, BASIC pauses and asks for a value by printing the
following messages before executing the  RANDOMIZE statement:

Random Number Seed (-32768 to 32767)?

When you use the argument  expression%, BASIC uses this value to initialize
the random-number generator.



If the random-number generator is not reseeded, the  RND function returns
the same sequence of random numbers each time the program is run. To change
the sequence of random numbers every time the program is run, place a
RANDOMIZE statement at the beginning of the program and change the argument
with each run.


A convenient way to initialize the random-number generator is to use the
TIMER function. Using  TIMER ensures a new series of random numbers each
time you use the program. See the example below.



See Also


    RND,  TIMER



Example


The following example uses  RANDOMIZE to seed and reseed the random number
generator. It uses the  RND function 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



Output





You rolled a 3 and a 5 for a total of 8
Roll again (Y/N)? n

READ Statement
────────────────────────────────────────────────────────────────────────────


Action

Reads values from a  DATA statement and assigns the values to variables.


Syntax


    READ  variablelist

Remarks


The argument  variablelist is a series of BASIC variables that receive the
data from a  DATA statement. The variables are separated by commas and can
be string or numeric. Only individual elements of a record variable can
appear in a  READ statement.

The following table describes what happens when you try to read data of one
data type into a variable with a different data type:

╓┌────────────────────────┌────────────────────────┌─────────────────────────╖
If you try to read       Into this:               The result is:
If you try to read       Into this:               The result is:
this:
────────────────────────────────────────────────────────────────────────────
String value             Numeric variable         A run-time error.

Numeric value            String variable          The value is stored as a
                                                    string of numerals (no
                                                    error is produced).

Any numeric value        Integer variables        The value is rounded
                                                    before it is assigned to
                                                    the variable.

Numeric value            A variable not large     A run-time error.
                            enough to handle the
                            numeric variable.

String value             Fixed-length string      Truncated if the string
                            variables                is too long;
                                                    left-justified and
                                                    padded with blanks if
If you try to read       Into this:               The result is:
this:
                                                    padded with blanks if
                                                    the string is shorter
                                                    than the variable.





Each variable in a  READ statement receives its value from some  DATA
statement. Which value the variable receives depends on how many values have
previously been read. The values of all  DATA statements in a module can be
considered as a single list of values. Each value in this list is assigned
in turn to the variables specified in  READ statements. It doesn't matter
how many values are specified in a given  DATA statement or how many
variables are specified in a  READ statement. If you attempt to read more
values than are specified in all of the statements combined, BASIC generates
the error message Out of data.

Use the  RESTORE statement to reread  DATA statements.


See Also

    DATA,  RESTORE


Example


The following example shows how you can use a  READ statement to assign
values to 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



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

REDIM Statement
────────────────────────────────────────────────────────────────────────────


Action

Changes the space allocated to an array that has been declared dynamic.


Syntax


    REDIM  SHARED  variable( subscripts)  AS  type ,  variable( subscripts)  AS
    type...

Remarks


The  REDIM statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Arguments                               Description
────────────────────────────────────────────────────────────────────────────
    SHARED                                 The optional  SHARED attribute
                                        allows a module to share variables
                                        with all the procedures in the
                                        module; this differs from the
                                        SHARED statement, which affects
                                        only the variables within a single
                                        module.  SHARED can be used in
Arguments                               Description
────────────────────────────────────────────────────────────────────────────
                                        module.  SHARED can be used in
                                        REDIM statements only 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 the type of the variable.
                                        The type can be  INTEGER,  LONG,
                                        SINGLE,  DOUBLE,  STRING (for
                                        variable-length strings),  STRING
                                        *  length (for fixed-length
                                        strings),  CURRENCY, or a
                                        user-defined type.

Arguments                               Description
────────────────────────────────────────────────────────────────────────────





Subscripts in  REDIM 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 that specify the lowest and highest value for the subscript. For
more information about using the  TO keyword, see the  DIM statement. For
more information about static and dynamic arrays, see Appendix B, "Data
Types, Constants, Variables, and Arrays" in the  Programmer's Guide.

When a  REDIM statement is compiled, all arrays declared in the statement
are treated as dynamic. At run time, when a  REDIM statement is executed,
the array is deallocated (if it is already allocated) and then reallocated
with the new dimensions. Old array-element values are lost because all
numeric elements are reset to 0, and all string elements are reset to null
strings.

Although you can change the  size of an array's dimensions with the  REDIM
statement, you can 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 if you use them, BASIC
generates the error message Wrong number of dimensions:


' $DYNAMIC

DIM A(50,50)

ERASE A

REDIM A(5,5,5) ' Changed number of dimensions from two to three.


Note



BASIC now supports the  CURRENCY data type (type suffix  @). This is used in
the  AS  type clause of  REDIM. BASIC now supports static arrays in
user-defined types.



See Also


    DIM,  ERASE



Example


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



Output





Keyword 99 is ERASE
Count is 2

REM Statement
────────────────────────────────────────────────────────────────────────────


Action

Allows explanatory remarks to be inserted in a program.


Syntax 1

    REM  remark

Syntax 2

'  remark



Remarks

    REM statements are not compiled, but they appear exactly as entered when
the program is listed. You can 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 also are used to introduce metacommands. For more
information, see Chapter 2, "SUB and FUNCTION Procedures" in the
Programmer's Guide.


Note

Do not use the single quotation form of the  REM statement in a  DATA
statement because it will be considered valid data.


Examples

The following example shows two equivalent remark statements. Note that you
must precede a REM statement at the end of a line with a colon.

This is not a complete program.

DIM Array(23)
FOR I = 1 TO 23 : Array(I) = 1 : NEXT I : REM Initialize the array.
FOR I = 1 TO 23 : Array(I) = 1 : NEXT I   ' Initialize the array.

RESET Statement
────────────────────────────────────────────────────────────────────────────


Action

Closes all disk files.


Syntax


    RESET

Remarks


The  RESET statement closes all open disk files and writes data still in the
file buffers to disk.


See Also

    CLOSE,  END,  SYSTEM


Example

The following example opens several files for sequential output, then
performs a  RESET. The program attempts to write to the previously opened
files. The error that occurs is trapped and a message is printed indicating
that all files have been closed using the  RESET statement.

DEFINT A-Z

ON ERROR GOTO ErrHandler    ' Set up the error-handling routine.



CLS

FOR I = 1 TO 3

    OPEN "Test" + RIGHT$(STR$(I), 1) + ".dat" FOR OUTPUT AS FREEFILE

    PRINT "File #"; I; "has been opened for output."

NEXT I

PRINT : PRINT "Press any key to reset all open files."

PRINT

Z$ = INPUT$(1)

RESET

FOR I = 1 TO 3

    PRINT "Trying to write to file #"; I

    PRINT #I, "Test data"

NEXT I

END



ErrHandler:

' Error 52 is "Bad file name or number"

IF ERR = 52 THEN PRINT "  File #"; I; "not open. RESET closed it."

RESUME NEXT

RESTORE Statement
────────────────────────────────────────────────────────────────────────────


Action

Allows  DATA statements to be reread from a specified line.


Syntax


    RESTORE { linelabel |  linenumber}

Remarks


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  linelabel or  linenumber is specified, the next  READ statement gets the
first item in the specified  DATA statement. If a line is specified, the
line label or line number must be in the module-level code. (Note that in
the QBX environment,  DATA statements are automatically moved to the
module-level code.)


See Also

    DATA,  READ


Example

See the  SEEK (file I/O) statement programming example, which uses the
RESTORE statement.


RESUME Statement
────────────────────────────────────────────────────────────────────────────


Action

Resumes program execution after an error-handling routine is finished.


Syntax


    RESUME { 0 |  NEXT |   line}

Remarks


The different forms of the  RESUME statement redirect program flow as
described in the following list:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    RESUME 0                               Program execution resumes with the
                                        statement that caused the error,
                                        or at the most recent call out of
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        or at the most recent call out of
                                        the error-handling procedure or
                                        module.

    RESUME  NEXT                           Execution resumes with the
                                        statement immediately following
                                        the one that caused the error, or
                                        with the statement immediately
                                        following the most recent call out
                                        of the error-handling procedure or
                                        module.

    line                                   Execution resumes at  line, a
                                        label or a line number. The
                                        argument  line must be in the same
                                        procedure (for local
                                        error-handlers) or within the same
                                        module (for module-level
                                        error-handlers).
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        error-handlers).





The location where execution resumes is based on the location of the error
handler in which the error is trapped, not necessarily on the location where
the error occurred.

The following table summarizes the resumption rules for the  RESUME  0
statement:

╓┌──────────────────────┌─────────────────────────┌──────────────────────────╖
Error handler          Location of error         Where program resumes
────────────────────────────────────────────────────────────────────────────
Local                  Same procedure            Statement that caused
                                                    error

Error handler          Location of error         Where program resumes
────────────────────────────────────────────────────────────────────────────

Module level           Same module               Statement that caused
                                                    error

Local or module level  Another procedure, same   Statement that last
                        or another module         called out of the
                                                    procedure or module that
                                                    contains the error
                                                    handler






Note

If BASIC had to search for the error handler (the error handler that
contains the  RESUME statement is in a procedure or module other than the
one in which the the error occurred), then the last statement executed in
that procedure (or module) is the last call out of that procedure or module.

As a rule, avoid using a  line argument with a  RESUME statement in a
module-level error handler, unless you expect errors to occur only at the
module level.


If you use a  RESUME statement outside an error-handling routine, BASIC
generates the error message RESUME without error.

When an error handling routine is active and the end of the program text is
encountered before executing a  RESUME statement, BASIC generates the error
message No RESUME. This also is true if an  END statement (or an  END  SUB,
END  FUNCTION, or  END  DEF statement for a local error handler) is executed
before a  RESUME.


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
BASIC command line.


See Also

    ON  ERROR


Example

See the  ON ERROR statement programming example, which uses the  RESUME
statement.


RETRIEVE Statement
────────────────────────────────────────────────────────────────────────────


Action

Fetches the current record in an ISAM table and places its data into a
record variable.


Syntax


    RETRIEVE #  filenumber%,  recordvariable

Remarks


    RETRIEVE places the current record's data into  recordvariable. You can
change the data in  recordvariable, then update the current record with the
changes you've made. Use the  UPDATE statement to update the current record.


The  RETRIEVE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the table.

    recordvariable                         The name of the variable that will
                                        hold the current record's data. It
                                        is a variable of the user-defined
                                        type  tabletype that was specified
                                        in the  OPEN statement.





    RETRIEVE has no effect on the current position.

If the values passed to  recordvariable do not match the record strucure in
the user-defined type, BASIC generates the error message Type Mismatch.The
record structure includes the names and types of columns or fields.


See Also

    INSERT,  UPDATE


Example

See the programming example for the  SEEKGT,  SEEKGE, and  SEEKEQ
statements, which uses the  RETRIEVE statement.


RETURN Statement
────────────────────────────────────────────────────────────────────────────


Action

Returns control from a routine.


Syntax


    RETURN { linelabel |  linenumber}

Remarks


Without a line label or number,  RETURN continues execution where an event
occurred (for event handling) or at the statement following the  GOSUB
statement (for subroutine calls).  GOSUB and  RETURN without a line number
can be used anywhere in a program, but the  GOSUB and corresponding  RETURN
must be at the same level.

The  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 return control to a statement in the
module-level code only, not in procedure-level code.

A  RETURN statement cannot be used to return control to a calling program
from a  SUB procedure. Use  EXIT SUB for this purpose.


Note

BASIC's  SUB procedures provide a better-structured alternative to  GOSUB
subroutines.


See Also

    EXIT,  GOSUB,  ON  event


Example

See the  GOSUB statement programming example, which uses the  RETURN
statement.


RIGHT$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string consisting of the rightmost  n% characters of a string.


Syntax


    RIGHT$( stringexpression$,  n%)

Remarks


The argument  stringexpression$ can be any string variable, string constant,
or string expression.

The argument  n% is a numeric expression between 0 and 32,767, inclusive,
indicating how many characters are to be returned.

If  n% is 0, the null string (length 0) is returned.

If  n% is greater than or equal to the number of characters in
stringexpression$, the entire string is returned. To find the number of
characters in  stringexpression$, use  LEN( stringexpression$) .


See Also

    LEFT$,  MID$ Function


Example

The following example converts names entered 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

RMDIR Statement
────────────────────────────────────────────────────────────────────────────


Action

Removes an existing directory.


Syntax


    RMDIR  pathname$

Remarks


The  pathname$ is the name of the directory that is to be deleted. The
pathname$ must be a string of fewer than 64 characters. The directory to be
removed must be empty except for the working directory ( '.' ) and the
parent directory ( '..' ); otherwise, BASIC generates one of two error
messages, 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 it can in DOS.


See Also

    CHDIR,  MKDIR


Example

The following example shows how to use  RMDIR to remove a subdirectory.

CHDIR "C:\SALES\TEMP"' Move to \TEMP subdirectory in \SALES.

KILL "*.*" ' Remove all files in \TEMP.

CHDIR ".." ' Move back up to \SALES.

RMDIR "TEMP"' Remove \TEMP subdirectory.

RND Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a single-precision random number between 0 and 1.


Syntax


    RND ( n#)

Remarks


The value of  n# determines how  RND generates the next random number:

╓┌──────────────────────┌────────────────────────────────────────────────────╖
Value                  Number returned
────────────────────────────────────────────────────────────────────────────
    n# < 0                Always returns the same number for any given  n#.
    n# > 0 or  n omitted  Returns the next random number in the sequence.
    n# = 0                Returns the last number generated.




Even if  n# > 0, the same sequence of random numbers is generated each time
the program is run unless you initialize the random-number generator each
time. (See the  RANDOMIZE statement entry for more information about
initializing the random-number generator.)

To produce random  integers in a given range, use this formula:

    INT (( upperbound -  lowerbound + 1) *  RND +  lowerbound)

In this formula,  upperbound is the highest number in the range, and
lowerbound is the lowest number in the range.


Example

See the  RANDOMIZE statement programming example, which uses the  RND
function.


ROLLBACK, ROLLBACK ALL Statements
────────────────────────────────────────────────────────────────────────────


Action

Rescind all or part of the operations of a transaction (a series of ISAM
database operations).


Syntax


    ROLLBACK  savepoint%

    ROLLBACK  ALL

Remarks


The  savepoint% is an integer that identifies a savepoint within a
transaction -- a series of ISAM database operations that is either committed
as a whole or rescinded. Use the savepoint function to designate a
savepoint, which marks the beginning of a subset of operations that can be
rescinded.

If you specify a  savepoint% argument,  ROLLBACK returns the data affected
by a transaction to its state at that savepoint.

If you do not specify a  savepoint% argument,  ROLLBACK returns the data
affected by the transaction to its state at the previous savepoint, or at
the beginning of the transaction if there are no intermediate savepoints.

    ROLLBACK  ALL rescinds all operations in a transaction and returns the data
to its initial state at the beginning of the transaction. Use  BEGINTRANS to
indicate the beginning of a transaction. Use  COMMITTRANS to commit all
operations since the most recent  BEGINTRANS statement.


See Also

    BEGINTRANS,  COMMITTRANS,  SAVEPOINT


Example

See the  BEGINTRANS statement programming example, which uses the  ROLLBACK
statement.


RSET Statement
────────────────────────────────────────────────────────────────────────────


Action

Moves data from memory to a random-access file buffer (in preparation for a
PUT statement), or right-justifies the value of a string in a string
variable.


Syntax


    RSET  stringvariable$ =  stringexpression$

Remarks


The  RSET statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    stringvariable$                        Usually a random-access file field
                                        defined in a  FIELD statement,
                                        although it can be any string
                                        variable.

    stringexpression$                      The value that is assigned to
                                        stringvariable$ and is
                                        right-justified.





If  stringexpression$ requires fewer bytes than were defined for
stringvariable$ in the  FIELD statement, the  RSET statement right-justifies
the string in the field ( LSET left-justifies the string). Spaces are used
to pad the extra positions. If the string is too long for the field, both
LSET and  RSET truncate characters from the right. Numeric values must be
converted to strings before they are justified with the  RSET or  LSET
statements.

The  RSET statement can be used with string variables unrelated to  FIELD
statements. When used with a fixed-length string variable, the value is
right-justified and left-padded with blanks.

When  RSET is used with a variable-length string, the string is treated as a
fixed field. The length of the field is the length of the value the variable
had before the  RSET statement.


See Also

    FIELD;  LSET;  MKI$,  MKL$,  MKS$,  MKD$,  MKC$;  PUT (File I/O)


Example

See the  LSET statement programming example, which uses the  RSET statement.


RTRIM$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string with trailing (rightmost) spaces removed.


Syntax


    RTRIM$( stringexpression$)

Remarks


The  stringexpression$ can be any string expression. The  RTRIM$ function
works with both fixed- and variable-length string variables.


See Also

    LTRIM$


Example

The following 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*

RUN Statement
────────────────────────────────────────────────────────────────────────────


Action

Restarts the program currently in memory, or executes a specified program.


Syntax


    RUN { linenumber |  filespec$}

Remarks


The  RUN statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    linenumber                             The numeric label of the line
                                        where execution begins. If no
                                        argument is given, execution
                                        begins at the first executable
                                        line of code.

    filespec$                              A string expression that names the
                                        program file to load and run. The
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        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.

Program lines can have line numbers or alphanumeric labels, such as
OpenWindow:. If an alphanumeric label is the target of a  RUN statement, the
compiler generates the error message String expression required.

You do not need to specify the filename extension in  filespec$. The .BAS
extension is assumed in the QBX environment, whereas the .EXE extension is
assumed 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 filename given must end with a period. For example,
the following statement would execute CATCHALL.EXE from a BC-compiled
program, and CATCHALL.BAS from within the QBX environment:

RUN "CATCHALL"

Programs running within the QBX environment must call only BASIC program
files. The file is loaded and run as if it were a BASIC program; if it is
not in the BASIC program format, execution halts. The error message that
results varies, depending on the file's contents. Likewise, programs
compiled with the compiler must not invoke BASIC source files, as these run
only in the QBX environment.

An executable file need not have been written in BASIC. Any executable file
can be run.

When running a program in the QBX environment, if an executable file
matching the filename in the command line cannot be found, BASIC generates
the error message File not found and control returns to BASIC. When running
a program compiled by BC, BASIC generates the error message File not found
in module module-name at address segment:offset and control returns to the
operating system.



When the invoked program completes execution, control does not return to the
invoking program. If the invoking program ran outside QBX, control returns
to the operating system. If the invoking program ran under QBX, control
returns to BASIC.


    RUN closes all files and clears program memory before loading the
designated program. The 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.



See Also


    CHAIN



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



Output





9     7     5     4
0     7     5     4
0     0     5     4
0     0     0     4
0     0     0     0

SADD Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the address of a specified string variable.


Syntax

    SADD( stringvariable$)

Remarks


The  SADD function returns the address of a string as an offset (near
pointer) from the current data segment. The offset is a two-byte integer.
SADD is most often used in mixed-language programming to obtain far
addresses before passing far strings to procedures written in other
languages.

The argument  stringvariable$ is the string whose offset you want to
determine. It can be a simple string variable or a single element of a
string array. You cannot use fixed-length string arguments.

    SADD can be used with both near and far strings. To obtain the segment
address of a far string, use the  SSEG function. In previous versions of
BASIC,  SADD was used only for near strings.


Note

Do not add characters to the beginning or end of a string passed using  SADD
and  LEN. Adding characters can cause BASIC to generate a run-time error.
Use this function with caution, because strings can move in the BASIC string
space (storage area) at any time.


See Also

    BLOAD;  BSAVE;  DEF SEG;  FRE;  PEEK;  POKE;  SSEG;  SSEGADD;  VARPTR,
VARSEG;  VARPTR$


Example

The following example illustrates the use of the  SADD and  SSEG functions.
SADD returns the offset address of a variable-length string.  SSEG returns
the segment of a variable-length string. Typically these functions are used
in mixed-language programs or with  PEEK,  POKE,  BLOAD, or  BSAVE.

In this example, a string is created and then its offset and segment are
calculated with  SADD and  SSEG. The information is then passed to a BASIC
SUB procedure that mimics the performance of a non-BASIC print routine.

DEFINT A-Z

' Create the string.

Text$ = ".... a few well-chosen words"



' Calculate the offset, segment, and length of the string.

Offset = SADD(Text$)

Segment = SSEG(Text$)

Length = LEN(Text$)



' Pass these arguments to the print routine.


CALL printit(Segment, Offset, Length)



SUB printit (Segment, Offset, Length)

    CLS

    ' Set the segment for the PEEK function.

    DEF SEG = Segment

    FOR i = 0 TO Length - 1

        ' Get each character from memory, convert to ASCII, and display.

        PRINT CHR$(PEEK(i + Offset));

    NEXT i

END SUB


SAVEPOINT Function
────────────────────────────────────────────────────────────────────────────


Action

Marks the beginning of a subset of ISAM database operations in a
transaction.


Syntax



    SAVEPOINT

Remarks


The  SAVEPOINT function marks the beginning of a subset of operations within
a transaction that can be rescinded using a  ROLLBACK statement. The
function returns an integer that refers to the savepoint.

Transactions are a way to group a series of ISAM operations so that you can
commit them as a whole, rescind them all, or rescind operations since a
designated savepoint. Use  BEGINTRANS to indicate the beginning of a
transaction and  COMMITTRANS to commit all operations since the beginning of
a transaction.

Use  ROLLBACK with the argument  savepoint% to return the data affected by a
transaction to its state at that savepoint. Use  ROLLBACK with no argument
to return the data affected by the transaction to its state at the most
recent savepoint, or at the beginning of the transaction if there are no
intermediate savepoints.

    ROLLBACK ALL rescinds all ISAM operations in a transaction and returns the
data to its initial state at the beginning of the transaction.

If there is no transaction pending when you use  SAVEPOINT, BASIC generates
the error message Illegal function call.


See Also

    BEGINTRANS,  COMMITTRANS,  ROLLBACK


Example

See the  BEGINTRANS statement programming example, which uses the  SAVEPOINT
function.


SCREEN Function
────────────────────────────────────────────────────────────────────────────


Action

Reads a specified character's ASCII value or its color from a specified
screen location.


Syntax



    SCREEN( line%,  column% ,  colorflag%)

Remarks


The  SCREEN function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    line%                                  The line number of the character
                                        location on the screen. The
                                        argument  line% is an integer
                                        expression whose valid range
                                        depends on the number of lines on
                                        screen.

    column%                                The column number of the character
                                        location on the screen. The
                                        argument  column% is an integer
                                        expression with a value between 1
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        expression with a value between 1
                                        and 80, inclusive.

    colorflag%                             A numeric expression that
                                        determines which information is
                                        returned. When  colorflag% is
                                        nonzero,  SCREEN returns the
                                        number of the color attribute at
                                        the screen location. If
                                        colorflag% is 0 or is absent, the
                                        SCREEN function returns the ASCII
                                        character code.






Note

In graphics screen modes, if the pattern on the screen at the given
character location does not exactly match any pattern in the current ASCII
character set, the  SCREEN function will return the ASCII code for a space.
If  colorflag% is nonzero, the  SCREEN function will return 0.


See Also

Appendix A, "Keyboard Scan Codes and ASCII Character Codes,"  COLOR,
PALETTE,  SCREEN Statement


Examples

If the character at (10,10) is A, then the following statement would return
65, the ASCII code for A, to the variable X:

X = SCREEN(10,10)

The following statement returns the color attribute of the character in the
upper-left corner of the screen:

X = SCREEN(1, 1, 1)


SCREEN Statement
────────────────────────────────────────────────────────────────────────────


Action

Sets the specifications for the graphics adapter and monitor.


Syntax



    SCREEN  mode% ,  colorswitch% ,  activepage% ,  visiblepage%

Remarks


The  SCREEN statement sets a screen mode for a particular combination of
display and adapter. Later sections in this entry describe the available
modes for specific adapters. The  SCREEN statement uses the following
arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    mode%                                  An integer constant or expression
                                        that selects a screen mode for a
                                        particular combination of display
                                        and adapter (see "Summary of
                                        Screen Modes" later in this entry
                                        for information on what the
                                        acronyms represent). There also
                                        are more details on  mode% later
                                        in this entry.

    colorswitch%                           Integer expression that switches
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    colorswitch%                           Integer expression that switches
                                        composite monitor display between
                                        color and monocolor (modes 0 and 1
                                        only). See below for more details
                                        on  colorswitch%.

    activepage%                            Integer expression that identifies
                                        the screen page that text or
                                        graphics output is written to.

    visiblepage%                           Integer expression that identifies
                                        the screen page that is displayed.



The  colorswitch% is effective only for screen modes 0 and 1 and for
composite monitors. In screen mode 0, use a  colorswitch% value of 0 to
disable color, and a non-zero value to enable color. In screen mode 1, use a
non-zero value to disable color and 0 to enable color.

See "Adapters, Screen Modes, and Displays" later in this entry for the valid
ranges for  activepage% and  visiblepage% for each graphics adapter. The
"Attributes and Colors" section lists the default color attributes for
different screen modes. If  mode% is an expression, rather than a constant,
and if you know your program will not use certain screen modes, you can
achieve a smaller .EXE file by linking one or more stub files:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
If not using screen modes:            Link to file:
────────────────────────────────────────────────────────────────────────────
1 or 2                                NOCGA.OBJ
3                                     NOHERC.OBJ
4                                     NOOGA.OBJ
7, 8, 9, or 10                        NOEGA.OBJ
11, 12, or 13                         NOVGA.OBJ



If you do not need graphics in your custom run-time module (because the
programs use screen mode 0 only), you can save 15K by creating the run-time
module with NOGRAPH.OBJ.


Summary of Screen Modes
The following lists summarize each of the screen modes. The color adapters
referred to are the IBM Monochrome Display and Printer Adapter (MDPA), the
IBM Color Graphics Adapter (CGA), the IBM Enhanced Graphics Adapter (EGA),
the IBM Video Graphics Array (VGA), the IBM Multicolor Graphics Array
(MCGA), and the Olivetti Color Adapter. 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. See
the  WIDTH statement for more information about changing the number of rows
and columns on the display.

SCREEN 0

    ■         MDPA, CGA, EGA, MCGA, Hercules, Olivetti, or VGA Adapter Boards

    ■         Text mode only

    ■         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 two color attributes

    ■         16 colors assigned to any of 16 color attributes with CGA or EGA

    ■         64 colors assigned to any of 16 color attributes with EGA or VGA

SCREEN 1

    ■         CGA, EGA, VGA, or MCGA Adapter Boards

    ■         320 x 200 graphics

    ■         40 x 25 text format, 8 x 8 character box

    ■         16 background colors and one of two sets of three foreground
            colors assigned using  COLOR statement with CGA

    ■         16 colors assigned to four color attributes with EGA, VGA or
            MCGA

SCREEN 2

    ■         CGA, EGA, VGA, or MCGA Adapter Boards

    ■         640 x 200 graphics

    ■         80 x 25 text format with character box size of 8 x 8

    ■         2 colors (black and white) with CGA

    ■         16 colors assigned to two color attributes with EGA or VGA


SCREEN 3

    ■         Hercules, Olivetti, or AT&T Adapter Boards

    ■         Hercules adapter required, monochrome monitor only

    ■         720 x 348 graphics

    ■         80 x 25 text format, 9 x 14 character box

    ■         Two screen pages (one only if a second display adapter is
            installed)

    ■          PALETTE statement not supported

SCREEN 4

    ■         Hercules, Olivetti, or AT&T Adapter Boards

    ■         640 x 400 graphics

    ■         80 x 25 text format, 8 x 16 character box

    ■         One of 16 colors assigned as the foreground color (selected by
            the  COLOR statement); background fixed at black

    ■         Supports Olivetti Personal Computers models M24, M240, M28,
            M280, M380, M380/C, and M380/T, and AT&T Personal Computers 6300
            series

Warning

Olivetti personal computers running 3XBOX under OS/2 should avoid screen
mode 4.


SCREEN 7

    ■         EGA or VGA Adapters

    ■         320 x 200 graphics

    ■         40 x 25 text format, character box size 8 x 8

    ■         32K page size, pages 0-1 (64K adapter memory), 0-3 (128K), or
            0-7 (256K)

    ■         Assignment of 16 colors to any of 16 color attributes

SCREEN 8

    ■         EGA or VGA Adapters

    ■         640 x 200 graphics

    ■         80 x 25 text format, 8 x 8 character box

    ■         64K page size, pages 0 (64K adapter memory), 0-1 (128K), or 0-3
            (256K)

    ■         Assignment of 16 colors to any of 16 color attributes

SCREEN 9

    ■         EGA or VGA Adapters

    ■         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 0 (64K adapter memory); 128K page size,
            pages 0 (128K adapter memory) or 0 - 1 (256K)

    ■         16 colors assigned to four color attributes (64K adapter
            memory), or 64 colors assigned to 16 color attributes (more than
            64K adapter memory)

SCREEN 10

    ■         EGA or VGA adapters, monochrome monitor only

    ■         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, pages 0 (128K adapter memory) or 0 - 1 (256K)

    ■         Up to nine shades of gray assigned to four color attributes

SCREEN 11

    ■         VGA or MCGA adapters

    ■         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 two color attributes

SCREEN 12

    ■         VGA adapter

    ■         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 color attributes

SCREEN 13

    ■         VGA or MCGA adapters

    ■         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 color attributes

Screen Modes, Adapters, and Displays
This section describes the screen modes available for each adapter. If the
display device also is a factor in choosing a screen mode, it is listed. The
IBM Monochrome Display and Printer Adapter (MDPA) must be used with a
monochrome display. Only SCREEN 0, text mode, can be used with the MDPA.


Table 1.10 describes the screen mode available with the MDPA.

Table 1.11 summarizes the screen modes available with Hercules Adapters.

The IBM Color Graphics Adapter (CGA) and Color Display typically are paired.
This combination permits running text-mode programs, and both
medium-resolution and high-resolution graphics programs.

Table 1.12 summarizes the screen modes available with the CGA.

The IBM Enhanced Graphics Adapter (EGA) can 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
differences:

    ■         Border color can't be set on an Enhanced Color Display when it
            is in 640 x 350 text mode.

    ■         The text quality is better on the Enhanced Color Display (an 8 x
            14 character box for Enhanced Color Display versus an 8 x 8
            character box for Color Display).


Screen mode 9 takes full advantage of the capabilities of the Enhanced Color
Display. 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.


Table 1.13 summarizes the screen modes that can be used with an EGA.

Only the EGA and VGA can be paired with the IBM Monochrome display to run
programs in screen mode 10. This mode can be used to display monochrome
graphics at a very high resolution with the optional effects of blinking and
high intensity.

The following two tables summarize the color attributes, display colors, and
effects for screen mode 10 used with a monochrome display.

Tables 1.14 and 1.15 summarize EGA and VGA adapters used with monochrome
display (SCREEN 10).

The IBM Video Graphics Array (VGA) adapter offers significantly enhanced
text and graphics in all modes. Table 1.16 summarizes the modes available
with the VGA.

The IBM Multicolor Graphics Array (MCGA) combines the modes of the CGA with
the very high resolution and 256K color modes of the VGA to provide enhanced
text and graphics in all modes. Table 1.17 summarizes the modes supported by
the MCGA.

The MCGA uses the same display color values as the VGA. For a description of
how the MCGA calculates display color values, see the  PALETTE statement.


Attributes and Colors
For various screen modes and display hardware configurations, different
color-attribute and display-color settings exist. (See the  PALETTE
statement for a discussion of color attributes and display colors.) The
majority of these color-attribute and display-color configurations are
summarized in Tables 1.18-1.20.

Note

In OS/2 protected mode, BASIC supports only screen modes 0 - 2 and does not
support the  activepage% and  visiblepage% arguments.


See Also

    COLOR,  PALETTE,  SCREEN Function,  WIDTH


Example

The following example sets up a multipage EGA or VGA mode 7 (320x200)
display using the  SCREEN statement. A help screen is displayed for several
seconds then copied (using the  PCOPY statement) to page 2 for later use. A
cube is displayed and rotated on the screen. By pressing Shift+F1, the user
can again see the help screen, after which the cube display is resumed.

DEFINT A-Z

' Define a macro string to draw a cube and paint its sides.

One$ = "BR30 BU25 C1 R54 U45 L54 D45 BE20 P1, 1G20 C2 G20"

Two$ = "R54 E20 L54 BD5 P2, 2 U5 C4 G20 U45 E20 D45 BL5 P4, 4"

Plot$ = One$ + Two$

' Initialize values for active page, visual page, and help page.

APage% = 0 : VPage% = 1 : HPage% = 2

Angle% = 0

' Create a HELP screen on the visual page.

SCREEN 7, 0, VPage%, VPage%

LOCATE 1, 18

PRINT "HELP"

LOCATE 5, 1

PRINT "Press 'Alt+F1' keys to see this HELP"

PRINT "screen while the cube is rotating"

PRINT "around the center of the screen."

PRINT

PRINT "After a brief delay, the cube will"

PRINT "resume at the next point in its rotation."

PRINT

PRINT "Press any other key to exit the program."

' Put a copy of the help screen in page 2.


PCOPY VPage%, HPage%

SLEEP 5

DO

    SCREEN 7, 0, APage%, VPage%

    ' Clear the active page.

    CLS 1

    ' Rotate the cube Angle% degrees.

    DRAW "TA" + STR$(Angle%) + Plot$

    ' Angle% is some multiple of 15 degrees.

    Angle% = (Angle% + 15) MOD 360

' Drawing is complete. Make the cube visible in its     '  new position by
swapping the active and visual pages.


SWAP APage%, VPage%

    ' Check the keyboard input.

    Kbd$ = INKEY$

    SELECT CASE Kbd$

        ' If Shift+F1 is pressed, show the HELP page.

        CASE CHR$(0) + CHR$(104)

            PCOPY HPage%, APage%

            SLEEP 3

        ' Do nothing if no key is pressed.

        CASE ""

        CASE ELSE

            EXIT DO

    END SELECT

LOOP

END


SEEK Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the current file position.


Syntax





    SEEK(  filenumber%)

Remarks


The argument  filenumber% is the number used in the  OPEN statement to open
the file.  SEEK returns a value between 1 and 2,147,483,647, inclusive
(equivalent to 231 -1).

    SEEK returns the number of the next record read or written when used on
random-access 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.

    SEEK returns zero when used on an ISAM table or on BASIC devices (SCRN,
CONS, KYBD, COM n, LPT n, PIPE) that do not support  SEEK.


See Also

    GET (File I/O);  OPEN;  PUT (File I/O);  SEEK Statement;  SEEKGT,  SEEKGE,
SEEKEQ Statements


Example

See the  SEEK statement programming example, which uses the  SEEK function.


SEEK Statement
────────────────────────────────────────────────────────────────────────────


Action

Sets the position in a file for the next read or write.


Syntax



    SEEK #  filenumber%,  position&

Remarks


The  SEEK statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    position&                              A numeric expression that
                                        indicates where the next read or
                                        write occurs. The  position& value
                                        must be between 1 and
                                        2,147,483,647 (equivalent to 231
                                        -1), inclusive.





For files opened in random-access mode,  position& is the number of a record
in the file.

For files opened in binary, input, output, or append mode,  position& is the
byte position relative to the beginning of the file. The first byte in a
file is at position 1; the second byte is at position 2, and so on. After a
SEEK operation, the next file I/O operation starts at the specified byte
position.


Note

Record numbers on a  GET or  PUT override the file positioning done by
SEEK.

Performing a file write after doing a  SEEK operation beyond the end of a
file extends the file. If you attempt a  SEEK operation to a negative or
zero position, BASIC generates the error message Bad record number.

BASIC leaves the file position unchanged when you use  SEEK on an ISAM table
or on BASIC devices (SCRN, CONS, KYBD, COM n, LPT n, PIPE) that do not
support  SEEK.


See Also

    GET (File I/O);  OPEN;  PUT (File I/O);  SEEK Function;  SEEKGT,  SEEKGE,
SEEKEQ Statements



Example

The following example 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):

CONST FALSE = 0, TRUE = NOT FALSE


' Define record fields and a user-type variable.


TYPE TestRecord


    NameField  AS STRING * 20


    ScoreField AS SINGLE


END TYPE


DIM RecordVar AS TestRecord


DIM I AS LONG


' This part of the program creates the random-access file used by the


' second part of the program, which demonstrates the SEEK statement.


OPEN "TESTDAT2.DAT" FOR RANDOM AS #1 LEN = LEN(RecordVar)


RESTORE


READ NameField$, ScoreField


I = 0


DO WHILE NameField$ <> "END"


    I = I + 1


    RecordVar.NameField = NameField$


    RecordVar.ScoreField = ScoreField


    PUT #1, I, RecordVar


    READ NameField$, ScoreField


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


SEEKGT, SEEKGE, SEEKEQ Statements
────────────────────────────────────────────────────────────────────────────



Action

Causes the first matching record in an ISAM table to become the current
record.


Syntax



    SEEKGT #  filenumber% ,  keyvalue,  keyvalue


    SEEKGE #  filenumber% ,  keyvalue,  keyvalue


    SEEKEQ #  filenumber% ,  keyvalue,  keyvalue

Remarks


The  SEEKGT,  SEEKGE, and  SEEKEQ statements cause the first matching record
in the table, according to the current index, to become the current record.
The following table shows which value of the current index column causes the
record to become current for each statement.

╓┌──────────────────┌────────────────────────────────────────────────────────╖
Statement          Current-index column value
────────────────────────────────────────────────────────────────────────────
    SEEKGT            Greater than  keyvalue
    SEEKGE            Greater than, or equal to,  keyvalue
    SEEKEQ            Equal to  keyvalue




The argument  filenumber% is the number used in the  OPEN statement to open
the table. The argument  keyvalue is an expression fewer than 256 characters
long that is evaluated based on the operand condition in the  SEEK operand
keyword. If more than one  keyvalue argument is specified, BASIC assumes the
current index is based on the combination of their values.

If no match is found, the current index position is at the end of the table
and there is no current record.

If the number of  keyvalues is greater than the number of values that makes
up the current index, BASIC generates the error message Syntax Error.

No error is generated if the number of  keyvalues is less than the number of
values that makes up the current index. The seek either fails or is based on
the  keyvalues supplied:

    ■          SEEKEQ with too few  keyvalues always fails.

    ■          SEEKGE with too few  keyvalues is equivalent to a  SEEKGE with
            the same arguments.

    ■          SEEKGT with too few  keyvalues seeks for the first record that
            matches the  keyvalues supplied.


BASIC removes trailing spaces from strings used in a seek.


Note

The  keyvalue expression must be explicitly typed if it is a DOUBLE or
CURRENCY value.


See Also

    MOVEFIRST,  MOVELAST,  MOVENEXT,  MOVEPREVIOUS Statements;  OPEN


Example


The following example uses the  CREATETABLE statement to create a new table
in an ISAM file and uses the  SEEKGE,  RETRIEVE,  UPDATE, and  INSERT
statements to insert records into the file. It uses the  LOF function to
display the number of records in the new table and then deletes the table
with  DELETETABLE.

The program uses a file called BOOKS.MDB, the sample ISAM file that SETUP
copies to your disk.


DEFINT A-Z


TYPE BookRec


    IDNum AS DOUBLE             ' Unique ID number for each book.


    Title AS STRING * 50        ' Book's title.


    Publisher AS STRING * 50    ' Book's publisher.


    Author AS STRING * 36       ' Book's author.


    Price AS CURRENCY           ' Book's price.


END TYPE





CONST Database = "BOOKS.MDB"    ' Name of the disk file.


DIM Library AS BookRec          ' Variable for current record.


DIM MinPrice AS CURRENCY        ' SEEK criteria.





CLS


DO


INPUT "Display books that cost as much or more than "; MinPrice


    IF MinPrice < 0 THEN PRINT "Positive values only, please."


LOOP UNTIL MinPrice > 0





' Open existing table.


LibraryFile = FREEFILE


OPEN Database FOR ISAM BookRec "BooksStock" AS LibraryFile


CREATEINDEX LibraryFile, "Library", 0, "Price"


SETINDEX LibraryFile, "Library"





' Create and open a new table.


NewFile = FREEFILE


OPEN Database FOR ISAM BookRec "PricyBooks" AS NewFile





' Fill new table with records for all books with price >= MinPrice.


SEEKGE LibraryFile, MinPrice


DO


    RETRIEVE LibraryFile, Library


    INSERT NewFile, Library


    MOVENEXT LibraryFile


LOOP UNTIL EOF(LibraryFile)


' First time through loop get price increase;


' second time display new price.


FOR count = 1 TO 2


    CLS


    PRINT SPC(18); LOF(NewFile); "books cost at least ";


    PRINT USING ("$###.##"); MinPrice


    PRINT " ID Number"; SPC(3); "Title"; SPC(20); "Author";


    PRINT SPC(11); "Publisher"; SPC(10); "Price"


    VIEW PRINT 3 TO 20


    MOVEFIRST NewFile


    DO


        RETRIEVE NewFile, Library


        PRINT Library.IDNum; " "; LEFT$(Library.Title, 20);


        IF LEN(RTRIM$(Library.Title)) > 20 THEN


            PRINT "...  ";


        ELSE


            PRINT "     ";


        END IF


        PRINT LEFT$(Library.Author, 15); "  ";


        PRINT LEFT$(Library.Publisher, 16); "  ";


        PRINT USING ("$###.##"); Library.Price


        MOVENEXT NewFile


    LOOP UNTIL EOF(NewFile)


    IF count = 1 THEN


        VIEW PRINT 20 TO 24: LOCATE 20, 1


        DO


            INPUT "Increase cost by how much (0-100%)"; increase


            IF increase < 0 OR increase > 100 THEN PRINT "Illegal value"


        LOOP UNTIL increase >= 0 AND increase <= 100


        ' Update records in PricyBooks.


        MOVEFIRST NewFile


        DO


            RETRIEVE NewFile, Library


            Library.Price = (Library.Price * (100 + increase)) / 100


            ' Overwrite record with increased price.


            UPDATE NewFile, Library


            CHECKPOINT' Force ISAM to flush the buffer to disk.


            MOVENEXT NewFile


        LOOP UNTIL EOF(NewFile)


    END IF


    VIEW PRINT 1 TO 19


NEXT count


' Destroy index and temporary table, close files.


DELETEINDEX LibraryFile, "Library"


CLOSE


DELETETABLE Database, "PricyBooks"


SELECT CASE Statement
────────────────────────────────────────────────────────────────────────────


Action

Executes one of several statement blocks depending on the value of an
expression.


Syntax



    SELECT CASE  testexpression


    CASE  expressionlist1


    statementblock-1


    CASE  expressionlist2


    statementblock-2


    CASE  ELSE


    statementblock-n


    END  SELECT

Remarks

The following list describes the parts of the  SELECT CASE statement:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
    testexpression                       Any numeric or string expression.

    statementblock-1, statementblock-2,  The elements statementblock-1 to
statementblock-n                      statementblock-n consist of any
                                        number of statements on one or more
                                        lines.

    expressionlist1, expressionlist2     These elements can have any of the
                                        three following forms:


                                        expression ,  expression...

                                        expression TO  expression

                                        IS relational-operator expression





The following list describes the parts of  expressionlist :

╓┌───────────────────────────────────────┌───────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
    expression                             Any numeric or string expression.
                                        The type of the expression must be
                                        compatible with the type of
                                        testexpression. (The type of the
                                        expression will be coerced to the
                                        same type as  testexpression. For
                                        example, if  testexpression is an
                                        integer,  expressionlist can
                                        contain a double-precision data
                                        type.)

    relational-operator                    Any of the following operators:

                                        <   Less than
────────────────────────────────────────────────────────────────────────────
                                        <   Less than

                                        <=  Less than or equal to

                                        >   Greater than

                                        >=  Greater than or equal to

                                        < > Not equal

                                        =   Equal






If  testexpression matches the expression list 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  testexpression is -4. The line should be
written as CASE -5 TO -1.

You can use a relational operator only if the  IS keyword appears. If  CASE
ELSE is used, its associated statements are executed only if  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.

You can 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 also can specify ranges and multiple expressions for strings:


CASE "everything", "nuts" TO "soup", TestItem$

    CASE matches strings that are exactly equal to everything, the current
value of TestItem$, or that fall between nuts and soup in alphabetical
order.


Strings are evaluated according to the ASCII values of their characters.
Lowercase letters have larger ASCII values than uppercase letters, so this
statement is true:

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 can be nested. Each  SELECT CASE statement must have
a matching  END SELECT statement.


Examples


In the first example,  SELECT  CASE is used to take different actions based
on the input value:

INPUT "Enter acceptable level of risk (1-10): ", Total


SELECT CASE Total


CASE IS >= 10


PRINT "Maximum risk and potential return."


PRINT "Choose stock investment plan."


CASE 6 TO 9


PRINT "High risk and potential return."


PRINT "Choose corporate bonds."


CASE 2 TO 5


PRINT "Moderate risk and return."


PRINT "Choose mutual fund."


CASE 1


PRINT "No risk, low return."


PRINT "Choose IRA."


CASE ELSE


PRINT "Response out of range."


END SELECT




Output



Enter acceptable level of risk (1-10): 10


Maximum risk and potential return.


Choose stock investment plan.





Enter acceptable level of risk (1-10): 0


Response out of range.




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


CLS


PRINT "Press Escape key to end."


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 48 TO 57


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.


Choice$ = RIGHT$(Choice$, 1)


SELECT CASE Choice$


CASE CHR$(DOWN)


PRINT "DOWN direction key"


CASE CHR$(UP)


PRINT "UP direction 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 direction key"


CASE CHR$(LEFT)


PRINT "LEFT direction key"


CASE ELSE


BEEP


END SELECT


END IF


LOOP


SETINDEX Statement
────────────────────────────────────────────────────────────────────────────


Action

Makes the specified ISAM table index the current index.


Syntax



    SETINDEX #  filenumber% ,  indexname$

Remarks


The  SETINDEX statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the table.

    indexname$                             The name used in the  CREATEINDEX
                                        statement to create the index. If
                                        no  indexname$ argument or set of
                                        double quotation marks ("") is
                                        specified, the null index  becomes
                                        the current index. The NULL index
                                        represents the order in which
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        represents the order in which
                                        records were added to the file.





After  SETINDEX makes an index current, the current record is the first
record according to that index.


See Also

    CREATEINDEX,  DELETEINDEX,  GETINDEX$


Example

See the  CREATEINDEX statement programming example, which uses the  SETINDEX
statement.


SETMEM Function
────────────────────────────────────────────────────────────────────────────


Action

Changes the amount of memory used by the far heap -- the area where far
objects are stored -- and returns information about the far heap.


Syntax



    SETMEM( numeric- expression&)

Remarks


The   SETMEM function increases or decreases the far heap by the number of
bytes indicated by  numeric- expression&. If  numeric-expression& is
negative,  SETMEM decreases the far heap by the indicated number of bytes.
If  numeric-expression& is positive,  SETMEM attempts to increase the far
heap by the number of bytes. 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
so procedures in other languages can dynamically allocate far memory.

The information that the  SETMEM function returns about the far heap depends
on the value of  numeric-expression&, as follows:

╓┌─────────────────────────┌─────────────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
Positive or negative      Total number of bytes in the far heap.
0                         Current size of far heap.





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.

When programming with OS/2 protected mode, the  SETMEM function performs no
other function than to return a dummy value. This value is the previous
SETMEM value adjusted by the  SETMEM argument. The initial value for  SETMEM
is 655,360.


Example


In the following example,  SETMEM is used to free memory for a C routine
that uses the C function malloc to get dynamic memory. The C routine must be
separately compiled and then put in a Quick library or linked 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)





CFunc(1024%)' Call the C routine.





' 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




This routine is compiled using the large memory model, so calls to the C
function malloc use the far space freed by the BASIC program.


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


}


SetUEvent Routine
────────────────────────────────────────────────────────────────────────────


Action

Sets the BASIC entry point that causes a user-defined event.


Syntax



    SetUEvent

Remarks


    SetUEvent is used in user-event trapping.

    SetUEvent signals an event for the  ON  UEVENT event-handling routine.

The  SetUEvent routine is a part of BASIC, and is automatically included in
compiled applications or when running QBX 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 non-BASIC language.

To use the  SetUEvent routine in the QBX environment, use any Quick library.
Outside of the QBX environment, you do not have to link to another library.


See Also

    ON  event,  UEVENT


Example

See the  UEVENT  statements programming example, which uses the  SetUEvent
routine.


SGN Function
────────────────────────────────────────────────────────────────────────────


Action

Indicates the sign of a numeric expression.


Syntax



    SGN( numeric-expression)

Remarks


The  SGN function returns a value depending on the sign of its argument:

    ■   If  numeric-expression > 0, then  SGN( numeric-expression) returns 1.

    ■   If  numeric-expression = 0, then  SGN( numeric-expression) returns 0.

    ■   If  numeric-expression < 0, then  SGN( numeric-expression) returns -1.


Example

The following example 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




Output



a = 3,  b = -4,  c = 1


This equation has two solutions:  1  and  .3333333


SHARED Statement
────────────────────────────────────────────────────────────────────────────


Action

Gives a  SUB or  FUNCTION procedure access to variables declared at the
module level without passing them as parameters.


Syntax



    SHARED  variable( )  AS  type ,  variable( )  AS  type...

Remarks


The argument  variable is the module-level variable the procedure will use.
It is either an array name followed by ( ), or a variable name. The  AS
type clause can be used to indicate the variable's type, which can be
INTEGER,  LONG,  SINGLE,  DOUBLE,  STRING, fixed-length string ( STRING *
length),  CURRENCY, 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 used with  COMMON or  DIM 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 shares variables only 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 shares variables only between the module-level code and a  SUB or
FUNCTION procedure in the same module.

The  SHARED statement can appear only in a  SUB or  FUNCTION procedure. For
more information, see Chapter 2, "SUB and FUNCTION Procedures" in the
Programmer's Guide.


See Also

    COMMON,  DIM,  SUB


Example


The following example calls a  SUB procedure named Convert that converts the
input decimal number to its string representation in the given new base. The
string N$ is shared by the procedure and the main program.

DEFINT A-Z


DO


    INPUT "Decimal number (input number <= 0 to quit): ",Decimal


    IF Decimal <= 0 THEN EXIT DO


    INPUT "New base: ",Newbase


    N$ = ""


    PRINT Decimal "base 10 equals ";


    DO WHILE Decimal > 0


        CALL Convert (Decimal,Newbase)


        Decimal = Decimal\Newbase


    LOOP


    PRINT N$ " base" Newbase


    PRINT


LOOP





SUB Convert (D,Nb) STATIC


SHARED N$


    ' Take the remainder to find the value of the current


    ' digit.


    R = D MOD Nb


    ' If the digit is less than ten, return a digit (0-9).


    ' Otherwise, return a letter (A-Z).


    IF R < 10 THEN Digit$ = CHR$(R+48) ELSE Digit$ = CHR$(R+55)


    N$ = RIGHT$(Digit$,1) + N$


END SUB


SHELL Function
────────────────────────────────────────────────────────────────────────────


Action

Returns an integer value that is the OS/2 process ID for the shelled
process.


Syntax



    SHELL( commandstring$)

Remarks


The argument  commandstring$ is the name of the OS/2 process to be executed,
along with any command-line arguments that the executed process requires.
The command string is required.

The  SHELL function is used only under OS/2 protected mode.

Like the  SHELL statement, the OS/2 protected-mode  SHELL function permits a
BASIC program to execute another process. In addition, the  SHELL function
allows the BASIC program to continue execution without waiting for the child
process to terminate, and returns the process ID of the child process. The
process ID is used by some of the OS/2 API functions (which can be called
from BASIC).


See Also

    SHELL Statement


Example

The following example uses the  SHELL function to execute three OS/2
commands:

ON ERROR GOTO ErrHandler


Ext$ = CHR$(34) + " EXE" + CHR$(34)


' The child process does: DIR | FIND " EXE" | SORT


Child$ = "dir | find " + Ext$ + "| sort"


ProcessID = SHELL(Child$)


PRINT "Process ID is:" ProcessID


END





ErrHandler:


    SELECT CASE ERR


        CASE 73


            PRINT : PRINT "You cannot use the SHELL function in DOS."


        CASE ELSE


    END SELECT


    END


SHELL Statement
────────────────────────────────────────────────────────────────────────────


Action

Suspends execution of the BASIC program, runs a .COM, .EXE, .BAT, or .CMD
program, or a DOS or OS/2 command, and resumes execution of the BASIC
program at the statement following the  SHELL statement.


Syntax



    SHELL  commandstring

Remarks


The argument  commandstring must be a valid string expression that contains
the name of a program to run, and any program arguments.

Any .COM file, .EXE file, .BAT program, .CMD program, DOS command, or OS/2
command that runs under the  SHELL statement is called a "child process."
Child processes are executed by the  SHELL statement, which loads and runs a
copy of COMMAND.COM (for DOS) or CMD.EXE (for OS/2) with the /C option.

The /C 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 and PATH.

The program name in  commandstring can have any extension you wish. If no
extension is supplied, COMMAND.COM (for DOS) or CMD.EXE (for OS/2) looks for
a .COM file, then an .EXE file, and finally, a .BAT file (for DOS) or a .CMD
file (for OS/2). If COMMAND.COM or CMD.EXE is not found, BASIC generates the
error message File not found. BASIC does not generate an error if
COMMAND.COM or CMD.EXE cannot find the file specified in  commandstring, but
the operating system generates an error message.


COMMAND.COM or CMD.EXE treat as program parameters any text separated from
the program name by at least one blank. BASIC remains in memory while the
child process is running. When the child process finishes, BASIC continues.

If you omit the argument  commandstring,  SHELL gives you a new shell
(COMMAND.COM for DOS or CMD.EXE for OS/2). You then can enter
operating-system commands at the prompt. Use the  EXIT command to return to
BASIC.


Note

If you are using OS/2, make sure that the SET COMSPEC configuration command
in your CONFIG.SYS file specifies the path for the CMD.EXE file. If the path
for CMD.EXE is not set, BASIC generates an error message when  SHELL
searches for the CMD.EXE file.


See Also

    SHELL Function


Examples


The following example shows how a single  SHELL statement starts up a new
COMMAND.COM:

' Get a new COMMAND.COM


' Type EXIT at the operating system prompt to return to this program.


SHELL




If the name of a any executable file or command is provided as an argument
to the  SHELL statement, that command will be executed as if it had been
invoked from the operating-system prompt. When the program is finished,
control returns to BASIC. The following use of the  SHELL statement
illustrates how to display a directory listing to check the creation time of
a file:


SHELL "DIR | MORE"


SIGNAL Statements
────────────────────────────────────────────────────────────────────────────


Action

Enable, disable, or suspend event trapping for an OS/2 protected-mode
signal.


Syntax



    SIGNAL( n%)  ON


    SIGNAL( n%)  OFF


    SIGNAL( n%)  STOP

Remarks


The argument  n% identifies an OS/2 protected-mode signal. The following
table lists the numbers of the protected-mode signals:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
Number                Signal
────────────────────────────────────────────────────────────────────────────
1                     Ctrl+C
2                     Pipe connection broken
3                     Program terminated
4                     Ctrl+Break
5                     Process flag A
6                     Process flag B
7                     Process flag C






    SIGNAL( n%)  OFF disables trapping of OS/2 signal  n%. No trapping takes
place until another  SIGNAL( n%)  ON statement is executed. Events occurring
while trapping is off are ignored.

    SIGNAL( n%)  STOP suspends trapping of OS/2 signal  n%. No trapping takes
place until a  SIGNAL( n%)  ON statement is executed. Events occurring while
trapping is suspended are remembered and processed when the next  SIGNAL(
n%)  ON statement is executed. However, remembered events are lost if
SIGNAL( n%)  OFF is executed.

When a signal-event trap occurs (that is, the  GOSUB is performed), an
automatic  SIGNAL STOP is executed so that recursive traps cannot take
place. The  RETURN operation from the trapping routine automatically
performs a  SIGNAL ON statement unless an explicit  SIGNAL OFF was performed
inside the routine. For more information, see Chapter 9, "Event Handling" in
the  Programmer's Guide.


Note

The  SIGNAL statement is available only for OS/2 protected mode.


See Also

    ON  event


Example


The following example uses  ON SIGNAL to trap an event in the OS/2 operating
system:

PRINT "This program traps Ctrl+Break. Press Q to quit."


EVENT ON





' Set up the signal-event trap and enable.


ON SIGNAL(4) GOSUB CtrlBreak


SIGNAL(4) ON





' Wait until the signal event occurs.


DO : LOOP UNTIL UCASE$(INKEY$) = "Q"


PRINT "'Q' pressed - Program terminating normally."


END





CtrlBreak:


    PRINT "A SIGNAL(4) event occurred."


    PRINT "Press 'Q' to quit."


    RETURN


SIN Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the sine of an angle given in radians.


Syntax



    SIN( x)

Remarks


The argument  x can be of any numeric type.

The sine of an angle in a right triangle is the ratio between the length of
the side opposite the angle and the length of the hypotenuse.

    SIN is calculated in single precision if  x# is an integer or
single-precision value. If you use any other numeric data type,  SIN is
calculated in double precision.

To convert values from degrees to radians, multiply the angle (in degrees)
times π/180 (or .0174532925199433). To convert a radian value to degrees,
multiply it by 180/π (or 57.2957795130824). In both cases, π ≈ 3.141593.



See Also

    ATN,  COS,  TAN


Example

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

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


SLEEP Statement
────────────────────────────────────────────────────────────────────────────


Action

Suspends execution of the calling program.


Syntax



    SLEEP  seconds&

Remarks


The optional argument  seconds& determines the number of seconds to suspend
the program. The  SLEEP statement suspends the program until one of the
following events occurs:

    ■         The time period in the argument  seconds& has elapsed.

    ■         A key is pressed.

    ■         An enabled event occurs.

A BASIC event is one you can trap with an  ON  event statement such as  ON
COM or  ON  TIMER. A BASIC event 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.

If  seconds& is 0 or is omitted, the program is suspended until a key is
pressed or an enabled event occurs.

    SLEEP responds only to keystrokes that occur after it executes.  SLEEP
ignores characters in the keyboard buffer that were typed before it
executed.


See Also

    WAIT


Example

The following example 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


SOUND Statement
────────────────────────────────────────────────────────────────────────────


Action

Generates sound through the speaker.


Syntax



    SOUND  frequency,  duration!

Remarks


The  SOUND statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    frequency                              The frequency of the sound in
                                        cycles per second or hertz. It
                                        must be a numeric expression with
                                        a value between 37 and 32,767,
                                        inclusive.

    duration!                              The number of system clock ticks
                                        the sound lasts. The duration
                                        argument accepts any positive
                                        single-precision, floating-point
                                        value between 0 and 65,535,
                                        inclusive. There are 18.2 clock
                                        ticks per second, regardless of
                                        CPU speed.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        CPU speed.



If  duration! is 0, any current  SOUND statement that is running in the
background is turned off. If no  SOUND statement is running, a duration of
zero has no effect.


Note

The  SOUND statement is not available in OS/2 protected mode.


See Also

    PLAY (Music)


Example

The following example produces a rising and descending glissando:
FOR I = 440 TO 1000 STEP 5


    SOUND I, I/1000


NEXT


FOR I = 1000 TO 440 STEP -5


    SOUND I, I/1000


NEXT


SPACE$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string of spaces of length  n.


Syntax



    SPACE$( n)

Remarks


The expression  n specifies the number of spaces you want in the string.  It
is rounded to an integer and must be between 0 and 32,767, inclusive.


See Also

LSET, Print Using,  RSET,  SPC, String $


Example

The following example demonstrates use of the  SPACE$ function:

CLS' Clear the screen.


FOR I=1 TO 5


    X$=SPACE$(I)


    PRINT X$;I


NEXT I




Output



1


    2


    3


    4


        5


SPC Function
────────────────────────────────────────────────────────────────────────────


Action

Skips a specified number of spaces in a  PRINT,  LPRINT, OR  PRINT  #
statement, starting at the current print position.


Syntax



    SPC( n%)

Remarks


    SPC can only be used with  PRINT,  LPRINT, or  PRINT # statements. The
argument  n% is a number between 0 and 32,767, inclusive, that is combined
with the width of the output line to determine the number of blank
characters to print.

A semicolon (;) is assumed to follow the  SPC function. For example, the
following two print statements are equivalent:

PRINT SPC(10) FixLen1$; SPC(10) FixLen2$; SPC(10) FixLen3$


PRINT SPC(10); FixLen1$; SPC(10); FixLen2$; SPC(10); FixLen3$




Note that the  SPC function does more than move the text cursor to a new
print position. For screen output it also overwrites any existing characters
on a display screen with blanks. The  n% blank characters are printed
starting at the current print position.


The leftmost print position on an output line is always 1; to have any
effect, the value of  n% must be greater than or equal to 1.

The rightmost print position is the current line width of the output device
(which can be set with the  WIDTH statement).

The behavior of an  SPC function depends on the relationship between three
values:  n%, the output-line print position when the  SPC function is
executed, and the current output-line width:

    ■         If  n% is greater than the output-line width,  SPC calculates
            n%  MOD width and generates the number of blanks indicated by
            that calculation, starting at the current print position.

    ■         If the difference between the current print position and the
            output-line width is less than  n% (or  n%  MOD width), the  SPC
            function skips to the beginning of the next line and generates a
            number of blanks equal to  n% - (width - current print
            position).

See Also

    SPACE$,  TAB


Example


The following example demonstrates the use of the  SPC statement to insert a
number of spaces within a printed line using either the  PRINT statement or
the  LPRINT statement:

CLS   ' Clear the screen.


PRINT "The following line is printed using standard screen print"


PRINT "zones."


PRINT : PRINT "Column 1","Column 2","Column 3","Column 4","Column 5"


PRINT : PRINT


PRINT "The next line is printed using the SPC(n%) statement to achieve"


PRINT "the same results."


PRINT


PRINT "Column 1"; SPC(6); "Column 2"; SPC(6); "Column 3";


PRINT SPC(6); "Column 4"; SPC(6); "Column 5"




Output



The following line is printed using standard screen print


zones.





Column 1      Column 2      Column 3      Column 4      Column 5








The next line is printed using the SPC(n%) statement to achieve


the same results.





Column 1      Column 2      Column 3      Column 4      Column 5


SQR Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the square root of a numeric expression.


Syntax



    SQR( numeric-expression)

Remarks


The argument  numeric-expression must be greater than or equal to 0.

    SQR is calculated in single precision if  numeric-expression is an integer
or single-precision value. If you use any other numeric data type,  SQR is
calculated in double precision.


Example

The following example uses the  SQR function to plot the graph of y =
sqr(abs(x)) for -9  x  9 :


SCREEN 1 : COLOR 1         ' Low-resolution color graphics mode.


WINDOW (-9,-.25)-(9,3.25)  ' Convert screen to Cartesian coordinates.


LINE (-9,0)-(9,0)          ' Draw x-axis.


LINE (0,-.25)-(0,3.25)     ' Draw y-axis.


FOR x = -9 TO 9


    LINE(x,.04)-(x,-.04)   ' Put tick marks on x-axis.


NEXT x


FOR y = .25 TO 3.25 STEP .25


    LINE (-.08,y)-(.12,y)  ' Put tick marks on y-axis.


NEXT y


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 x


SSEG Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the segment address of a string (or 0 if the argument is a null
string).


Syntax



    SSEG( stringvariable$)

Remarks


The argument  stringvariable$ is the string variable for which you want the
segment address. It can be a simple string variable or a single element of a
string array. You cannot use fixed-length string arguments.


    SSEG returns the segment address for strings. It is typically used in
mixed-language programming to obtain far addresses before passing far
strings to procedures written in other languages.

    SSEG usually is used with far strings but also can be used with strings
stored in DGROUP (in which case it returns DGROUP's address). The offset of
a string can be found by using the  SADD function.

In OS/2 protected mode, the  SSEG function returns the selector of the
specified string variable.


See Also

    BLOAD,  BSAVE,  DEF SEG,  PEEK,  POKE,  SADD,  SSEGADD


Example

See the sadd function programming example, which uses the  SSEG function.


SSEGADD Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the far address of a string variable (both segment and offset).


Syntax



    SSEGADD( stringvariable$)

Remarks


The argument  stringvariable$ is the string variable for which you want an
address. It can be a simple string variable or a single element of a string
array. You cannot use fixed-length string arguments.

The  SSEGADD function combines the segment and offset information into one
long integer (4 bytes).


    SSEG returns the far address for a string. It is typically used in
mixed-language programming to obtain far addresses before passing far
strings to procedures written in other languages.

    SSEGADD usually is used with far strings but also can be used with strings
stored in DGROUP.

The offset of a string can be found with the  SADD function, while the
segment of a string can be found with the  SSEG function.


See Also

    BLOAD,  BSAVE,  DEF SEG,  SADD,  SSEG,  PEEK,  POKE


Example

The following example passes a string to a C routine. It uses  SSEGADD to
obtain the memory address of the string.

DEFINT A-Z


DECLARE SUB printmessage CDECL (BYVAL farstring AS LONG)


' Create the message as an ASCIIZ string (last character null),


' as required by the C function printf.


a$ = "This is a short example of a message" + CHR$(0)


' Call the C function with pointers


CALL printmessage(SSEGADD(a$))




This C routine prints a BASIC far string on the screen:


#include <stdio.h>


/* Define a procedure which inputs a string far pointer */


void printmessage (char far *farpointer)


{


/* print the string addressed by the far pointer */


printf( "%s\n", farpointer);


}


STACK Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a long integer that is the maximum stack size that can be allocated.


Syntax



    STACK

Remarks


The  STACK function can be used with the stack statement to set the stack to
the maximum possible size. For example:

STACK STACK


See Also


    CLEAR,  STACK Statement


Example

See the  FRE function programming example, which uses the  STACK function.


STACK Statement
────────────────────────────────────────────────────────────────────────────


Action

Resets the size of the stack.


Syntax



    STACK   longinteger&

Remarks


The default stack size is 3K for DOS and 3.5K for OS/2. The minimum stack
size

(if  longinteger& is 0) is 0.325K for DOS and 0.825K for OS/2.

The argument  longinteger& is the number of bytes to reserve for the stack.
If  longinteger& is omitted, the stack is reset to its default size. If you
request a stack space that is too large, the  STACK statement allocates as
much stack space as possible.

The  STACK statement is useful in programs that contain recursion and lots
of nesting of sub and function procedures.

The  STACK statement is allowed only at the module level.

The  STACK function can be used with the stack statement to set the stack to
the maximum possible size. For example:

STACK STACK


See Also


    CLEAR,  STACK Function


Example

See the  FRE function programming example, which uses the  STACK statement.


$STATIC, $DYNAMIC Metacommands
────────────────────────────────────────────────────────────────────────────


Action

Set aside storage for arrays, while program is either compiling ( $STATIC)
or running ( $DYNAMIC).


Syntax

    REM $STATIC
    '$STATIC

    REM $DYNAMIC
    '$DYNAMIC

Remarks


The  $STATIC metacommand 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  $DYNAMIC metacommand 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 also can use the  REDIM statement to
change the size of an array allocated using  $DYNAMIC.

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. All
arrays inside a  SUB or  FUNCTION procedure are dynamic unless the  STATIC
keyword is included in the  SUB or  FUNCTION statement.


Example

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


STATIC Statement
────────────────────────────────────────────────────────────────────────────


Action

Makes simple variables or arrays local to a  DEF  FN function, a  FUNCTION
procedure, or a  SUB procedure, and preserves values between calls.


Syntax



    STATIC  variable( )  AS  type ,  variable( )  AS  type...

Remarks


The  STATIC statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               The variable the procedure will
                                        use. It is either an array name
                                        followed by ( ), or a variable
                                        name.

    AS  type                               Declares the type of the variable.
                                        The type can be  INTEGER,  LONG,
                                        SINGLE,  DOUBLE,  STRING (for
                                        variable-length strings),  STRING
                                        *  length (for fixed-length
                                        strings),  CURRENCY, or a
                                        user-defined type.

Argument                                Description
────────────────────────────────────────────────────────────────────────────



    STATIC is a BASIC declaration that makes simple variables or arrays local
to a procedure (or a function defined by  DEF FN) and preserves the variable
value between procedure calls.

The  STATIC statement can appear only in a  SUB or  FUNCTION procedure or
DEF  FN function. Earlier versions of BASIC required the number of
dimensions in parentheses after an array name. The number of dimensions in
BASIC is now 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.

The differences between the  STATIC statement, the  STATIC attribute, and
the  $STATIC metacommand are:
╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Statement/Attribute                   Differences
────────────────────────────────────────────────────────────────────────────
    STATIC attribute on  SUB and         Declares default for variables to be
FUNCTION statements                   static. Variables having the same
                                        name as variables shared by
                                        module-level code are still shared.

    STATIC statement                     Makes specific variables static and
                                        overrides any variables shared by
                                        the module-level code.

    $STATIC metacommand                  Affects how memory is allocated for
                                        arrays.




See Also

    DEF  FN,  FUNCTION,  SUB


Example


The following example searches for every occurrence of a certain string
expression in a file and replaces that string with another string. The
program also prints the number of substitutions and the number of lines
changed.

INPUT "Name of file";F1$


INPUT "String to replace";Old$


INPUT "Replace with";Nw$


Rep = 0 : Num = 0


M = LEN(Old$)


OPEN F1$ FOR INPUT AS #1


CALL Extension


OPEN F2$ FOR OUTPUT AS #2


DO WHILE NOT EOF(1)


    LINE INPUT #1, Temp$


    CALL Search


    PRINT #2, Temp$


LOOP


CLOSE


PRINT "There were ";Rep;" substitutions in ";Num;" lines."


PRINT "Substitutions are in file ";F2$


END





SUB Extension STATIC


SHARED F1$,F2$


    Mark = INSTR(F1$,".")


    IF Mark = 0 THEN


        F2$ = F1$ + ".NEW"


    ELSE


        F2$ = LEFT$(F1$,Mark - 1) + ".NEW"


    END IF


END SUB





SUB Search STATIC


SHARED Temp$,Old$,Nw$,Rep,Num,M


STATIC R


    Mark = INSTR(Temp$,Old$)


    WHILE Mark


        Part1$ = LEFT$(Temp$,Mark - 1)


        Part2$ = MID$(Temp$,Mark + M)


        Temp$ = Part1$ + Nw$ + Part2$


        R = R + 1


        Mark = INSTR(Temp$,Old$)


    WEND


    IF Rep = R THEN


        EXIT SUB


    ELSE


        Rep = R


        Num = Num + 1


    END IF


END SUB


STICK Function
────────────────────────────────────────────────────────────────────────────


Action

Returns joystick coordinates.


Syntax



    STICK( n%)

Remarks


The argument   n% is a numeric expression whose value is an unsigned integer
from 0 to 3 that indicates which joystick coordinate value to return:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Argument         Value returned
────────────────────────────────────────────────────────────────────────────
0                Indicates the x coordinate of joystick A.
1                Indicates the y coordinate of joystick A.
2                Indicates the x coordinate of joystick B.
3                Indicates the y coordinate of joystick B.


Joystick coordinates range from 1 to 200 in both directions. You must use
STICK(0) before you use STICK(1), STICK(2), or STICK(3) because STICK(0) not
only returns the x coordinate of joystick A, but also records the other
joystick coordinates. These recorded coordinates are returned by calling
STICK(1), STICK(2), or STICK(3).


Note

The  STICK function is not available in OS/2 protected mode.


Example

See the  STRIG statements programming example, which uses the  STICK
function.

STOP Statement
────────────────────────────────────────────────────────────────────────────


Action

Terminates the program.


Syntax



    STOP  n%

Remarks


The  STOP statement halts a program and returns the value  n% to the
operating system. The value  n% can be used by DOS or OS/2 batch files or by
non-BASIC programs. If  n% is omitted, the  STOP statement returns a value
of 0. Untrapped errors and fatal errors set the value of  n% to -1.

You can place a  STOP statement anywhere in a program to terminate
execution.

In a stand-alone program,  STOP closes all files and returns to the
operating system; in the QBX environment,  STOP leaves files open and
returns to that environment.

If you use the /D, /E, or /X compiler option on the BC command line, the
STOP statement prints line numbers as follows:
╓┌──────────────────────────┌────────────────────────────────────────────────╖
If your program has:       STOP prints:
────────────────────────────────────────────────────────────────────────────
Line numbers               Number of the line where execution stopped.
No line number for  STOP   Most recent line number.
No line numbers            0


In the QBX environment,  STOP always returns an error level of 0, even if
you specify a different error level.

In some previous versions of BASIC,  STOP statements were used for
debugging. In the current version of BASIC, you do not have to use  STOP for
debugging.


See Also

    END,  SYSTEM


Example

See the  ON ERROR statement programming example, which uses the  STOP
statement.


STR$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string representation of the value of a numeric expression.


Syntax



    STR$( numeric-expression)

Remarks


If  numeric-expression is positive, the string returned by the  STR$
function contains a leading blank. The  VAL function complements  STR$.


See Also

    VAL


Example

The following example 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:

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




Output



Enter 0 to end.


Find cosine of: 3.1


COS(3.1) = -.9991351


Find cosine of: 0


STRIG Function
────────────────────────────────────────────────────────────────────────────


Action

Returns the status of a joystick trigger.


Syntax



    STRIG( n%)

Remarks


The  STRIG function is used to test the joystick trigger status.

The numeric expression  n% is an unsigned integer between 0 and 7 that
indicates the joystick and trigger to check. The following list describes
the values returned by the  STRIG( n%) function for different values of  n%:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Value                                   Returns
────────────────────────────────────────────────────────────────────────────
0                                       -1 if the lower trigger on
                                        joystick A was pressed since the
                                        last STRIG(0) call, 0 if not.

1                                       -1 if the lower trigger on
                                        joystick A is currently down, 0 if
                                        not.

2                                       -1 if the lower trigger on
                                        joystick B was pressed since the
                                        last STRIG(2) call, 0 if not.

3                                       -1 if the lower trigger on
                                        joystick B is currently down, 0 if
                                        not.
Value                                   Returns
────────────────────────────────────────────────────────────────────────────
                                        not.

4                                       -1 if the upper trigger on
                                        joystick A was pressed since the
                                        last STRIG(4) call, 0 if not.

5                                       -1 if the upper trigger on
                                        joystick A is currently down, 0 if
                                        not.

6                                       -1 if the upper trigger on
                                        joystick B was pressed since the
                                        last STRIG(6) call, 0 if not.

7                                       -1 if the upper trigger on
                                        joystick B is currently down, 0 if
                                        not.



For more information on joystick-event trapping, see the entry for  ON
event. You cannot use the  STRIG function inside a joystick-event trap
because the trigger information used by the  STRIG function will not be
available for  ON  STRIG.

In previous versions of BASIC, the statement  STRIG  ON enabled testing of
the joystick triggers;  STRIG OFF disabled joystick-trigger testing. The
current version of BASIC ignores these statements. (The old  STRIG ON and
STRIG OFF statements are different from the  STRIG( n%)  ON,  STRIG( n%)
OFF, and  STRIG( n%)  STOP statements. The  STRIG statements enable,
disable, and inhibit trapping of joystick events.)


Note

The  STRIG function is not available in OS/2 protected mode.


See Also

    ON  event,  STRIG Statements


Example

See the  STRIG statements programming example, which uses the  STRIG
function.

STRIG Statements
────────────────────────────────────────────────────────────────────────────


Action

Enable, disable, or suspend trapping of joystick activity.


Syntax



    STRIG( n%)  ON


    STRIG( n%)  OFF


    STRIG( n%)  STOP

Remarks


The argument  n% is the trigger number as defined in the following table:
╓┌──┌────────┌───────────────────────────────────────────────────────────────╖
n  Trigger  Joystick
────────────────────────────────────────────────────────────────────────────
0  Lower    First
2  Lower    Second
4  Upper    First
6  Upper    Second


    STRIG( n%)  ON enables joystick-event trapping. If joystick trigger  n% is
pressed after a  STRIG( n%)  ON statement, the routine specified in the  ON
STRIG statement is executed.

The  STRIG( n%)  OFF statement disables joystick-event trapping. No joystick
event trapping takes place until a  STRIG( n%)  ON statement is executed.
Events occurring while trapping is off are ignored. However, remembered
events are lost if  STRIG( n%)  OFF is executed.

The  STRIG( n%)  STOP statement suspends joystick-event trapping. No
joystick-event trapping takes place until a  STRIG( n%)  ON statement is
executed. Events occurring while trapping is suspended are remembered and
processed when the next  STRIG( n%)  ON statement is executed. However,
remembered events are lost if  STRIG( n%)  OFF is executed.

When a joystick-event trap occurs (that is, the  GOSUB is performed), an
automatic  STRIG  STOP is executed so that recursive traps cannot take
place. The  RETURN operation from the trapping routine automatically
performs a  STRIG  ON statement unless an explicit  STRIG  OFF was performed
inside the routine.

In previous versions of BASIC, the  STRIG  ON statement enabled testing of
the joystick triggers;  STRIG  OFF disabled joystick-trigger testing. The
current version of BASIC ignores the  STRIG  ON and  STRIG  OFF statements.

For more information, see Chapter 9, "Event Handling" in the  Programmer's
Guide.


Note

The  STRIG statement is not available for OS/2 protected mode.


See Also

    ON  event,  STRIG Function


Example


The following example sets up joystick events for two triggers on each of
two joysticks. It also displays the current x and y coordinate position of
both joysticks. If any trigger is pressed, control is passed to a routine
that indicates the state of the trigger; that is, whether the trigger is
down or up. This example exercises the  STRIG statements, the  STRIG
function, the  ON STRIG statement, the  STICK function, and the  EVENT
statements.

' Turn on event processing.


EVENT ON





' Enable the upper and lower triggers on both joysticks.


STRIG(0) ON 'Lower trigger, joystick A


STRIG(2) ON 'Lower trigger, joystick B


STRIG(4) ON  'Upper trigger, joystick A


STRIG(6) ON  'Upper trigger, joystick B





' Set up joystick-event processing for each trigger.


ON STRIG(0) GOSUB JoyTriggerHandler


ON STRIG(2) GOSUB JoyTriggerHandler


ON STRIG(4) GOSUB JoyTriggerHandler


ON STRIG(6) GOSUB JoyTriggerHandler





LOCATE 22, 6


PRINT "Press a trigger on either joystick to see a complete report."


LOCATE 23, 20


PRINT "Press ANY keyboard key to end the program."





' Infinite loop waiting for a joystick event or keyboard input.


DO


LOOP WHILE INKEY$ = ""





WrapItUp:


    CLS


    STRIG(0) OFF


    STRIG(2) OFF


    STRIG(4) OFF


    STRIG(6) OFF


    END





JoyTriggerHandler:


    ' Print a label on screen.


    LOCATE 10, 14: PRINT "Joystick A"


    LOCATE 10, 45: PRINT "Joystick B"


    LOCATE 22, 1: PRINT STRING$(80, 32)


    DO


        IF STRIG(1) THEN   ' Trigger 1, Joystick A.


                TriggerStatus$ = "DOWN"


        ELSE


                TriggerStatus$ = "UP  "


        END IF


        EVENT OFF


        LOCATE 16, 10: PRINT "Trigger 1 is "; TriggerStatus$


        EVENT ON





        IF STRIG(3) THEN   ' Trigger 1, Joystick B.


                TriggerStatus$ = "DOWN"


        ELSE


                TriggerStatus$ = "UP  "


        END IF


        EVENT OFF


        LOCATE 16, 42: PRINT "Trigger 1 is "; TriggerStatus$


        EVENT ON





        IF STRIG(5) THEN   ' Trigger 2, Joystick A.


                TriggerStatus$ = "DOWN"


        ELSE


                TriggerStatus$ = "UP  "


        END IF


        EVENT OFF


        LOCATE 18, 10: PRINT "Trigger 2 is "; TriggerStatus$


        EVENT ON





        IF STRIG(7) THEN    ' Trigger 2, Joystick B.


                TriggerStatus$ = "DOWN"


        ELSE


                TriggerStatus$ = "UP  "


        END IF


        EVENT OFF


        LOCATE 18, 42: PRINT "Trigger 2 is "; TriggerStatus$


        EVENT ON


        GOSUB UpdateXY


    LOOP WHILE INKEY$ = ""


    RETURN WrapItUp





UpdateXY:


    EVENT OFF


    LOCATE 12, 10: PRINT USING "X Position = ###"; STICK(0)


    LOCATE 14, 10: PRINT USING "Y Position = ###"; STICK(1)


    LOCATE 12, 42: PRINT USING "X Position = ###"; STICK(2)


    LOCATE 14, 42: PRINT USING "Y Position = ###"; STICK(3)


    EVENT ON


RETURN


STRING$ Function
────────────────────────────────────────────────────────────────────────────


Action

Returns a string whose characters all have a given ASCII code or whose
characters are all the first character of a string expression.


Syntax 1

    STRING$( m%,  n%)

Syntax 2

    STRING$( m%,  stringexpression$)


Remarks


The  STRING$ function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    m%                                     A numeric expression indicating
                                        the length of the string to return.

    n%                                     The ASCII code of the character to
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    n%                                     The ASCII code of the character to
                                        use to build the string. It is a
                                        numeric expression that BASIC
                                        converts to an integer value
                                        between 0 and 255, inclusive.

    stringexpression$                      The string expression whose first
                                        character is used to build the
                                        return string.






Examples

The first example uses  STRING$ to create part of a report heading:

Dash$ = STRING$(10,45)


PRINT Dash$;"MONTHLY REPORT";Dash$




Output



----------MONTHLY REPORT----------




This example uses  STRING$ to generate a bar graph:


PRINT TAB(7);"Daily Mean Temperature in Seattle" : PRINT


' Read and graph data for each month.


FOR Month = 1 TO 12 STEP 2


    READ Month$, Temp


    ' Print Temp-35 stars.


    PRINT Month$;" +"; STRING$(Temp-35,"*")


    PRINT "    |"


NEXT Month


' Print horizontal line.


PRINT "    +";


FOR X = 1 TO 7


    PRINT "----+";


NEXT X


PRINT


' Print temperature labels.


FOR X = 4 TO 39 STEP 5


    PRINT TAB(X); X+31;


NEXT X


PRINT





DATA Jan, 40, Mar, 46, May, 56


DATA Jul, 66, Sep, 61, Nov, 46




Output



Daily Mean Temperature in Seattle


Jan +*****
    |
Mar +***********
    |
May +*********************
    |
Jul +*******************************
    |
Sep +**************************
    |
Nov +***********
    |
    +----+----+----+----+----+----+----+
    35   40   45   50   55   60   65   70




StringAddress Routine
────────────────────────────────────────────────────────────────────────────


Action

Used in mixed-language programming to returns the far address of a
variable-length string.


Syntax



    far-address =  StringAddress( string-descriptor%);

Remarks


The syntax above is for the C language. For MASM, Pascal, and FORTRAN
examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in
the  Programmer's Guide.

    StringAddress returns the far address of the variable-length string defined
by  string-descriptor%. The argument  string-descriptor% is the near address
of a string descriptor within a non-BASIC routine.

A non-BASIC routine uses  StringAddress to find the far address of a BASIC
variable-length string. Calls to the  StringAddress routine always are made
from a non-BASIC routine to find the address of a string that was
transferred to BASIC from the non-BASIC routine.

For example, assume that you have passed a string from a MASM routine to
BASIC's string space using  StringAssign. The descriptor for the string
exists at offset descriptor. MASM can find the far address of the string
data using the following code:

leaax, descriptor ; offset of descriptor


pushax


extrnstringaddress: proc far


callstringaddress




The far address is returned in DX:AX. DX holds the segment and AX holds the
offset.



Note

If you are not doing mixed-language programming, there usually is no reason
to use  StringAddress. Instead, use  SSEGADD to find the far address of a
variable-length string.

For more information on mixed-language programming with strings, see Chapter
12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming
with Far Strings" in the  Programmer's  Guide.


See Also

    SSEGADD,  StringAssign,  StringLength,  StringRelease


Example


The following example shows how to use  StringAddress and  StringLength,
routines in the BASIC main library.

The program creates a string in BASIC, then passes it to MASM, which uses
StringAddress to find the data that needs to be printed. It uses
StringLength to tell the system the length of the string.

DEFINT A-Z


' Create a variable-length string.


Message1$ = "This string was sent to MASM for printing."


' Pass it to MASM to be printed.


CALL PrintMessage1(Message1$)




The following MASM procedure must be assembled and the .OBJ file linked to
the BASIC code listed above.


; *************************PrintMessage1************************


; Prints a string passed by BASIC.





.model  medium, basic; Use same model as BASIC.


.code





; Define procedure with one-word argument.


PrintMessage1 procuses ds, descriptor





; Define external (BASIC library) procedures.


extrnStringAddress: proc far


extrnStringLength: proc far





mov ax, descriptor ; Find length of string.


pushax


callStringLength


pushax; Save length on stack.





mov ax, descriptor ; Go find out the


pushax; address of the string


CALLStringAddress; data.





mov ds, dx  ; Address of string.


mov dx, ax


mov bx, 01  ; Handle of printer.


pop cx; Length of string.


mov ah, 40h ; Have DOS print it.


int 21h


ret


PrintMessage1 endp





end


StringAssign Routine
────────────────────────────────────────────────────────────────────────────


Action

Used in mixed-language programming to transfer string data from one
language's memory space to that of another.


Syntax



    StringAssign( sourceaddress&,  sourcelength%,  destaddress&,  destlength%);

Remarks


The syntax above is for the C language. However, the order of the arguments
in the syntax follows BASIC, Pascal and FORTRAN calling conventions rather
than the C calling convention. (In BASIC, Pascal and FORTRAN, the arguments
are passed in the order in which they appear in the source code. In C, the
arguments are passed in the reverse order.)

For MASM, Pascal, and FORTRAN examples, see Chapter 13, "Mixed-Language
Programming with Far Strings" in the  Programmer's Guide.

The  StringAssign routine uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    sourceaddress&                         The far address of the start of
                                        string data (if the source is a
                                        fixed-length string), or the far
                                        address of the string descriptor
                                        (if the source is a
                                        variable-length string). The
                                        sourceaddress& is a long integer.

    sourcelength%                          The string length (if the source
                                        is a fixed-length string), or 0
                                        (if the source is a
                                        variable-length string). The
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        variable-length string). The
                                        sourcelength% is an integer.

    destaddress&                           The far address of the start of
                                        string data (if the destination is
                                        a fixed-length string), or the far
                                        address of the string descriptor
                                        (if the destination is a
                                        variable-length string). The
                                        destaddress& is a long integer.

    destlength%                            The string length (if the
                                        destination is a fixed-length
                                        string), or0 (if the destination
                                        is a variable-length string). The
                                        destlength% is an integer.





The  StringAssign routine is used in mixed-language programming to transfer
a string from BASIC to a non-BASIC routine or from a non-BASIC routine to
BASIC. A typical use is to transfer a string from BASIC to a non-BASIC
routine, process the string using the non-BASIC routine, and then transfer
the modified string back to BASIC.

Calls to the  StringAssign routine are usually made from a C, MASM, Pascal,
or FORTRAN routine. Seldom, if ever, would you call  StringAssign from
inside a BASIC program.

    StringAssign can be used to transfer both near and far strings. Using
StringAssign, you can write mixed-language programs that are
near-string/far-string independent.

MASM, C, Pascal, and FORTRAN deal only with fixed-length strings. When
programming in these languages you can use  StringAssign to create a new
BASIC variable-length string and transfer fixed-length string data to it.
For example, to transfer a MASM fixed-length string containing the word
"Hello" to a BASIC variable-length string, you would use the following data
structure:


fixedstringdb "Hello" ; source of data


descriptor dd 0; descriptor for destination




The second data element, descriptor, is a 4-byte string descriptor
initialized to zero. BASIC interprets this to mean that it should create a
new variable-length string and associate it with the address labelled
descriptor.


To create a new BASIC variable-length string and transfer fixed-length data
to it, the  StringAssign routine requires four arguments:

    ■         The far address of the fixed-length string in the MASM data
            segment.

    ■         The length of the fixed-length string in the MASM data segment.

    ■         The far address of the string descriptor in the MASM data
            segment.

    ■         0 (to indicate that the string in the BASIC data segment will be
            a variable-length string).

The following MASM code pushes these arguments on the stack and calls
StringAssign:

pushds; segment of fixed-length string


lea ax, fixedstring ; offset of fixed-length string


pushax


mov ax, 5; length of "Hello"


pushax


pushds; segment of descriptor


lea ax, descriptor ; offset of descriptor


pushax


mov ax, 0 ; 0 = variable-length string


pushax


extrnstringassign: proc far


callstringassign




When the call to  StringAssign is made, BASIC will fill in the double-word
descriptor with the correct string descriptor.

Note

When creating a new variable-length string, you must allocate 4 bytes of
static data for a string descriptor as shown above. Allocating the data on
the stack will not work.

For more information on mixed-language programming with strings, see Chapter
12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming
with Far Strings" in the  Programmer's  Guide.


See Also


    StringAddress,  StringLength,  StringRelease


Example

The following example shows how to use  StringAssign and  StringRelease,
routines in the BASIC main library. The program gets a MASM string and
prints it on the screen.

DEFINT A-Z


' Declare external MASM procedures.


DECLARE FUNCTION MakeString$


DECLARE SUB ReleaseIt





' Get string from MASM and print it.


PRINT MakeString





' Have MASM release the variable-length string it created.


CALL ReleaseIt




The following MASM procedure must be assembled and the .OBJ file linked to
the BASIC code listed above:


; ************************** MakeString ***************************


; Create a fixed-length string and assign it to a BASIC


; variable-length string. Release the string after BASIC uses it.





.model  medium, basic ; Use same model as BASIC.


.data


; Create MASM string and a place for BASIC to create a


; variable-length string descriptor.


String2db  "This is a string created by MASM."


Descriptor dd  0





.code





; Declare BASIC library routines to be used.


extrnStringAssign: proc far


extrnStringRelease: proc far





MakeString proc; Push arguments:


pushds; MASM string segment


lea ax, String2; MASM string offset


pushax


mov ax, 33; MASM string length


pushax


pushds; BASIC descriptor segment


lea ax, Descriptor


pushax; BASIC descriptor offset


xor ax, ax; Variable-length indicator


pushax


callStringAssign; Assign the string.





lea ax, descriptor ; Return with descriptor


ret ; address in AX.


MakeString endp





ReleaseIt  proc; Routine to release


lea ax, Descriptor ; the string.


pushax


callStringRelease


ret


ReleaseIt  endp


end


StringLength Routine
────────────────────────────────────────────────────────────────────────────


Action

Used in mixed-language programming to return the length of a variable-length
string.


Syntax



    length =  StringLength( string-descriptor%);

Remarks


The syntax above is for the C language. For MASM, Pascal, and FORTRAN
examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in
the  Programmer's Guide.

A non-BASIC routine uses  StringLength to return the number of characters in
a BASIC variable-length string.

Calls to the  StringLength routine are usually made from a non-BASIC
routine. The argument  string-descriptor% is an integer that is the near
address of a string descriptor within a non-BASIC routine.

As an example, assume that a MASM routine takes a pointer to a string
descriptor as a parameter. MASM can find the length of the string data with
the following code:

movax, psdparm; offset of descriptor


pushax


extrnstringlength: proc far


callstringlength




The length of the string is returned in AX.



Note

If you are not doing mixed-language programming, there is usually no reason
to use  StringLength. Instead, use  LEN to find the length of a
variable-length string.

For more information on mixed-language programming with strings, see Chapter
12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming
with Far Strings" in the  Programmer's  Guide.


See Also

L EN,  StringAddress,  StringAssign,  StringRelease


Example

See the  StringAddress routine programming example, which uses the
StringLength routine.


StringRelease Routine
────────────────────────────────────────────────────────────────────────────


Action

Deallocates variable-length strings that have been transferred to BASIC's
string space from a non-BASIC routine.


Syntax



    StringRelease( string-descriptor%);

Remarks


The syntax above is for the C language. For MASM, Pascal, and FORTRAN
examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in
the  Programmer's Guide.

    StringRelease is used in mixed-language programming.  StringRelease is used
by a non-BASIC routine to deallocate variable-length strings that have been
transferred to BASIC's string space from the non-BASIC routine.

Calls to the  StringRelease routine are made from a non-BASIC routine to
free up space in BASIC's data area. The argument  string-descriptor% is an
integer that is the near address of a string descriptor within a non-BASIC
routine.

BASIC automatically deallocates strings allocated by BASIC. However, strings
that have been transferred to BASIC from a non-BASIC routine should be
deallocated from the non-BASIC routine using the  StringRelease routine.
(The reason for this is that  StringAssign transfers strings but not string
descriptors. Without the string descriptor, BASIC cannot deallocate the
string; the deallocation has to be done from the non-BASIC routine with
StringRelease.)

As an example, assume that you have passed a string from a MASM routine to
BASIC's string space using  StringAssign. To deallocate this string,
assuming a descriptor for the variable-length string exists at offset
descriptor, the code would be as follows:

leaax, descriptor ; offset of descriptor


pushax


extrnstringrelease: proc far


call stringrelease


Warning


Use the  StringRelease routine only to deallocate variable-length strings
that have been transferred to BASIC's string space from a non-BASIC routine.
Never use it on strings created by BASIC. Doing so may cause unpredictable
results.

For more information on mixed-language programming with strings, see Chapter
12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming
with Far Strings" in the  Programmer's  Guide.


See Also

    StringAddress,  StringAssign,  StringLength


Example

See the  StringAssign routine programming example, which uses the
StringRelease routine.


SUB Statement
────────────────────────────────────────────────────────────────────────────


Action

Declares the name and the parameters of a  SUB procedure.


Syntax



    SUB  globalname( parameterlist)  STATIC


    statementblock


    EXIT SUB


    statementblock


    END SUB

Remarks


The  SUB statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    globalname                             A variable name up to 40
                                        characters long. This name cannot
                                        appear in any other  SUB or
                                        FUNCTION statement in the same
                                        program or the user library. The
                                        name cannot include a
                                        type-declaration character ( %,  &,
                                            !,  #,  @, or  $).

    parameterlist                          The list of variables,
                                        representing parameters, that will
                                        be passed to the SUB procedure
                                        when it is called. Multiple
                                        variables are separated by commas.
                                        Parameters are passed by reference,
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        Parameters are passed by reference,
                                        so any change to a parameter's
                                        value inside the  SUB procedure
                                        changes its value in the calling
                                        program.

    STATIC                                 Indicates that the  SUB
                                        procedure's local variables are to
                                        be saved between calls. Without
                                        STATIC, the local variables are
                                        allocated each time the  SUB
                                        procedure is invoked, and the
                                        variables' values are lost when
                                        the  SUB returns to the calling
                                        program. The  STATIC attribute
                                        does not affect variables that are
                                        used in a  SUB procedure but
                                        declared outside the procedure in
                                        DIM or  COMMON statements using
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        DIM or  COMMON statements using
                                        the  SHARED statement.

    EXIT                                   Causes an immediate exit from a
                                        SUB. Program execution continues
                                        with the statement after the  CALL
                                        statement.





A  SUB  parameterlist argument has the following syntax:

    variable( )  AS  type  ,  variable( )  AS  type...
╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               A BASIC variable name. Previous
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    variable                               A BASIC variable name. Previous
                                        versions of BASIC required the
                                        number of dimensions in
                                        parentheses after an array name.
                                        In the current version of BASIC,
                                        the number of dimensions is not
                                        required.

    AS  type                               The type of the variable:  INTEGER,
                                            LONG,  SINGLE,  DOUBLE,  CURRENCY,
                                            STRING, or a user-defined type.
                                        You cannot use a fixed-length
                                        string, or an array of
                                        fixed-length strings, as a
                                        parameter. However, you can use a
                                        simple fixed-length string as an
                                        argument in a  CALL statement;
                                        BASIC converts a simple
                                        fixed-length string argument to a
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        fixed-length string argument to a
                                        variable-length string argument
                                        before passing the string to a
                                        SUB procedure.






A  SUB procedure is a separate procedure, like a  FUNCTION procedure.
However, unlike a  FUNCTION procedure, a  SUB procedure cannot be used in an
expression.

    SUB and  END  SUB mark the beginning and end of a  SUB procedure. You also
can use the optional  EXIT  SUB statement to exit a  SUB procedure.

    SUB procedures are called by a  CALL statement or by using the procedure
name followed by the argument list. See the entry for the  CALL statement.
BASIC  SUB procedures can be

recursive -- they can call themselves to perform a given task. See the
second example below.

The  STATIC attribute indicates that all variables local to the  SUB
procedure are static -- their values are saved between calls. Using the
STATIC keyword increases execution speed slightly.  STATIC usually is not
used with recursive  SUB procedures.

Any  SUB procedure variables or arrays are considered local to that  SUB
procedure, 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  SUB procedure.


See Also

    CALL (BASIC),  DECLARE (BASIC),  SHARED,  STATIC Statement


Examples

See the  CALL (BASIC) statement programming example, which uses the  SUB
statement.


SWAP Statement
────────────────────────────────────────────────────────────────────────────


Action

Exchanges the values of two variables.


Syntax



    SWAP  variable1,  variable2

Remarks


Any type of variable can be swapped (integer, long, single precision, double
precision, string, currency, or record). However, if the two variables are
not exactly the same data type, BASIC generates the error message Type
mismatch.


Example

The following example 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





SYSTEM Statement
────────────────────────────────────────────────────────────────────────────


Action

Closes all open files and returns control to the operating system.


Syntax



    SYSTEM  n%

Remarks


The  SYSTEM statement returns control to the operating system and returns
the value  n% to the operating system. The value  n% can be used by DOS or
OS/2 batch files or by non-BASIC programs. If  n% is omitted, the  SYSTEM
statement returns a value of 0. Untrapped errors and fatal errors set the
value of  n% to -1.

In a stand-alone program,  SYSTEM returns to the operating system and closes
all files; in the QBX environment,  SYSTEM stops program execution and
closes all files.


Note

A program containing a  SYSTEM statement exits to the operating system if
run from the QBX command line with the /RUN option. Entering a  SYSTEM
statement in the Immediate window terminates BASIC.


BASICA

    END and  SYSTEM are distinct in BASICA, but act identically in the current
version of BASIC.


See Also

    END,  STOP


Example

See the  ON ERROR statement programming example, which uses the  SYSTEM
statement.




















TAB Function

Action

Moves the text cursor to a specified print position when used in the  PRINT,
    PRINT  USING,  LPRINT,  LPRINT  USING, and  PRINT  # statements.

Syntax


────────────────────────────────────────────────────────────────────────────
    TAB( column%)


Remarks

The argument  column% is a numeric expression that is the column number of
the new print position.

The leftmost print position is always 1. The rightmost position is the
current line width of the output device (which can be set with the  WIDTH
statement).

This is an example of using  TAB in the  PRINT function:

PRINT  TAB(10); City$; TAB(40); State$; TAB(45); Zip$

The behavior of  TAB depends on the relationship between three values:
column%, the current print position on the current output line when the  TAB
function is executed, and the current output-line width:

    ■   If the current print position on the current line is greater than
        column%,  TAB skips to  column% on the next output line.

    ■   If  column% is less than 1,  TAB moves the print position to column 1.

    ■   If  column% is greater than the output-line width,  TAB calculates:

    ■   print position =  column%  MOD width.  ■   n

        If the calculated print position is less than the current print
        position, the cursor jumps to the next line at the calculated print
        position. If the calculated print position is greater than the current
        print position, the cursor moves to the calculated print position on
        the same line.


See Also


    LPRINT,  PRINT,  SPACE$,  SPC

Example

In the following example  TAB is also used with the  PRINT statement to
center a text string on an 80-column screen.

CLS
INPUT "What is your full name "; Name$
PRINT
' Get the length of Name$, divide by 2, and subtract from screen
' center point.
PRINT TAB(40 - (LEN(Name$) \ 2)); Name$
END

TAN Function

Action

Returns the tangent of the angle  x, where  x is in radians.

Syntax


    TAN( x)


Remarks

The tangent of an angle in a right triangle is the ratio between the length
of the side opposite an angle and the length of the side adjacent to it.

    TAN is calculated in single precision if  x is an integer or
single-precision value. If you use any other numeric data type,  TAN is
calculated in double precision.

To convert values from degrees to radians, multiply the angle (in degrees)
times /180

(or .0174532925199433). To convert a radian value to degrees, multiply it by
180/

    (or 57.2957795130824). In both cases,   3.141593.

BASICA

In BASICA, if  TAN overflows, the interpreter generates an error message
that reads Overflow, returns machine infinity as the result, and continues
execution.

If  TAN overflows, BASIC does not display machine infinity and execution
halts (unless the program has an error-handling routine).

See Also

    ATN,  COS,  SIN

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' CGA screen mode.

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
Aspect = 4 * (200 / 640) / 3' Screen 2 is 640 x 200 pixels.
H = 180 - Height
B = 15 + (Baselen / Aspect)
LINE (15,180)-(B,180)' Draw triangle.
LINE -(B,H)
LINE -(10,180)
LOCATE 24,1 : PRINT "Press any key to continue...";
DO
LOOP WHILE INKEY$=""

TEXTCOMP Function

Action

Compares two strings as they would be compared by ISAM.

Syntax


    TEXTCOMP( a$,  b$)

Remarks

The arguments  a$ and  b$ are two strings.  TEXTCOMP compares their relative
order as they would be sorted by an ISAM index and returns an integer value
of 1, 0, or -1:

    ■   -1 is returned when  a$ compares less than  b$.

    ■   0 is returned when  a$ compares equal to  b$.

    ■   1 is returned when  a$ compares greater than  b$.


Only the first 255 characters are considered in the comparison.


The comparison is not case sensitive ("A" is the same as "a"), and any
trailing spaces are removed.  TEXTCOMP uses the International Sorting Tables
for sorting international characters. For more information, see Appendix E,
"International Sorting Tables."

See Also

    SetFormatCC; Appendix E, "International Character Sort Order Tables"

Example

The BookLook program uses  TEXTCOMP to compare titles in a table named
BookStock and then prints each title that begins with the word QuickBASIC.
Because the comparison performed by  TEXTCOMP is not case-sensitive, all
variations of titles whose first word is QuickBASIC will be printed.


TIME$ Function

Action

Returns the current time from the operating system.

Syntax

    TIME$


Remarks

The  TIME$ function returns an eight-character string in the form  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 P.M. is shown as
20:00:00.

To set the time, use the  TIME$ statement.

See Also

    TIME$ Statement,  TIMER Function

Example

The following example converts the 24-hour clock used by  TIME$ to 12-hour
output:

T$ = TIME$
Hr = VAL(T$)
IF Hr < 12 THEN Ampm$ = " AM" ELSE Ampm$ = " PM"
IF Hr > 12 THEN Hr = Hr - 12
PRINT "The time is" STR$(Hr) RIGHT$(T$,6) Ampm$


Output

The time is 11:26:31 AM


TIME$ Statement

Action

Sets the time.

Syntax


    TIME$= stringexpression$

Remarks

The  TIME$ statement changes the system time, which stays changed until you
change it again or reboot your computer.

The argument  stringexpression$ must be in one of the following forms:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
Form           Description
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 P.M. would be entered as 20:00:00.

This statement complements the  TIME$ function, which returns the current
time.

See Also

    TIME$ Function

Example

The following statement sets the current time to 8:00 A.M.:

TIME$="08:00:00"

TIMER Function

Action

Returns the number of seconds elapsed since midnight.

Syntax


    TIMER


Remarks

The  TIMER function can be used with the  RANDOMIZE statement to generate a
random number. It also can be used to time programs or parts of programs.

See Also

Randomize

Example

The following example searches for the prime numbers from 3 to 10,000 using
a variation of the Sieve of Eratosthenes. The  TIMER function is used to
time the program.

DEFINT A-Z
CONST UNMARK = 0, MARKIT = NOT UNMARK
DIM Mark(10000)
CLS               ' Clear 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


Output

Program took .28125 seconds to find the 1228 primes.

TIMER Statements

Action

Enable, disable, or suspend timer-event trapping.

Syntax


    TIMER ON

    TIMER OFF

    TIMER STOP


Remarks

    TIMER  ON enables timer-event trapping. A timer event occurs when  n
seconds have elapsed (as specified in the  ON  TIMER statement). If a timer
event occurs after a  TIMER  ON statement, the routine specified in the  ON
TIMER statement is executed.

    TIMER  OFF disables timer-event trapping. No timer-event trapping takes
place until a  TIMER  ON statement is executed. Events occurring while
trapping is off are ignored.

    TIMER  STOP suspends timer-event trapping. No trapping takes place until a
TIMER  ON statement is executed. Events occurring while trapping is off are
remembered and processed when the next  TIMER  ON statement is executed.
However, remembered events are lost if  TIMER  OFF is executed.

When a timer-event trap occurs (that is, the  GOSUB is performed), an
automatic  TIMER  STOP is executed so that recursive traps cannot take
place. The  RETURN operation from the trapping routine automatically
performs a  TIMER  ON statement unless an explicit  TIMER  OFF was performed
inside the routine.

For more information, see Chapter 9, "Event Handling" in the  Programmer's
Guide.

See Also

    ON  event,  TIMER Function

Example


This example uses the  ON TIMER statement to trap timer events. It 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

TRON/TROFF Statements

Action

Trace the execution of program statements.

Syntax


    TRON
    TROFF


Remarks

In the QBX 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 display line numbers only when compiled with
the Debug option or the /D option on the BC command line.

Note

The debugging features of the QBX environment make these statements
unnecessary.

Example

There is no programming example for the  TRON statement.


TYPE Statement

Action

Defines a data type or ISAM table type that contains one or more elements or
table columns.

Syntax


    TYPE  usertype

    elementname  AS  typename

    elementname  AS  typename .

    .
    .

    END  TYPE


Remarks

The  TYPE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    usertype                               A user-defined data type or ISAM
                                        table type. The argument  usertype
                                        follows the same rules as a BASIC
                                        variable name. In the case of an
                                        ISAM table,  usertype identifies a
                                        user-defined table structure.

    elementname                            An element or table column of the
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    elementname                            An element or table column of the
                                        user-defined type. For a data type,
                                            elementname follows the same
                                        rules as a BASIC variable name.
                                        For a table type,  elementname
                                        follows the ISAM naming
                                        conventions.

    typename                               A user-defined data type, nested
                                        user-defined type (databases only),
                                        an array, or one of the following
                                        data types: integer, long, single
                                        (non-ISAM types only), double,
                                        fixed-length string, or currency .





If  usertype is a table type, any  elementname arguments are the names of
columns in the table. The names must be exact matches to existing column
names and must follow the ISAM naming conventions.

Note

Line numbers and line labels aren't allowed in  TYPE... END  TYPE blocks.

ISAM names use the following conventions:

    ■   They have no more than 30 characters.

    ■   They use only alphanumeric characters (A-Z, a-z, 0-9).

    ■   They begin with an alphabetic character.

    ■   They include no BASIC special characters.


Note


BASIC now supports user-defined types for ISAM tables, the currency data
type for dollars-and-cents math and static arrays in user-defined types.
Before you can use an ISAM table, you must declare a record type for the
records that make up the table. Instances of this type are used to pass
records to and from the table.

The following  TYPE statement illustrates the use of static arrays. The
record StateData includes the CityCode static array, and the record
Washington has the same structure

    as StateData:

TYPE StateData

CityCode (1 TO 100) AS INTEGER ' Declare a static array.

County AS STRING * 30

END TYPE

DIM Washington(1 TO 100) AS StateData
When you declare a static array within a user-defined type, its dimensions
must be declared with numeric constants rather than variables. For
efficiency, make sure that arrays within a user-defined type start on even
offsets. You can create very large records when you include static arrays
within records. Putting one of these records within a  SUB procedure can use
large amounts of stack space.

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:

TYPE Keyword AS STRING * 40 END TYPE
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 be declared only in
the module-level code, you can declare a variable to be of a user-defined
type anywhere in the module, even in a  SUB or  FUNCTION procedure.

Use the  DIM,  REDIM,  COMMON,  STATIC, or  SHARED statements to declare a
variable to be of a user-defined type.

The keyword  REM cannot be used as a field name in a  TYPE statement. The
text that follows  REM is treated as a comment.

Note

If you have defined a table to have columns A, B, C, and D, you can use a
user-defined type that has only the columns you need (any subset of A, B, C,
and D).

See Also

    OPEN

Example

See the  PUT statement (file I/O) programming example, which uses the  TYPE
statement.


UBOUND Function

Action

Returns the upper bound (largest available subscript) for the indicated
dimension of an array.

Syntax


    UBOUND( array ,  dimension%)


Remarks

The  UBOUND function is used with the  LBOUND function to determine the size
of an array.  UBOUND takes the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    array                                  The name of the array variable to
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    array                                  The name of the array variable to
                                        be tested.

    dimension%                             An integer ranging from 1 to the
                                        number of dimensions in  array;
                                        indicates which dimension's upper
                                        bound is returned. Use 1 for the
                                        first dimension, 2 for the second
                                        dimension, and so on. This
                                        argument is optional for
                                        one-dimensional arrays.





    UBOUND returns the values listed below for an array with the following
dimensions:

DIM A(1 TO 100, 1 TO 3, -3 TO 4)

╓┌───────────────────────────┌───────────────────────────────────────────────╖
Invocation                  Value returned
────────────────────────────────────────────────────────────────────────────
UBOUND(A,1)                 100
UBOUND(A,2)                 3
UBOUND(A,3)                 4




You can use the shortened syntax  UBOUND( array) for one-dimensional arrays
because the default value for  dimension% is 1. Use the  LBOUND function to
find the lower limit of an array dimension.

See Also

    DIM,  LBOUND,  OPTION BASE

Example


The following example shows how  LBOUND and  UBOUND can be used together in
a  SUB procedure to determine the size of an array passed to the procedure
by a calling program.

DECLARE SUB PRNTMAT (A!())
DIM A(0 TO 3, 0 TO 3)
FOR I% = 0 TO 3
FOR J% = 0 TO 3
A(I%, J%) = I% + J%
NEXT J%
NEXT I%
CALL PRNTMAT(A())
END

SUB PRNTMAT (A()) STATIC
FOR I% = LBOUND(A, 1) TO UBOUND(A, 1)
FOR J% = LBOUND(A, 2) TO UBOUND(A, 2)
PRINT A(I%, J%); " ";
NEXT J%
PRINT : PRINT
NEXT I%
END SUB

UCASE$ Function

Action

Returns a string expression with all letters in uppercase.

Syntax


    UCASE$ ( stringexpression$)


Remarks

The  UCASE$ function takes a string variable, string constant, or string
expression as its single argument.  UCASE$ works with both variable- and
fixed-length strings.

    UCASE$ and  LCASE$ are helpful in making string comparisons that are not
case-sensitive.

See Also

    LCASE$

Example

This example contains a  FUNCTION procedure, YesQues, that returns a Boolean
value depending on how the user responds. The procedure uses  UCASE$ to make
a non-

    case-sensitive test of the user's response.

DEFINT A-Z
FUNCTION YesQues(Prompt$,Row,Col) STATIC
OldRow=CSRLIN
OldCol=POS(0)
' Print prompt at Row, Col.
LOCATE Row,Col : PRINT Prompt$ "(Y/N):";
DO
' Get the user to press a key.
DO
Resp$=INKEY$
LOOP WHILE Resp$=""
Resp$=UCASE$(Resp$)
' Test to see if it's yes or no.
IF Resp$="Y" OR Resp$="N" THEN
EXIT DO
ELSE
BEEP
END IF
LOOP
PRINT Resp$;' Print the response on the line.
LOCATE OldRow,OldCol' Move the cursor back to the old position.
YesQues=(Resp$="Y")' Return a Boolean value.
END FUNCTION

DO
LOOP WHILE NOT YesQues("Do you know the frequency?",12,5)

UEVENT Statements

Action

Enable, disable, or suspend a user-defined event.

Syntax


    UEVENT ON

    UEVENT OFF

    UEVENT STOP


Remarks

The effects of the  UEVENT statements are like those of other event-trapping
statements (such as  COM or  KEY). 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.

When a user-defined event trap occurs (that is, the  GOSUB is performed), an
automatic  UEVENT STOP is executed so that recursive traps cannot take
place. The  RETURN operation from the trapping subroutine automatically
performs a  UEVENT ON statement unless an explicit  UEVENT OFF was performed
inside the subroutine.

See Also

    ON  event,  SetUEvent

Example

The following example shows a primitive use of the  ON UEVENT statement.

PRINT "Entering an odd number causes a UEVENT to occur."
ON UEVENT GOSUB Event1
UEVENT ON
DO
    PRINT "Enter a number --> ";
    N = VAL(INPUT$(1)): PRINT N: PRINT
    SELECT CASE N
        CASE 1, 3, 5, 7, 9
            CALL SetUevent    'Odd number was entered, causing UEVENT.
        CASE ELSE
            PRINT "No UEVENT occurred.": PRINT
    END SELECT
    LoopCount = LoopCount + 1
LOOP UNTIL LoopCount = 10

Event1:
    PRINT "Now processing the UEVENT. The odd number was"; N
    RETURN

UNLOCK Statement

Action

Releases locks applied to parts of a file.

Syntax


    UNLOCK #  filenumber% , { record& |  start&  TO  end&}


Remarks

The  UNLOCK statement is used only after a  LOCK statement. See the entry
for the  LOCK statement for a complete discussion.

The  UNLOCK statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the file.

    record&                                The number of the record or byte
                                        to be locked. The argument
                                        record& can be any number between
                                        1 and 2,147,483,647 (equivalent to
                                        231 -1), inclusive. A record can
                                        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,  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,  record&,  start&, and  end& represent the number
of a record relative to the beginning of the file. The first record is
record 1.

Warning

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.

Do not use  LOCK and  UNLOCK on devices or ISAM tables.

See Also

    LOCK... UNLOCK

Example

See the  LOCK... UNLOCK statement programming example, which uses the
UNLOCK statement.


UPDATE Statement

Action

Adds an updated record to an ISAM table, overwriting the current record.

Syntax


    UPDATE #  filenumber%,  recordvariable


Remarks

The  UPDATE statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    filenumber%                            The number used in the  OPEN
                                        statement to open the table.

    recordvariable                         A variable of the user-defined
                                        type  tabletype that was specified
                                        in the  OPEN statement. It is the
                                        record that will overwrite the
                                        current record.





    UPDATE replaces the current record with  recordvariable. It remains the
current record.

Use the  RETRIEVE statement to fetch the current record and place its data
into  recordvariable. You can change the data in  recordvariable, then use
the  UPDATE statement to update the current record with the changes you've
made. Use  INSERT to add a record to a table without overwriting the current
record.

If the values passed to  recordvariable do not match the record strucure in
the user-defined type, BASIC generates the error message Type Mismatch.The
record structure includes the names and types of columns or fields.

BASIC removes trailing spaces from strings used in an update.

See Also

    INSERT;  RETRIEVE;  SEEKGT,  SEEKGE,  SEEKEQ

Example

See the programming example for the  SEEKGT,  SEEKGE, and  SEEKEQ
statements, which uses the  UPDATE statement.


VAL Function

Action

Returns the numeric value of a string of digits.

Syntax


    VAL( stringexpression$)


Remarks

The argument  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 blanks, tabs, and line feeds from the argument
string. For example, the code below returns the value 1615198:

VAL("    1615 198th Street")

See Also



    STR$


Example


The following example prints the names and addresses of people with specific
telephone area codes:

' 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

VARPTR$ Function

Action

Returns a string representation of a variable's address for use in  DRAW and
    PLAY statements.

Syntax


    VARPTR$( variablename)


Remarks

The argument  variablename is the name of a variable in the program. If
variablename is an array element, dimensions for the array must be specified
before  VARPTR$ is used. The array must consist of variable-length strings.

Note

To guarantee correct results, use the value returned by  VARPTR$ immediately
after invoking the function.

BASICA

In this version of BASIC,  VARPTR$ must be used in the  DRAW and  PLAY
statements to execute substrings containing variables. BASICA supports both
the  VARPTR$ syntax and the syntax containing just the variable name.

See Also

    DRAW;  PLAY Statement (Music);  VARPTR,  VARSEG

Example

See the  PLAY function programming example, which uses the  VARPTR$
function.


VARPTR, VARSEG Functions

Action

Return the address of a variable or string descriptor.

Syntax


    VARPTR( variablename)

    VARSEG( variablename)


Remarks

The argument  variablename can be any BASIC variable, including a record
variable or record element.

    VARPTR and  VARSEG return the address of a variable (for numeric variables)
or the address of a string descriptor (for string variables) as indicated in
the following table:

╓┌────────────────────────┌────────────────────────┌─────────────────────────╖
For a variable of type:  VARSEG returns:          VARPTR returns:
────────────────────────────────────────────────────────────────────────────
Numeric                  Segment address of       Offset address of
                            variable                 variable

String                   Segment address of       Offset address of string
                            string  descriptor       descriptor (near strings)
                            (near strings)

Name not previously      Segment address of new   Offset address of new
defined                  variable ( VARSEG also   variable ( VARPTR also
                            creates the new          creates the  new
                            variable)                variable)





When  variablename is a numeric variable, the  VARPTR function returns an
unsigned integer (the offset of the variable within its segment). When
variablename is a numeric variable, the  VARSEG function returns an unsigned
integer (the segment address of the variable). When  variablename is a
near-string variable,  VARSEG and  VARPTR return a string-descriptor address
that contains the length of the string and the address at which it is
stored.

If  variablename is not defined before  VARPTR or  VARSEG is called, the
variable is created and its address is returned.

    VARPTR and  VARSEG are often used with  Absolute,  BLOAD,  BSAVE,
Interrupt,  PEEK,  POKE, or when passing arrays to procedures written in
other languages. When using  VARPTR or  VARSEG to get the address of an
array, use the first element of the array as the argument:

DIM A(150)

.

.

.

ArrAddress=VARPTR(A(1))

You can 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 in far memory.



When programming with OS/2 protected mode, the  VARSEG function returns the
selector of the specified variable or array.



Note


Because many BASIC statements move variables in memory, use the values
returned by  VARPTR and  VARSEG immediately after the functions are used.


It is not meaningful to use  VARSEG and  VARPTR for far strings, since the
format of the far strings' string descriptor is different from the string
descriptor for near strings. See the entry for  StringAddress for
information on locating the address of a far string's string descriptor. See
the entries for  SSEG,  SADD, and  SSEGADD for information on locating the
segment and offset addresses of far strings.


You can no longer use  VARPTR to get the address of a file's buffer. Use the
    FILEATTR function to get information about a file.


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 could be rewritten as follows to work with the current version
of BASIC:


DIM Cube(675)

.

.

.

' Change segment to segment containing Cube.

DEF SEG=VARSEG(Cube(1))

BSAVE "graph.dat",VARPTR(Cube(1)),2700

DEF SEG' Restore BASIC segment.

The  VARSEG function, combined with  VARPTR, replaces the PTR86 subprogram
used in previous versions of BASIC.


VARPTR and VARSEG and Expanded Memory Arrays

Do not pass expanded memory arrays to non-BASIC procedures. If you start QBX
with the /Ea switch, any of these arrays may be stored in expanded memory:

    ■   Numeric arrays less than 16K in size.

    ■   Fixed-length string arrays less than 16K in size.

    ■   User-defined-type arrays less than 16K in size.




If you want to pass expanded memory arrays to non-BASIC procedures, first
start QBX without the /Ea switch. (Without the /Ea switch, no arrays are
stored in expanded memory.)


For more information on using expanded memory, see "Memory Management for
QBX" in  Getting Started.

See Also

    DEF SEG,  PEEK,  POKE,  SADD,  VARPTR$

Example

The following example illustrates how to use the  VARPTR and  VARSEG
functions in a  CALL statement to pass a BASIC array to a C routine.

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

This C routine increments values of a BASIC array. It must be compiled and
the .OBJ file linked to the BASIC code above.

/* 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]++;
}

VIEW Statement

Action

Defines screen limits for graphics output.

Syntax


    VIEW  SCREEN ( x1!,  y1!)-( x2!,  y2!) ,  color& ,  border&


Remarks

The list below describes the parts of the  VIEW statement:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
    SCREEN                                 Specifies that coordinates of
                                        subsequent graphics statements are
                                        absolute to the screen, not
                                        relative to the viewport. Only
                                        graphics within the viewport are
                                        plotted. When  SCREEN is omitted,
                                        all points are plotted relative to
                                        the viewport ( x1! and  y1! are
                                        added to the coordinates before
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        added to the coordinates before
                                        plotting the point).

( x1!,  y1!)-( x2!,  y2!)               Indicates a rectangular area on
                                        the screen. The arguments  x1!,
                                        y1!,  x2!, and  y2! are numeric
                                        expressions that are the
                                        coordinates of diagonally opposite
                                        corners of the viewport. The
                                        argument  ( x1!,  y1!)-( x2!,  y2!)
                                        must be within the physical bounds
                                        of the screen in the current
                                        screen mode.

    color&                                 A numeric expression that
                                        specifies the color with which to
                                        fill the viewport. If you omit
                                        color&, the viewport area is not
                                        filled (it has the same color as
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        filled (it has the same color as
                                        the screen background color).

    border&                                Any numeric expression for
                                        border& causes a line to be drawn
                                        around the viewport. The value of
                                        border determines the color of the
                                        line. If you omit  border&, no
                                        line is drawn around the viewport.




The  VIEW statement defines a viewport or "clipping region," which is a
rectangular section of the screen to which graphics output is limited. If
VIEW is used with no arguments, the entire screen is defined as the
viewport.  RUN and  SCREEN also define the entire screen as the viewport.

See Also

    PRINT,  SCREEN Statement,  WINDOW

Examples

See the  WINDOW statement programming example, which uses the  VIEW
statement.


VIEW PRINT Statement

Action

Sets the boundaries of the screen text viewport.

Syntax


    VIEW PRINT  topline%  TO  bottomline%


Remarks

The argument  topline% is the number of the upper line in the text viewport;
    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 BASIC was started. For more information, see the entry for the
    WIDTH statement, and Chapter 3, "File and Device I/O" in the  Programmer's
Guide.

Statements and functions that operate within the defined text viewport
include  CLS,  INPUT,  LOCATE,  PRINT, the  SCREEN function, and  WRITE.

See Also

    CLS,  LOCATE,  PRINT,  SCREEN Function,  SCREEN Statement,  WIDTH

Example

The following example 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$ <> ""

WAIT Statement

Action

Suspends program execution while monitoring the status of a machine input
port.

Syntax


    WAIT  portnumber,  and-expression% ,  xor-expression%


Remarks

The  WAIT statement uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    portnumber                             An unsigned integer expression
                                        between 0 and 65,535, inclusive,
                                        that is the number of the machine
                                        input port.

    and-expression%                        An integer expression that is
                                        repeatedly combined with the bit
                                        pattern received at the port,
                                        using an  AND operator; when the
                                        result is nonzero, the  WAIT
                                        statement stops monitoring the
                                        port, and program execution
                                        resumes with the next program
                                        statement.

    xor-expression%                        Can be used to turn bits on and
                                        off in the received bit pattern
                                        before the  AND operation is
                                        applied.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        applied.





The  WAIT statement is an enhanced version of the  INP function; it suspends
execution until a specified bit pattern is input from an input port, using
the following four steps:

    ■   1.  The data byte read from the port is combined, using an  XOR
        operation, with

        xor-expression%. If  xor-expression% is omitted, it is assumed to be
        0.

    ■   2. The result is combined with  and-expression% using an  AND
        operation.

    ■   3. If the result is zero, the first two steps are repeated.

    ■   4. If the result is nonzero, execution continues with the next program
        statement.

        It is possible to enter an infinite loop with the  WAIT statement if
        the input port fails to develop a non-zero 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 BASIC to do an  AND operation on the bit pattern
received at the DOS I/O port HandShakePort with the bit pattern represented
by 2 (00000010).




Note

The  WAIT statement is not available in OS/2 protected mode.

See Also

    INP,  OUT

Example


The following example demonstrates the use of the  WAIT statement.

' Open and close the port at the proper baud rate.

OPEN "COM1:9600,N,8,1,BIN" FOR RANDOM AS #1

CLOSE #1

    PortNum% = &H3F8 'COM1

    NonPrintCharMask% = 96

' Wait until there's some activity on COM1.

' Mask out characters less than 32 for the first input character.

    LOCATE 12, 15: PRINT "Waiting for a printable input character. "

    WAIT PortNum%, NonPrintCharMask%

' Once a printable character comes in, execution continues.

DO

    'Get a character from the port and evaluate.

    A% = INP(PortNum%)

    SELECT CASE A%

        CASE 7

            Character$ = "   BELL    "

        CASE 8

            Character$ = "BACK SPACE "

        CASE 9

            Character$ = "    TAB    "

        CASE 13

            Character$ = "    CR     "

        CASE 32

            Character$ = "   SPACE   "

        CASE 127

            Character$ = "    DEL    "

        CASE IS < 31, IS > 127

            Character$ = "unprintable"

        CASE ELSE

            Character$ = SPACE$(5) + CHR$(A%) + SPACE$(5)

    END SELECT

    LOCATE 12, 15

    ' Report the input character.

    PRINT "Numeric Value                    ASCII Character"

    LOCATE 14, 20

    PRINT A%; TAB(50); Character$

    IF A% > 127 THEN STOP

    LOCATE 23, 25

    PRINT "Press ANY key to quit."

LOOP WHILE INKEY$ = ""

END

WHILE...WEND Statement

Action

Executes a series of statements in a loop, as long as a given condition is
true.

Syntax


    WHILE  condition
    .

    .

    .


    WEND


Remarks

The argument  condition is  a numeric expression that BASIC evaluates as
true (nonzero) or

    false (zero).

If  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

BASIC's  DO... LOOP statement provides a more powerful and flexible
loop-control structure.

    WHILE... WEND loops can be nested to any level. Each  WEND matches the most
recent  WHILE. When BASIC encounters an unmatched  WHILE statement, it
generates the error message WHILE without WEND. If BASIC encounters an
unmatched  WEND statement, it generates the error message WEND without
WHILE.

Note

Do not branch into the body of a  WHILE... WEND loop without executing the
WHILE statement. This may cause run-time errors or program problems that are
difficult to locate.

See Also

    DO... LOOP

Example


The following example performs a bubble sort on the array A$. Assigning the
variable Exchange a non-zero value (true) forces one pass through the
WHILE... WEND loop (this construction is unnecessary with  DO... LOOP). When
there are no more swaps, all elements of A$ are sorted, Exchange is false
(equal to zero), and the program continues execution with the line following
the  WEND statement.

' Bubble sort of array A$.

CONST FALSE = 0, TRUE = -1

DIM I AS INTEGER

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

WIDTH Statements

Action

Assign an output-line width to a device (such as a printer) or to a file, or
change the number of columns and lines displayed on the screen.

Syntax


    WIDTH  screenwidth% ,  screenheight%

    WIDTH { #filenumber% |  device$},  width%

    WIDTH LPRINT  width%


Remarks

The different forms of the  WIDTH statements are explained in the following
list:

    WIDTH  screenwidth% ,  screenheight%

Sets number of columns and lines to display on the screen. The value of
screenwidth% must be either 40 or 80; default is 80. The table below has
details about the value of  screenheight%.

    WIDTH  # filenumber%,  width%

Sets to  width% the output-line width of an output device already opened as
a file (for example, LPT1 or CONS). The argument  filenumber% is the number
used to open the file with the  OPEN statement. The number sign (#) in front
of  filenumber% is not optional.This form permits altering the width while a
file is open, because the statement  takes effect immediately.

    WIDTH  device$, width%

Sets to  width% the line width of  device (a device filename). The  device
should be a string expression (for example, "LPT1:"). Note that he  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. Equivalent to the statement form:WIDTH "LPT1:",
width%Not all of the argument values are valid in every case; it depends on
the installed display adapter and the screen mode established by the most
recently executed  SCREEN statement. The value of  screenheight% may be 25,
30, 43, 50, or 60, depending on the display adapter used and the screen
mode.


Table 1.21 lists the number of lines that can be displayed when a program is
started.



See Also

    SCREEN Statement,  VIEW PRINT

Example

The following example demonstrates the effect of the  WIDTH statement on
output:

CLS
' Open the port at the proper baud rate.
OPEN "COM1:9600,N,8,1,ASC,LF" FOR OUTPUT AS #1
Test$ = "1234567890"' Set up a test string.
WIDTH #1, 3' Change width to 3.
PRINT #1, Test$


Output

123
456
789
0

WINDOW Statement

Action

Defines the dimensions of the current graphics viewport window.

Syntax


    WINDOW  SCREEN ( x1!,  y1!)  - ( x2!,  y2!)


Remarks

The  WINDOW statement allows the user to create a customized coordinate
system to draw lines, graphs, or objects without being constrained by the
physical coordinate values and orientation of the graphics viewport. This is
done by redefining the graphics viewport coordinates with the "view
coordinates" ( x1!,  y1!) and ( x2!,  y2!). These view coordinates are
single-precision numbers.

    WINDOW defines a coordinate system that is mapped to the physical
coordinates of the viewport. All subsequent graphics statements use the
window 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 coordinates are the same as the viewport
coordinates.) The  WINDOW SCREEN variant inverts the normal Cartesian
direction of the y coordinate, so y values go from negative to positive from
top to bottom.

Figure 1.1 shows the effects of  WINDOW and  WINDOW SCREEN on a line drawn
in screen mode 2. Notice the change in the coordinates of the screen
corners.

See Also


    SCREEN Statement,  VIEW,  WIDTH

Example


The following example uses BASIC graphics statements to generate a fractal.
This fractal shows a subset of a class of numbers known as complex numbers;
this subset is called the "Mandelbrot Set," named after an IBM researcher.
The program uses the  VIEW,  WINDOW,  PMAP, and  PSET statements.

DEFINT A-Z         ' Default variable type is integer.

DECLARE SUB ScreenTest (EM%, CR%, VL%, VR%, VT%, VB%)



' Set maximum number of iterations per point.

CONST MAXLOOP = 30, MAXSIZE = 1000000

CONST FALSE = 0, TRUE = NOT FALSE       ' Boolean constants.

' Set window parameters.

CONST WLeft = -1000, WRight = 250, WTop = 625, WBottom = -625



' Call ScreenTest to find out if this is an EGA machine,

' and get coordinates of viewport corners.

ScreenTest EgaMode, ColorRange, VLeft, VRight, VTop, VBottom



' Define viewport and corresponding window.

VIEW (VLeft, VTop)-(VRight, VBottom), 0, ColorRange

WINDOW (WLeft, WTop)-(WRight, WBottom)



LOCATE 24, 10: PRINT "Press any key to quit.";

XLength = VRight - VLeft

YLength = VBottom - VTop

ColorWidth = MAXLOOP \ ColorRange



' Loop through each pixel in viewport and calculate

'  whether or not it is in the Mandelbrot Set.

FOR Y = 0 TO YLength       ' Loop through every line in the viewport.

    LogicY = PMAP(Y, 3)     ' Get the pixel's logical y coordinate.

    PSET (WLeft, LogicY)    ' Plot leftmost pixel in the line.

    OldColor = 0            ' Start with background color.

    FOR X = 0 TO XLength    ' Loop through every pixel in the line.

        LogicX = PMAP(X, 2)  ' Get the pixel's logical x coordinate.

        MandelX& = LogicX

        MandelY& = LogicY

        ' Do the calculations to see if this point is in

        '  the Mandelbrot Set.

        FOR I = 1 TO MAXLOOP

            RealNum& = MandelX& * MandelX&

            ImagNum& = MandelY& * MandelY&

            IF (RealNum& + ImagNum&) >= MAXSIZE THEN EXIT FOR

            MandelY& = (MandelX& * MandelY&) \ 250 + LogicY

            MandelX& = (RealNum& - ImagNum&) \ 500 + LogicX

        NEXT I

' Assign a color to the point.

        PColor = I \ ColorWidth

        ' If color has changed, draw a line from the

        ' last point referenced to the new point,

        '  using the old color.

        IF PColor <> OldColor THEN

            LINE -(LogicX, LogicY), (ColorRange - OldColor)

            OldColor = PColor

        END IF

        IF INKEY$ <> "" THEN END

    NEXT X

    ' Draw the last line segment to the right edge of

    '  the viewport.

    LINE -(LogicX, LogicY), (ColorRange - OldColor)

NEXT Y

DO : LOOP WHILE INKEY$ = ""

SCREEN 0, 0             ' Restore the screen to text mode,

WIDTH 80                ' 80 columns.

END



BadScreen:              ' Error handler that is invoked if

    EgaMode = FALSE      '  there is no EGA graphics card.

    RESUME NEXT



' The ScreenTest SUB procedure tests to see if user has EGA hardware

' EGA hardware with SCREEN 8. If this causes an error, the EM flag

' is set to FALSE, and the screen is set with SCREEN 1. ScreenTest

' also sets values for corners of viewport (VL = left, VR = right,

' VT = top, VB = bottom), scaled with the correct aspect ratio so

' that the viewport is a perfect square.

SUB ScreenTest (EM, CR, VL, VR, VT, VB) STATIC

    EM = TRUE

    ON ERROR GOTO BadScreen

    SCREEN 8, 1

    ON ERROR GOTO 0

    IF EM THEN           ' No error, so SCREEN 8 is OK.

        VL = 110: VR = 529

        VT = 5: VB = 179

        CR = 15           ' 16 colors (0 - 15).

    ELSE                 ' Error, so use SCREEN 1.

        SCREEN 1, 1

        VL = 55: VR = 264

        VT = 5: VB = 179

        CR = 3            ' 4 colors (0 - 3).

    END IF

END SUB

WRITE Statement

Action

Sends data to the screen.

Syntax


    WRITE  expressionlist


Remarks

The argument  expressionlist specifies one or more values to be written on
the screen, separated by commas, with double quotation marks around the
strings and no spaces around numbers.

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 can be numeric and/or string expressions. They must
be separated by commas.

When the printed items are written, each item is separated from the last by
a comma. Printed strings are delimited by quotation marks. After the last
item in the list is printed, BASIC inserts a carriage-return-and-line-feed
sequence. The  WRITE statement writes numeric values without leading or
trailing spaces.

See Also

    PRINT, PRINT USING

Example

The following example shows the difference between the  PRINT and  WRITE
statements:

CLS         ' Clear screen.

A=80 : B=90 : C$="That's all." : D=-1.0E-13

WRITE A,B,C$,D

PRINT A,B,C$,D



Output

80,90,"That's all.",-1E-13
    80            90           That's all.  -1E-13

WRITE # Statement

Action

Writes data to a sequential file.

Syntax


    WRITE  #filenumber%,  expressionlist


Remarks

The  filenumber% is the number used in the  OPEN statement to open the file
that will contain the data being written. 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
expressionlist, the  WRITE # statement writes a blank line to the file.

The  WRITE # statement, unlike the  PRINT # statement, inserts commas
between items and quotation marks around strings 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 you use  WRITE # in an attempt to write data to a sequential file
restricted by a  LOCK statement, BASIC generates the error message
Permission denied unless the error is trapped by the program. All of BASIC's
usual error-handling routines can trap and examine this error.

See Also

    LOCK,  OPEN,  PRINT #,  WRITE

Example

See the  LINE INPUT # statement programming example, which uses the  WRITE #
statement.


♀Part 2:  Date/Time, Financial, Format Functions


Part 2 is an alphabetical reference for each function found in the
Date/Time, Financial, and Format add-on libraries. The syntax, options, and
action performed by each are described, as well as examples of how to use
each in a BASIC program.
Leading off Part 2 is a set of summary tables for the add-on libraries. Each
table lists the names of the functions to use for specific tasks, along with
the results.

The following groups of functions are included:
    ■   Date/time functions
    ■   Financial functions
    ■   Format functions



DateSerial# Function

Action
Returns a serial number that represents the date of the arguments.

Syntax
    DateSerial# ( year%,  month%,  day%)

Remarks
The  DateSerial# function uses the following arguments:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Argument         Description
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
Argument         Description
────────────────────────────────────────────────────────────────────────────
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    DateSerial#,  Day&,  Month&,  Now#, Serial Numbers,  Weekday&,  Year&



Day& Function


Action
Takes a date/time serial number and returns the day of the month.

Syntax
    Day& ( serial#)


Remarks
The  Day& function returns an integer between 1 and 31, inclusive, that
represents the day of the month corresponding to the argument.

The argument  serial# is  a serial number that represents a date and/or
time. For more information, see the topic "Serial Numbers" in this section.

To use  Day& in the QBX environment, use the DTFMTER.QLB Quick library. To
use  Day& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Hour&,  Minute&,  Month&,  Now#,  Second&, Serial Numbers,  Weekday&,
Year&



DDB# Function

Action
Returns depreciation of an asset for a specific period using the
double-declining-balance method.

Syntax
    DDB# ( cost#,  salvage#,  life#,  period#,  status%)


Remarks
The double-declining-balance method computes depreciation at an accelerated
rate. Depreciation is highest in the first period and decreases in
successive periods.

The  DDB# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    cost#                                  The initial cost of the asset.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    cost#                                  The initial cost of the asset.

    salvage#                               The value at the end of the useful
                                        life of the asset.

    life#                                  The useful life of the asset.

    period#                                The period for which asset
                                        depreciation is desired.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





Note
All numeric arguments must be positive values.

The arguments  life# and  period# must use the same units. If  life# is
given in months,  period# also must be given in months.

    DDB# uses the formula:

Depreciation for a period = (( cost - total depreciation from prior periods)
* 2) /  life

To use  DDB# in the QBX environment, use the FINANCER.QLB Quick library. To
use  DDB# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header
file contains the necessary function declarations for using the financial
functions. For more information on using libraries, see Chapter 18, "Using
LINK and LIB" and Chapter 19, "Creating and Using Quick Libraries" in the
Programmer's Guide.


See Also
SLN #,  SYD#



FormatX$ Functions

Action
Formats a numeric value.

Syntax
    FormatI$ ( expression#,  fmt$)
    FormatL$ ( expression#,  fmt$)
    FormatS$ ( expression#,  fmt$)
    FormatD$ ( expression#,  fmt$)
    FormatC$ ( expression#,  fmt$)


Remarks
The  Format X $ functions  return  a string that contains the formatted
expression. The functions use the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    expression#                            A numeric expression to be
                                        formatted.

    fmt$                                   A string expression comprising
                                        BASIC display-format characters
                                        that detail how the expression is
                                        to be displayed.




There are five separate add-on-library functions, depending on the data type
of  expression#. Use the appropriate function as shown below:

╓┌──────────────────────┌────────────────────────────────────────────────────╖
Function               Data type of  expression
────────────────────────────────────────────────────────────────────────────
    FormatI$              Integer
    FormatL$              Long integer
Function               Data type of  expression
────────────────────────────────────────────────────────────────────────────
    FormatL$              Long integer
    FormatS$              Single precision
    FormatD$              Double precision
    FormatC$              Currency




If  fmt$ is a null string, BASIC uses the general format (which gives output
identical to output with no formatting).

To use the  Format X $ functions in the QBX environment, use the DTFMTER.QLB
Quick library. To use the  Format X $ functions outside of the QBX
environment, link your program with the appropriate DTFMT xx.LIB file.
Depending on the compiler options you chose when you installed BASIC, one or
more of the following files will be available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The FORMAT.BI header
file contains the necessary function declarations for using the  Format X $
functions. For more information on using libraries, see Chapter 18, "Using
LINK and LIB" and Chapter 19, "Creating and Using Quick Libraries" in the
Programmer's Guide.


Available Formats

The  Format X $ functions provide a wide range of formats for numeric and
date/time data. The following symbols are used to create the formats:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
Null string                             Display the number in general
                                        format.

0                                       Digit placeholder.

                                        If the number has fewer digits on
                                        either side of the decimal point
                                        than there are zeros on either
                                        side of the decimal point in the
                                        format, the extra zeros are
                                        displayed. If the number has more
                                        digits to the right of the decimal
                                        point than there are zeros to the
                                        right in the format, the number is
                                        rounded to as many decimal places
                                        as there are zeros to the right.
                                        If the number has more digits to
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
                                        If the number has more digits to
                                        the left of the decimal point than
                                        there are zeros to the left in the
                                        format, the extra digits are
                                        displayed.

#                                       Digit placeholder.

                                        Follows the same rules as for the
                                        0 digit placeholder, except that
                                        extra zeros are not displayed if
                                        the number has fewer digits on
                                        either side of the decimal point
                                        than there are number signs (#) on
                                        either side of the decimal point.

.                                       Decimal point.

                                        This symbol determines how many
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
                                        This symbol determines how many
                                        digits BASIC displays to the right
                                        and left of the decimal point.
                                        Depending on the country code set
                                        using the  SetFormatCC routine,
                                        BASIC may use the comma as the
                                        decimal point. If the format
                                        contains only number signs (#) to
                                        the left of this symbol, numbers
                                        smaller than 1 are begun with a
                                        decimal point. To avoid this, you
                                        should use 0 as the first digit
                                        placeholder to the left of a
                                        decimal point instead  of #.

%                                       Percentage.

                                        The expression is multiplied by
                                        100 and the percent character (%)
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
                                        100 and the percent character (%)
                                        is inserted.






╓┌───────────────────────────────────────┌───────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
,                                       Thousands separator.

                                        BASIC separates thousands by
                                        commas (or by periods, depending
                                        on the country code set using the
                                        SetFormatCC routine) if the format
                                        contains a comma surrounded by
                                        digit placeholders (0 or #). Two
                                        adjacent commas, or a comma
────────────────────────────────────────────────────────────────────────────
                                        adjacent commas, or a comma
                                        immediately to the left of the
                                        decimal point location (whether
                                        there is a decimal specified or
                                        not) means "Omit the three digits
                                        that fall between these commas, or
                                        between the comma and the decimal
                                        point, rounding as needed."

E-  E+  e-  e+                          Scientific format.

                                        If a format contains one digit
                                        placeholder (0 or #) to the right
                                        of an E-, E+, e-, or e+, BASIC
                                        displays the number in scientific
                                        format and inserts an E or e. The
                                        number of digit placeholders to
                                        the right determines the number of
                                        digits in the exponent. Use E- or
                                        e- to place a minus sign next to
────────────────────────────────────────────────────────────────────────────
                                        e- to place a minus sign next to
                                        negative exponents. Use E+ or e+
                                        to place a minus sign next to
                                        negative exponents and a plus sign
                                        next to positive exponents.

:  -  +  $  ( )  Space                  Display that literal character.

                                        To display characters other than
                                        one of these, precede each
                                        character with a backslash( \ ) or
                                        enclose the character(s) in double
                                        quotation marks ("").

\                                       Display the next character in the
                                        format string.

                                        Many characters in the format
                                        string have a special meaning and
                                        cannot be displayed as literal
────────────────────────────────────────────────────────────────────────────
                                        cannot be displayed as literal
                                        characters unless they are
                                        preceded by a backslash. The
                                        backslash is not displayed. This
                                        is the same as enclosing the next
                                        character in double quotation
                                        marks.

                                        Examples of such characters are
                                        the date- and time-formatting
                                        characters (y, m, d, h, s, a, and
                                        p) and the numeric-formatting
                                        characters (#, 0, %, E, e, comma,
                                        and period).

" abc"                                  Display whatever text is inside
                                        the double quotation marks.

                                        To include a text string in  fmt$,
                                        you must use CHR$(34) to enclose
────────────────────────────────────────────────────────────────────────────
                                        you must use CHR$(34) to enclose
                                        the text (34 is the ASCII code for
                                        double quotation mark).






The  Format X $ functions have the following general syntax:  Format X $ (
expression#,  fmt$). Some sample numeric formats are shown below for
different values of  fmt $ and  expression#. (These examples all assume the
country code is set to 1, United States.)

The following example has two sections: the first section defines the format
for positive numbers and zeros; the second section defines the format for
negative numbers.

$#,##0;($#,##0)
You can use from one to three sections:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
One section only                        The format applies to all numbers.

Two sections                            The first section applies to
                                        positive numbers and zeros; the
                                        second to negative numbers.

Three sections                          The first section applies to
                                        positive numbers, the second to
                                        negative numbers, and the third to
                                        zeros.





If you have semicolons with nothing between them, the missing section is
printed using the format of the positive value. For example, the following
format will display positive and negative numbers using the format in the
first section, and "Zero" if the value is zero:

"$#,##0;;Z\ero"

Date/Time Formats

Date/time serial numbers can be formatted with date/time or numeric formats
(since date/time serial numbers are stored as floating-point values).

Date/time formats have the following meanings:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
d dd ddd dddd                           Display the day as a number
                                        without leading zeros (1-12), as a
                                        number with leading zeros (01-12),
                                        as an abbreviation (Sun-Sat), or
                                        as a full name (Sunday-Saturday).

m mm mmm mmmm                           Display the month as a number
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
m mm mmm mmmm                           Display the month as a number
                                        without leading zeros (1-12), as a
                                        number with leading zeros (01-12),
                                        as an abbreviation (Jan-Dec), or
                                        as a full month name
                                        (January-December). If you use m
                                        or mm immediately after the h or
                                        hh symbol, the minute rather than
                                        the month is displayed.

yy yyyy                                 Display the year as a two-digit
                                        number (00 - 99), or as a
                                        four-digit number (1900 - 2040).

h hh                                    Display the hour as a number
                                        without leading zeros (0 - 23), or
                                        as a number with leading zeros (00
                                        - 23). If the format contains an
                                        AM or PM, the hour is based on the
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
                                        AM or PM, the hour is based on the
                                        12-hour clock. Otherwise, the hour
                                        is based on the 24-hour clock.

m mm                                    Display the minute as a number
                                        without leading zeros (0 - 59),
                                        or as a number with leading zeros
                                        (00 - 59). The m or mm must appear
                                        after an h or hh, or the month is
                                        displayed rather than the minute.

s ss                                    Display the second as a number
                                        without leading zeros (0 - 59), or
                                        as a number with leading zeros (00
                                        - 59)..

AM / PM am / pm A / P a / p             Display the hour using the 12-hour
                                        clock. AM, am, A, or a is
                                        displayed with any time before
Symbol                                  Meaning
────────────────────────────────────────────────────────────────────────────
                                        displayed with any time before
                                        noon. PM, pm, P, or p is displayed
                                        with any time between noon and
                                        11:59 P.M.





The following are examples of date and time formats:
d-mmmm-yy       7-December-58
d-mmmm          7-December
mmmm-yy         December-58
h:mm AM/PM      8:50 PM
h:mm:ss AM/PM   8:50:35 PM
h:mm            20:50
h:mm:ss         20:50:35
m/d/yy h:mm     12/7/58 20:50

See Also
    PRINT,  PRINT  USING,  STR$



FV# Function

Action
Returns the future value of an annuity based on periodic, constant payments
and a constant interest rate.

Syntax
    FV# ( rate#,  nper#,  pmt#,  pv#,  type%,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The  FV# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10/12, or
                                        .0083.

    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pmt#                                   The payment to be made each period.
                                        It  usually contains principal and
                                        interest and does not change over
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        interest and does not change over
                                        the life of the annuity.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
                                        make.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.

Argument                                Description
────────────────────────────────────────────────────────────────────────────

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





The arguments  rate# and  nper# must use consistent units. For example:

Note
For all arguments, cash you pay out, such as deposits to savings, is
represented by negative numbers; cash you receive, such as dividend checks,
is represented by positive numbers.

A number of other functions are related to  FV#:
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    NPer# returns the number of periods (payments) for an annuity.
    ■    Pmt# returns the periodic total payment for an annuity.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.
    ■    PV# returns the present value of an annuity.
    ■    Rate# returns the interest rate per period of an annuity.


To use  FV# in the QBX environment, use the FINANCER.QLB Quick library. To
use  FV# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    IPmt#,  NPer#,  Pmt#, P Pmt#, PV#, R ate#




Hour& Function

Action
Takes a date/time serial number and returns the hour.

Syntax

    Hour& ( serial#)


Remarks
The  Hour& function returns an integer between 0 (12:00 A.M.) and 23 (11:00
P.M.) that represents the hour of the day corresponding to the argument.

The argument  serial# is  a serial number that represents a date and/or
time. For more information, see the topic "Serial Numbers" in this section.

To use  Hour& in the QBX environment, use the DTFMTER.QLB Quick library. To
use  Hour&  outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Minute&,  Month&,  Second&, Serial Numbers,  Weekday&,  Year&



IPmt# Function

Action
Returns the interest payment for a given period of an annuity based on
periodic, constant payments and a constant interest rate.

Syntax
    IPmt# ( rate#,  per#,  nper#,  pv#,  fv#,  type%,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The  IPmt# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10 divided by
                                        12, or .0083.

    per#                                   The payment period; must be in the
                                        range from 1 to  nper#.

    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
                                        make.

    fv#                                    The future value or the cash
                                        balance you want sometime in the
                                        future after the last payment is
                                        made. The future value of a loan,
                                        for instance, is 0. As another
                                        example, if you think you will
                                        need $50,000 in 18 years to pay
                                        for your child's education, then
                                        $50,000 is the future value.

    type%                                  An integer expression that
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





The arguments  rate# and  nper# must use
consistent units.


Note
For all arguments, negative numbers equal cash you pay out, and positive
numbers equal cash you receive.

A number of other functions are related to  IPmt#:
    ■    FV# returns the the future value of an annuity.
    ■    NPer# returns the number of periods (payments) for an annuity.
    ■    Pmt# returns the periodic total payment for an annuity.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.
    ■    PV# returns the present value of an annuity.
    ■    Rate# returns the interest rate per period of an annuity.


To use  IPmt# in the QBX environment, use the FINANCER.QLB Quick library. To
use  IPmt# outside of the QBX environment, link your program with the
appropriate FINANCxx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode



The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
FV#,  NPer#,  Pmt#,  PPmt#, PV#,  Rate#

Example


This example uses the  IPmt# function to calculate how much you will pay
over the lifetime of a loan where all the payments are of equal value.

To run this example, you must link it with the appropriate FINANC xx.LIB and
DTFMT xx.LIB files or use the FINANCER.QLB and DTFMTER.QLB Quick libraries.
The following include files must also be present:

' $INCLUDE: 'FINANC.BI'
' $INCLUDE: 'FORMAT.BI'

CONST YEARMONTHS = 12
CONST ENDPERIOD = 0
CONST BEGINPERIOD = 1
CONST DOLLARFORMAT$ = "$###,###,###.00"
FutureVal = 0
DEFDBL A-Z
DIM Status  AS INTEGER

' Get user input.
CLS
INPUT "Enter the annual percentage rate of your loan"; APR
PRINT
INPUT "What is the principal amount of your loan"; PresentVal
PRINT
INPUT "How many monthly payments do you have to make"; NumPeriods
PRINT
DO WHILE PaymentTypeString$ <> "B" AND PaymentTypeString$ <> "E"
    PRINT "Payments due at the beginning or end of the month? ";
    PaymentTypeString$ = UCASE$(INPUT$(1))
LOOP

' Set up the correct payment type.
IF PaymentTypeString$ = "B" THEN
    PaymentType = BEGINPERIOD
    PRINT "Beginning"
ELSE
    PaymentType = ENDPERIOD
    PRINT "End"
END IF
PRINT

' Put APR in proper form.
IF APR > 1 THEN APR = APR / 100

FOR Period = 1 TO
NumPeriods

    ' Calculate the Interest paid each month.
InterestPmt = ABS(IPmt#(APR / YEARMONTHS, Period, NumPeriods,_
                    -PresentVal, FutureVal, PaymentType, Status))
    ' Check for an error.
    IF Status THEN
        PRINT "There was a calculation error."
        END
    END IF
    ' Accumulate a total.
    TotalInterest = TotalInterest + InterestPmt
NEXT Period

' Format and display results.
TotalInterest$ = FormatD$(TotalInterest, DOLLARFORMAT$)
PresentVal$ = FormatD$(PresentVal, DOLLARFORMAT$)
TotalPaid$ = FormatD$(TotalInterest + PresentVal, DOLLARFORMAT$)
PRINT
PRINT "You'll pay a total of "; TotalPaid$; " on your "; PresentVal$;
PRINT " loan, of which "; TotalInterest$; " is interest."



IRR# Function

Action
Returns the internal rate of return for a series of periodic cash flows
(payments and receipts).

Syntax
    IRR# ( valuearray# ( ),  valuecount%,  guess#,  status%)


Remarks
The internal rate of return is the interest rate received for an investment
that consists of payments and receipts that occur at regular intervals.

The  IRR# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    valuearray#( )                         An array of cash-flow values. The
                                        argument must contain at least one
                                        negative value (a payment) and one
                                        positive value (a receipt).

    valuecount%                            The total number of items in the
                                        cash-flow array.

    guess#                                 A value you guess is close to the
                                        result of  IRR#. In most cases you
                                        can assume  guess# to be 0.1 (10
                                        percent). However, if  IRR#
                                        returns a status of 1 (failure),
                                        or if the result is not close to
                                        what you expected, try different
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        what you expected, try different
                                        values of  guess#.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.



    ■    MIRR# gives the internal rate of return where positive and negative
        cash flows are financed at different rates.

    ■    NPV# gives the net present value of an investment based on cash flows
        that do not have to be constant.

    ■    Rate# gives the interest rate per period of an investment.


To use  IRR# in the QBX
environment, use the FINANCER.QLB Quick library. To use  IRR# outside of the
QBX environment, link your program with the appropriate FINANC xx.LIB file.
Depending on the compiler options you chose when you installed BASIC, one or
more of the following files will be available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode



The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    MIRR#,  NPV#,  Rate#




Minute& Function

Action
Takes a date/time serial number and returns the minute.

Syntax
    Minute& ( serial# )


Remarks
The  Minute& function returns an integer between 0 and 59, inclusive, that
represents the minute corresponding to the argument.

The argument  serial#  is a serial number that represents a date and/or
time. For more information, see the topic "Serial Numbers" in this section.

To use  Minute& in the QBX environment, use the DTFMTER.QLB Quick library.
To use  Minute& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Month&,  Now#,  Second&, Serial Numbers,  Weekday&,  Year&




MIRR# Function

Action
Returns the modified internal rate of return for a series of periodic cash
flows (payments and receipts).

Syntax
    MIRR# ( valuearray# ( ),  valuecount%,  fin-rate#,  reinv-rate#,
status%)


Remarks
The modified internal rate of return is the internal rate of return where
payments and receipts are financed at different rates.  MIRR# considers both
the cost of the investment ( fin-rate#) and the interest received on
reinvestment of cash ( reinv-rate#).

The  MIRR# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    valuearray# ( )                        An array of cash-flow values. The
                                        argument must contain at least one
                                        negative value (a payment) and one
                                        positive value (a receipt).

    valuecount%                            The total number of items in the
                                        cash-flow array.

    fin-rate#                              The interest rate paid as the cost
                                        of financing..
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        of financing..

    reinv-rate#                            The interest rate received on
                                        gains from cash reinvestment.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





The arguments  fin-rate# and  reinv-rate# are percentages expressed as
decimal values. For example, 12 percent is expressed as .12.

    MIRR# uses the order of values within the array to interpret the order of
payments and receipts. Be sure to enter your payment and receipt values in
the correct sequence.

Two other functions are related to  MIRR#:
    ■    IRR# returns the internal rate of return for an investment.
    ■    Rate# returns the interest rate per period of an annuity.


To use  MIRR# in the QBX environment, use the FINANCER.QLB
Quick library. To use  MIRR# outside of the QBX environment,
link your program with the appropriate FINANC xx.LIB file.

Depending on the compiler options you chose when you installed BASIC,
one or more of the following files will be available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
IRR#,  Rate#



Month& Function

Action
Takes a date/time serial number and returns the month.

Syntax
    Month& ( serial# )


Remarks
The  Month& function returns an integer between 1 and 12, inclusive, that
represents the month corresponding to the argument.

The argument  serial# is a serial number that represents a date and/or time.
For more information, see the topic "Serial Numbers" in this section.

To use  Month& in the QBX environment, use the DTFMTER.QLB Quick library. To
use  Month& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Minute&,  Now#,  Second&, Serial Numbers,  Weekday&,  Year&



Now# Function

Action
Returns a serial number that represents the current date and time according
to your computer's system date and time.

Syntax
    Now#


Remarks
For more information, see the topic "Serial Numbers" in this section.

To use  Now# in the QBX environment, use the DTFMTER.QLB Quick library. To
use  Now# outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Minute&,  Month&,  Second&, Serial Numbers,  Weekday&,
Year&


Example

The following example examines the current date and time information
contained by the operating system and displays a formatted version of the
date and time as returned by the  Now# function.

To run this example, you must link it with the appropriate DTFMT xx.LIB file
or use the DTFMTER.QLB Quick library. The following include files must also
be present.

' $INCLUDE: 'DATIM.BI'
' $INCLUDE: 'FORMAT.BI'

CLS
PRINT "Today's date is "; FormatD$(Now#, "dd-mmm-yy"); "."
PRINT "The current time is "; FormatD$(Now#, "hh:mm:ss AM/PM"); "."

Output

Today's date is 02-May-1989.
The current time is 2:22:14 PM.




NPer# Function

Action
Returns the number of periods for an annuity based on periodic, constant
payments and a constant interest rate.

Syntax
    NPer# ( rate#,  pmt#,  pv#,  fv#,  type%,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The NP er# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10 divided by
                                        12, or .0083.

    pmt#                                   The payment to be made each period.
                                        It  usually contains principal and
                                        interest and does not change over
                                        the life of the annuity.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        the monthly car payments you will
                                        make.

    fv#                                    The future value or the cash
                                        balance you want to be attained
                                        sometime in the future after the
                                        last payment is made. The future
                                        value of a loan, for example is
                                        zero. As another example, if you
                                        think you will need $50,000 in 18
                                        years to pay for your child's
                                        education, the future value is
                                        $50,000.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due ar the end of the
                                        period; use 1 if at the beginning
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        period; use 1 if at the beginning
                                        of the period.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





Note
For all arguments, cash you pay out, such as deposits to savings, is
represented by negative numbers; cash you receive, such as dividend checks,
is represented by positive numbers.


A number of other functions are related to  NPer#:
    ■    FV# returns the the future value of an annuity.
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    Pmt# returns the periodic total payment for an annuity.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.
    ■    PV# returns the present value of an annuity.
    ■    Rate# returns the interest rate per period of an annuity.


To use  NPer# in the QBX environment, use the FINANCER.QLB Quick library. To
use  NPer# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    FV#,  IPmt#,  Pmt#,  PPmt#,  PV#,  Rate#



NPV# Function

Action
Returns the net present value of an investment based on a series of periodic
cash flows (payments and receipts) and a discount rate.

Syntax
    NPV# ( rate#,  valuearray#( ),  valuecount%,  status%)


Remarks
The net present value of an investment is today's value of a future series
of payments and receipts.

The  NPV# function uses the following arguments:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Argument                              Description
────────────────────────────────────────────────────────────────────────────
    rate#                                The discount rate over the length of
                                        the period, expressed as a decimal.

Argument                              Description
────────────────────────────────────────────────────────────────────────────

    valuearray#( )                       An array of cash-flow values. The
                                        argument must contain at least one
                                        negative value (a payment) and one
                                        positive value (a receipt).

    valuecount%                          The total number of items in the
                                        cash-flow array.

    status%                              A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





Several other functions are related to  NPV#:
    ■    FV# returns the the future value of an annuity.
    ■    IRR# returns the internal rate of return for an investment.
    ■    PV# returns the present value of an annuity.


To use  NPV# in the QBX environment, use the FINANCER.QLB Quick library. To
use  NPV# outside of the QBX environment, link your program with the
appropriate FINANCxx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    FV#,  IRR#,  PV#



Pmt# Function

Action
Returns the payment for an annuity based on periodic, constant payments and
a constant interest rate.

Syntax
    Pmt# ( rate#,  nper#,  pv#,  fv#,  type%,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The  Pmt# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10 divided by
                                        12, or .0083.

    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
                                        make.

    fv#                                    The future value or the cash
                                        balance you want to be attained
                                        sometime in the future after the
                                        last payment is made. The future
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        last payment is made. The future
                                        value of a loan, for example is
                                        zero. As another example, if you
                                        think you will need $50,000 in 18
                                        years to pay for your child's
                                        education, the future value is
                                        $50,000.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





The arguments  rate# and  nper# must use consistent units. For example:

Note
For all arguments, cash you pay out, such as deposits to savings, is
represented by negative numbers; cash you receive, such as dividend checks,
is represented by positive numbers.

A number of other functions are related to  Pmt#:
    ■    FV# returns the the future value of an annuity.
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    NPer# returns the number of periods (payments) for an annuity.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.
    ■    PV# returns the present value of an annuity.
    ■    Rate# returns the interest rate per period of an annuity.


To use  Pmt# in the QBX environment, use the FINANCER.QLB Quick library. To
use  Pmt# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    FV#,  IPmt#,  NPer#,  PPmt#,  PV#,  Rate#



PPmt# Function

Action
Returns payment on the principal for a given period of an annuity based on
periodic, constant payments and a constant interest rate.

Syntax
    PPmt# ( rate#,  per#,  nper#,  pv#,  fv#,  type%,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The  PPmt# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10 divided by
                                        12, or .0083.

    per#                                   The payment period; must be
                                        between 1 and  nper#, inclusive.
                                        If it is not in that range, BASIC
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        If it is not in that range, BASIC
                                        generates the error message
                                        Overflow.

    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
                                        make.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        make.

    fv#                                    The future value or the cash
                                        balance you want to be attained
                                        sometime in the future after the
                                        last payment is made. The future
                                        value of a loan, for example is
                                        zero. As another example, if you
                                        think you will need $50,000 in 18
                                        years to pay for your child's
                                        education, the future value is
                                        $50,000.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        beginning of the period.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





The arguments  rate# and  nper# must use consistent units.


Note

For all arguments, cash you pay out, such as deposits to savings, is
represented by negative numbers; cash you receive, such as dividend checks,
is represented by positive numbers.

A number of other functions are related to  PPmt#:
    ■    FV# returns the the future value of an annuity.
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    NPer# returns the number of periods (payments) for an annuity.
    ■    Pmt# returns the periodic total payment for an annuity.
    ■    PV# returns the present value of an annuity.
    ■    Rate# returns the interest rate per period of an annuity.


To use  PPmt# in the QBX environment, use the FINANCER.QLB Quick library. To
use  PPmt# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    FV#,  IPmt#,  NPer#,  Pmt#,  PV#,  Rate#



PV# Function

Action
Returns the present value, or lump sum, that a series of payments to be paid
in the future is worth now.

Syntax
    PV# ( rate#,  nper#,  pmt#,  fv#,  type%,  status%)


Remarks
The  PV# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    rate#                                  The interest rate per period. For
                                        example, if you get a car loan at
                                        an annual rate of 10 percent and
                                        make monthly payments, the rate
                                        per period would be .10 divided by
                                        12, or .0083.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        12, or .0083.

    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pmt#                                   The payment to be made each period.
                                        It usually contains principal and
                                        interest and does not change over
                                        the life of the annuity.

    fv#                                    The future value or the cash
                                        balance you want to be attained
                                        sometime in the future after the
                                        last payment is made. The future
                                        value of a loan, for example is
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        value of a loan, for example is
                                        zero. As another example, if you
                                        think you will need $50,000 in 18
                                        years to pay for your child's
                                        education, the future value is
                                        $50,000.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        successful, and 1 if it was not.




Two other functions are related to  PV#:
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.


To use  PV# in the QBX environment, use the FINANCER.QLB Quick library. To
use  PV# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    IPmt#,  PPmt#




Rate# Function

Action
Returns the interest rate per period for an annuity.

Syntax
    Rate# ( nper#,  mt#,  pv#,  fv#,  type%,  guess#,  status%)


Remarks
An annuity is a series of constant cash payments made over a continuous
period of time. An annuity can be a loan (such as a home mortgage) or an
investment (such as a monthly savings plan).

The  Rate# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    nper#                                  The number of payment periods in
                                        the annuity. For example, if you
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        the annuity. For example, if you
                                        get a four-year car loan and make
                                        monthly payments, your loan has a
                                        total number of 4 times 12, or 48,
                                        payment periods.

    pmt#                                   The payment to be made each period.
                                        It usually contains principal and
                                        interest and does not change over
                                        the life of the annuity.

    pv#                                    The present value or a lump sum
                                        that a series of payments to be
                                        paid in the future is worth now.
                                        For example, when you borrow money
                                        to buy a car, the loan amount is
                                        the present value to the lender of
                                        the monthly car payments you will
                                        make.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        make.

    fv#                                    The future value or the cash
                                        balance you want to be attained
                                        sometime in the future after the
                                        last payment is made. The future
                                        value of a loan, for example is
                                        zero. As another example, if you
                                        think you will need $50,000 in 18
                                        years to pay for your child's
                                        education, the future value is
                                        $50,000.

    type%                                  An integer expression that
                                        indicates when payments are due.
                                        Use 0 as the value for  type% if
                                        payments are due at the end of the
                                        period; use 1 if due at the
                                        beginning of the period.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        beginning of the period.

    guess#                                 A value you guess is close to the
                                        result of  Rate#.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





Note%
For all arguments, cash you pay out, such as deposits to savings, is
represented by negative numbers; cash you receive, such as dividend checks,
is represented by positive numbers.

    Rate# is calculated by iteration. Starting with
the value of  guess#,  Rate# cycles
through the calculation until the result is accurate within .00001 percent.
If after 20 tries it can't find a result that works,  Rate
# returns a status of 1.  In most cases you can assume the
    guess# argument to be 0.1 (10 percent). However, if Rate%# returns a status


A number of other functions are related to  Rate#:
    ■    FV# returns the the future value of an annuity.
    ■    IPmt# returns the interest payment for an annuity for a given period.
    ■    NPer# returns the number of periods (payments) for an annuity.
    ■    Pmt# returns the periodic total payment for an annuity.
    ■    PPmt# returns the principal payment for an annuity for a given
        period.
    ■    PV# returns the present value of an annuity.


To use  Rate# in the QBX environment, use the FINANCER.QLB Quick library. To
use  Rate# outside of the QBX environment, link your program with the
appropriate FINANCxx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:


╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    FV#,  IPmt#,  NPer#,  Pmt#,  PPmt#,  PV#



Second& Function

Action
Takes a date/time serial number and returns the second.

Syntax
    Second& ( serial#)


Remarks
The  Second& function returns an integer between 0 and 59, inclusive, that
represents the second corresponding to the argument.

The argument serial#  is a serial number that represents a date and/or time.
For more information, see the topic "Serial Numbers" in this section.

To use  Second& in the QBX environment, use the DTFMTER.QLB Quick library.
To use  Second& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Minute&,  Month&,  Now#, Serial Numbers,  Weekday&,  Year&



Serial Numbers

A serial number is a date/time code used by BASIC to represent dates and
times between
                        Jan. 1, 1753 and Dec. 31, 2078.


Serial-Number Format
Numbers to the left of the decimal point represent the date; numbers to the
right of the decimal point represent the time. For example:

╓┌────────────────────────┌──────────────────────────────────────────────────╖
Serial number            Date and time represented
────────────────────────────────────────────────────────────────────────────
20323.25                 August 22, 1955  6:00 A.M.
Serial number            Date and time represented
────────────────────────────────────────────────────────────────────────────
20323.25                 August 22, 1955  6:00 A.M.
20324.25                 August 23, 1955  6:00 A.M.
367.5                    January 1, 1901  12:00 P.M.
367.75                   January 2, 1901  6:00 P.M.



A serial number with no fractional part represents a date only. A serial
number with only a fractional part represents a time only.

The date portion of the serial number (to the left of the decimal point) can
represent dates ranging from January 1, 1753, through December 31, 2078.
Dates before December 30, 1899 are represented by negative numbers; dates
after December 30, 1899 are represented by positive numbers:

╓┌───────────────────────────┌───────────────────────────────────────────────╖
Serial number               Date represented
────────────────────────────────────────────────────────────────────────────
-1                          December 29, 1899
Serial number               Date represented
────────────────────────────────────────────────────────────────────────────
-1                          December 29, 1899
    0                          December 30, 1899
    1                          December 31, 1899
    2                          January 1, 1900



The time portion of the serial number (to the right of the decimal point)
can represent times that range from 0 (12:00:00 A.M.) to .99999 (11:59:59
P.M. or 23:59:59).



SetFormatCC Routine

Action
Sets the country code for the  Format X $ functions.

Syntax
    SetFormatCC ( countrycode%)


Remarks
The argument  countrycode% is the international telephone dialing prefix for
the country chosen as the target audience when using the  Format X $
functions.

The only reason to use  SetFormatCC is to change what the  Format X $
functions expect as thousands-separator and decimal-point formatting
characters.

The default setting for the country code is the United States (1). If you
set the country code to France (33), the following statement would display
the number 1,000 (U.S.) as 1.000,00:

PRINT FormatD$ (1000, "#.##0,00")
The format you use with the  Format X $ functions must be compatible with
the current country code in order for formatted numbers to display properly.

If you set the country code to one of the following countries, the  Format X
$ functions expect alternative formatting characters: Austria, Belgium,
Brazil, Denmark, France, Germany, Italy, Netherlands, Norway, Spain, Sweden,
or Switzerland. Canada uses one country code for French Canada (2) and
another for the remainder of Canada (1).

To use  SetFormatCC in the QBX environment, use the DTFMTER.QLB Quick
library. To use  SetFormatCC outside of the QBX environment, link your
program with the appropriate DTFMT xx.LIB file. Depending on the compiler
options you chose when you installed BASIC, one or more of the following
files will be available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode




The FORMAT.BI header file contains the necessary function declarations for
using the formatting functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Format X $;  StringAddress Routine,  StringLength Routine (in Part 1).



SLN# Function

Action
Returns straight-line depreciation of an asset for a single period.

Syntax
    SLN# ( cost#,  salvage#,  life#,  status%)


Remarks
The  SLN# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    cost#                                  The initial cost of the asset.

    salvage#                               The value at the end of the useful
                                        life of the asset.

    life#                                  The useful life of the asset (or
                                        the number of periods over which
                                        the asset is being depreciated).

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.





To use  SLN# in the QBX environment, use the FINANCER.QLB Quick library. To
use  SLN# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode




The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    DDB#,  SYD#




SYD# Function

Action
Returns the sum-of-years' digits depreciation of an asset for a specified
period.

Syntax
    SYD# ( cost#,  salvage#,  life#,  period#,  status%)


Remarks
The  SYD# function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    cost#                                  The initial cost of the asset.

    salvage#                               The value at the end of the useful
                                        life of the asset.

    life#                                  The useful life of the asset (or
                                        the number of periods over which
                                        the asset is being depreciated).

    period#                                Period for which asset
                                        depreciation is desired.

    status%                                A BASIC variable that indicates
                                        whether calculation succeeded or
                                        failed. The value of the variable
                                        will be 0 if the calculation was
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        will be 0 if the calculation was
                                        successful, and 1 if it was not.




The arguments  life# and  period# must use the same units. For example, if
life# is given in months,  period# also must be given in months.

To use  SYD# in the QBX environment, use the FINANCER.QLB Quick library. To
use  SYD# outside of the QBX environment, link your program with the
appropriate FINANC xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
Filename          Compiler options
────────────────────────────────────────────────────────────────────────────
FINANCER.LIB      80x87 or emulator math; DOS or OS/2 real mode
FINANCAR.LIB      Alternate math; DOS or OS/2 real mode
FINANCEP.LIB      80x87 or emulator math; OS/2 protected mode
FINANCAP.LIB      Alternate math; OS/2 protected mode



The FINANC.BI header file contains the necessary function declarations for
using the financial functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    DDB#,  SLN#




TimeSerial# Function

Action
Returns a serial number that represents the time of the arguments.

Syntax
    TimeSerial# ( hour%,  minute%,  second%)


Remarks
The  TimeSerial# function uses the following arguments:

╓┌──────────┌────────────────────────────────────────────────────────────────╖
Argument   Description
────────────────────────────────────────────────────────────────────────────
    hour%     An hour between 0 (12:00 A.M.) and 23 (11:00 P.M.), inclusive.
    minute%   A minute between 0 and 59, inclusive.
    second%   A second between 0 and 59, inclusive.



You can use negative numbers as arguments, as long as the resulting serial
number is positive. For example, to find the serial number for the time 50
seconds before 2:00:02, you could use:

TimeSerial#(2,0,2-50)
For more information, see the topic "Serial Numbers" in this section.

To use  TimeSerial# in the QBX environment, use the DTFMTER.QLB Quick
library. To use  TimeSerial# outside of the QBX environment, link your
program with the appropriate DTFMT xx.LIB file. Depending on the compiler
options you chose when you installed BASIC, one or more of the following
files will be available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
"Creating and Using Quick Libraries" and "Using LINK and LIB" in the
Programmer's Guide.

See Also
    Hour&,  Minute&,  Now#,  Second&, Serial Numbers,  TimeValue#

Example
The following example calculates the time between now and midnight tonight.
The results of the calculations are shown as a total number of seconds, as a
combination of hours, minutes, and seconds, and also as a standard time
format. The time information is displayed using the  TimeValue#,
TimeSerial#,  Hour&,  Minute&, and  Second& functions.

To run this example, you must link it with the appropriate DTFMT xx.LIB file
or use the DTFMTER.QLB Quick library. The following include files must also
be present.

' $INCLUDE: 'DATIM.BI'
' $INCLUDE: 'FORMAT.BI'

' Get a time value for midnight tonight -1 second.
Midnight# = TimeValue#("23:59:59")

' Get a time value for right now.
Instant# = Now#

' Get the difference in hours, minutes, seconds.
HourDiff% = Hour&(Midnight#) - Hour&(Instant#)
MinuteDiff% = Minute&(Midnight#) - Minute&(Instant#)

' Add in the odd second between 23:59:59 and midnight.
SecondDiff% = Second&(Midnight#) - Second&(Instant#) + 1
' Adjust so that seconds and minutes are less than 60.
IF SecondDiff% = 60 THEN
MinuteDiff% = MinuteDiff% + 1
SecondDiff% = 0
END IF

IF MinuteDiff% = 60 THEN
HourDiff% = HourDiff% + 1
MinuteDiff% = 0
END IF

' Calculate seconds between now and midnight.
TotalMinDiff# = (HourDiff% * 60) + MinuteDiff%
TotalSecDiff# = (TotalMinDiff# * 60) + SecondDiff%
' Put the difference back into a standard time format.
TotalDiff# = TimeSerial#(HourDiff%, MinuteDiff%, SecondDiff%)
' Display results.
CLS
PRINT "There are a total of"; TotalSecDiff#; "seconds until midnight."
PRINT "That translates to"; HourDiff%; "hours,"; MinuteDiff%;
PRINT "minutes, and"; SecondDiff%; "seconds."
PRINT
PRINT "The difference can also be expressed in standard time notation:"
PRINT FormatD$(TotalDiff#, "hh:mm:ss")



TimeValue# Function

Action
Returns a serial number that represents the time of the argument.

Syntax
    TimeValue# ( time$)


Remarks
The argument  time$ is a time between 0:00:00 (12:00:00 A.M.) and 23:59:59
(11:59:59 P.M.), inclusive. Time can be entered as "2:24PM" or "14:24".

Any date information used in  time$ is ignored.

For more information, see the topic "Serial Numbers" in this section.

To use  TimeValue# in the QBX environment, use the DTFMTER.QLB Quick
library. To use  TimeValue# outside of the QBX environment, link your
program with the appropriate DTFMT xx.LIB file. Depending on the compiler
options you chose when you installed BASIC, one or more of the following
files will be available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Hour&,  Minute&,  Now#,  Second&, Serial Numbers,  TimeSerial#,  Year&



Weekday& Function

Action
Takes a date-time serial number and returns the day of the week.

Syntax
    Weekday& ( serial# )


Remarks
The  Weekday& function returns an integer between 1 (Sunday) and 7
(Saturday) that represents the day of the week corresponding to the
argument.

The argument  serial# is a serial number that represents a date and/or time.
For more information, see the topic "Serial Numbers" in this section.

To use  Weekday&  in the QBX environment, use the DTFMTER.QLB Quick library.
To use  Weekday& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Minute&,  Month&,  Now#,  Second&,  Year&



Year& Function

Action
Takes a date-time serial number and returns the year.

Syntax
    Year& ( serial# )


Remarks
The  Year& function returns an integer between 1753 and 2078, inclusive,
that represents the year corresponding to the argument.

The argument  serial# is a serial number that represents a date and/or time.
For more information, see the topic "Serial Numbers" in this section.

To use  Year& in the QBX environment, use the DTFMTER.QLB Quick library. To
use  Year& outside of the QBX environment, link your program with the
appropriate DTFMT xx.LIB file. Depending on the compiler options you chose
when you installed BASIC, one or more of the following files will be
available:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Filename         Compiler options
────────────────────────────────────────────────────────────────────────────
DTFMTER.LIB      80x87 or emulator math; DOS or OS/2 real mode
DTFMTAR.LIB      Alternate math; DOS or OS/2 real mode
DTFMTEP.LIB      80x87 or emulator math; OS/2 protected mode
DTFMTAP.LIB      Alternate math; OS/2 protected mode



The DATIM.BI header file contains the necessary function declarations for
using the date/time functions. For more information on using libraries, see
Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick
Libraries" in the  Programmer's Guide.

See Also
    Day&,  Hour&,  Minute&,  Month&,  Now#,  Second&, Serial Numbers

a
♀Toolbox Summary Tables



The following groups are summarized here:
*    Matrix Math Function procedures
*    Presentation Graphics Sub and Function procedures
*    Font SUB and Function procedures
*    User Interface SUB and Function procedures
-    Menu
-    Window
-    Mouse
-    General


Matrix Math Function Procedures

*    I is integer.
*    L is long integer.
*    S is single-precision floating point.
*    D is double-precision floating point.
*    C is currency.


Addition
--------
MatAddI%
MatAddL%
MatAddS%
MatAddD%
MatAddC%
Finds the sum of two matrixes whose row and column dimensions are identical.


Subtraction
-----------
MatSubI%
MatSubL%
MatSubS%
MatSubD%
MatSubC%
Finds the difference between two matrixes whose row and column dimensions
are identical.


Multiplication
--------------
MatMultI%
MatMultL%
MatMultS%
MatMultD%
MatMultC%
Finds the product of two matrixes where the first matrix has the same number
of columns as the second matrix has rows.


Determinant
-----------
MatDetI%
MatDetL%
MatDetS%
MatDetD%
MatDetC%
Finds the determinant of a square matrix.


Inverse
-------
MatInvS%
MatInvD%
MatInvC%
Finds the multiplicative inverse of a square matrix, if one exists; that is,
if the determinant is not equal
to 0.


Gaussian elimination
--------------------
MatSEqnS%
MatSEqnD%
MatSEqnC%
Uses Gaussian elimination to solve, if a solution exists, a system of linear
equations contained in a square matrix and a vector.


Presentation Graphics Sub and FUNCTION Procedures


Chart
Draws a bar, column, or line chart.

ChartMS
Draws a multi-series bar, column, or line chart.

ChartPie
Draws a pie chart.

ChartScatter
Draws a single-series scatter chart.

ChartScatterMS
Draws a multi-series scatter chart.

ChartScreen
Sets the screen mode to be used when displaying a chart.

DefaultChart
Initializes a ChartEnvironment structure for the specified chart type and
style.

GetPaletteDef
Gets a copy of the current internal chart palette.

GetPattern$
Returns a string that can be used by BASIC as a pixel pattern

LabelChartH
Prints a user-defined string horizontally on a chart.

LabelChartV
Prints a user-defined string vertically on a chart.

MakeChartPattern$
Changes fill pattern and color.
ResetPaletteDef
Builds the internal chart palette for the current screen mode using the
current style pool.

SetPaletteDef
Replaces the internal chart palette with user-defined values.



Font SUB and FUNCTION Procedures


GetFontInfo
Gets font information for the currently selected font.

GetGTextLen%
Returns the pixel length of a string based on the currently selected font.

GetMaxFonts
Gets the maximum number of fonts that can be registered and loaded.

GetRFontInfo
Gets font information for the currently registered fonts.

GetTotalFonts
Gets the number of fonts currently registered and loaded.

LoadFont%
Loads the font information from the .fon files or memory for the specified
fonts and returns the number of fonts actually loaded.

OutGText%
Outputs text in the currently selected font using the current graphics color
at the current graphics cursor position. Returns pixel length of the
character output.

RegisterFonts%
Registers font-header information from a specified .fon file and returns the
number of fonts registered.

RegisterMemFont%
Registers the font-header information for fonts that reside in memory and
returns the number of fonts registered.

SelectFont
Designates a loaded font as the active font.

SetGCharSet
Sets the character set used in subsequent graphics characters.

SetGTextColor
Sets the character color used in subsequent graphic characters.

SetGTextDir
Sets the horizontal or vertical orientation of graphics characters.

SetMaxFonts
Sets the maximum number of fonts that are allowed to be registered and
loaded.

UnRegisterFonts
Removes registered fonts from memory.



User Interface Procedures

The following tables summarize the procedures that make up the User
Interface toolbox. These functions are provided in four separate toolbox
files. The files are:
*    MENU.BAS
*    WINDOW.BAS
*    MOUSE.BAS
*    GENERAL.BAS

Each table lists the type of operation performed by the procedure, the
procedure name, and the result of the procedure. See the detailed
description of each of the procedures later in this part for more
information about how to use them in your programs.

Menu SUB and FUNCTION Procedures


Initialize variables and preprocess menus
-----------------------------------------
MenuInit
Initializes global menu arrays and mouse driver servicing routines.

MenuPreProcess
Performs calculations and builds indexes so menus run faster.


Define and display menus
------------------------
MenuColor
Assigns color to various components of the menus.

MenuSet
Defines the structure of menus and the quick keys associated with each menu
selection.

MenuShow
Draws the menu across the top line of the screen.


Change the state of menus or menu items
---------------------------------------
MenuItemToggle
Toggles the state of a menu item between enabled but not selected and
enabled and selected.

MenuSetState
Explicitly assigns the state of a menu item. States are: empty (menu item
does not appear on the menu); enabled but not selected; enabled and
selected; and disabled.


Process menu events
-------------------
MenuCheck
Provides a numeric indication of what menu selection, if any, was made
following a menu or shortcut-key event.

MenuEvent$
Monitors user input to determine if a menu choice is being made with either
the mouse or the keyboard.

MenuInkey$
Performs a BASIC INKEY$ function as well as a MenuEvent$ and
ShortCutKeyEvent$ function.

MenuOff
Turns off menu and shortcut-key event processing.

MenuOn
Turns on menu and shortcut-key event processing that was previously turned
off.


Shortcut keys
-------------
ShortCutKeyDelete$
Revokes any previous shortcut-key definitions associated with a particular
menu item.

ShortCutKeyEvent$
Polls user input to determine if a menu item was selected using a shortcut
key.

ShortCutKeySet
Assign shortcut keys to individual menu items.


Window SUB and FUNCTION Procedures



Initialize window variables
---------------------------
WindowInit
Initializes global variables for all procedures in WINDOW.BAS.


Define windows
--------------
WindowBox
Draws a box with a single-line border at a designated position within the
current window.

WindowClose
Closes a specified window.

WindowColor
Changes color characteristics of the current window.

WindowOpen
Defines the size, position, color, and other characteristics of individual
windows.

WindowSetCurrent
Makes the specified window the current window.


Get information about windows
-----------------------------
WindowCols
Returns the number of columns in the current window.

WindowCurrent
Returns the number of the current window handle.

WindowNext
Returns the number of the next available window handle.

WindowRows
Returns the number of rows in the current window.


Display text in windows
-----------------------
WindowCls
Clears all text from within a window.

WindowLine
Draws a horizontal line across a window at the row specified.

WindowLocate
Sets the row and column of the window text cursor to define the next
position where a character will be printed.

WindowPrint
Prints text in a window at the position established by WindowLocate.

WindowScroll
Scrolls text, in the current window, the number of lines specified.


Button actions
--------------
ButtonClose
Erases the specified button from the current window and deletes it from the
global arrays.

ButtonInquire
Returns a value that indicates the state of the specified button. Only used
with button types 1, 2, 3, 6, and 7.

ButtonOpen
Opens a button of a specified type and places it in the current window at
the specified window coordinates.

ButtonSetState
Sets the state of the specified button in the current window.

ButtonToggle
Toggles the state of the specified button between selected and not selected.


Edit field actions
------------------
EditFieldClose
Erases the specified edit field from the current window and deletes it from
the global arrays.

EditFieldInquire
Returns the string associated with the specified edit field.

EditFieldOpen
Opens an edit field and places it in the current window at specified
coordinates.

Miscellaneous actions
---------------------
Alert
Displays a window containing between one and three buttons that indicate
user choices. Returns a value that indicates the number of the button
selected by the user.

Dialog
Returns a value that indicates what type of button, edit field, or window
event occurred during window-event processing.

ListBox
Displays a window containing a list box, a scroll bar, an OK button, and a
Cancel button. Returns a value that indicates the number of the item
selected in the list box,
or 0 if Cancel is selected.

MaxScrollLength
Returns a value that indicates how many positions are available on a
specified scroll bar.



Mouse SUB Procedures


Initialize the mouse
--------------------
MouseDriver
Calls Interrupt 51 (33H) and passes parameters to the proper CPU registers.

MouseInit
Initializes mouse driver servicing routines.


Establish limits of mouse movement on the screen
------------------------------------------------
MouseBorder
Defines the area where the mouse can be used.


Manipulate the mouse
--------------------
MouseHide
Turns off display of the mouse cursor.

MousePoll
Polls the mouse driver to establish the position of the mouse cursor and the
status of mouse buttons.

MouseShow
Turns on display of the mouse cursor.


General SUB and FUNCTION Procedures


Accept and evaluate keyboard input
----------------------------------
AltToASCII$
Decodes extended key codes associated with the Alt key and returns an
individual ASCII character.

GetShiftState
Returns the status of one of eight possible shift states.


Manipulate screen areas
-----------------------
AttrBox
Changes color attributes of text within an area described by specified row
and column coordinates.

Box
Draws a box around a defined area using specified foreground and background
colors.

GetBackground
Saves an area of the screen into a named buffer.

PutBackground
Restores to specified coordinates a previously saved screen area from a
named buffer.

Scroll
Scrolls the defined area a specified number of lines.




Matrix Math Toolbox

This section describes the six FUNCTION procedures supported by the Matrix
Math toolbox:
*    MatAdd FUNCTION
*    MatSub FUNCTION
*    MatMult FUNCTION
*    MatDet FUNCTION
*    MatInv FUNCTION
*    MatSEqn FUNCTION

Matrix Math is the name of a BASIC toolbox (MATB.BAS) included with
Microsoft BASIC. The toolbox contains a set of matrix-manipulation
procedures that perform math operations on two-dimensional matrixes. There
is a separate toolbox procedure for each supported numeric data type. Which
one to use depends on the data type of the elements in the matrix. The last
letter in the procedure name identifies the data type of the procedure, as
follows:


Letter    Numeric data type
I         Integer
S         Single precision floating point
C         Currency
L         Long integer
D         Double precision floating point


All numeric data types are supported by MatAdd, MatSub, MatMult, and MatDet.
Integer and long integer data types are not supported by MatInv and MatSEqn.

Each procedure returns a result code that indicates the success of the
operation, or, in the case of an error, the nature of the problem
encountered. The following result codes are defined:

Result code    Significance
    0            Normal completion. No error occurred.
- 1            Determinant for matrix is 0. No inverse of the input matrix
exists.
- 2            Matrix not square; doesn't have same number of rows as
columns.
- 3            Inside dimension not the same. The number of columns in
matrix1 is not the same as the number of rows in matrix2.
- 4            Matrixes not of the same dimension. That is, there are not
the same number of rows in matrix1 that are in matrix2 or there are not the
same number of columns in matrix1 that are in matrix2.
- 5            Dimensions for the solution matrix not correctly declared.
The matrix does not have the proper number of rows and columns.



Note
----
By default all arrays are zero based; that is, the lower bound of an array
is 0. You may wish to use OPTION BASE 1 so that the numbers in the DIM
statement accurately reflect the number of row and column elements in your
matrixes.



Following is a description of the FUNCTION procedures in the Matrix Math
toolbox.



MatAdd FUNCTION

MatAddI%
MatAddL%
MatAddS%
MatAddD%
MatAddC%

Syntax
errcode% = MatAddtype%(matrix1( ), matrix2( ))

Remarks
MatAddtype% performs matrix addition of two matrixes that are the same in
both row (m) and column (n) dimensions. The input matrixes contain values
whose data type is defined by the last letter in the procedure name (I, L,
S, D, or C). The sum is returned in matrix1( ), replacing any previous
values. The solution matrix contains values of the same data type as the
input matrixes. Once the procedure has been performed, the contents of
matrix2( ) are meaningless.

MatAddtype% uses the following arguments:

matrix1( )
----------
A matrix consisting of m x n dimensions.

matrix2( )
----------
A matrix consisting of m x n dimensions.


A result code indicates the success or failure of the FUNCTION procedure.
Possibilities are:
    0             Normal completion. No error occurred.
-4             Matrixes not of the same dimension. That is, there are not
the same number of rows in matrix1 as there are in matrix2 or there are not
the same number of columns in matrix1 as in matrix2.


MatSub FUNCTION

MatSubI%
MatSubL%
MatSubS%
MatSubD%
MatSubC%

Syntax
errcode% = MatSubtype%(matrix1( ), matrix2( ))

Remarks
The MatSubtype% procedure performs matrix subtraction of two matrixes whose
row (m) and column (n) dimensions are identical. The input matrixes contain
values whose data type is defined by the last letter in the procedure name
(I, L, S, D, or C). The first matrix is subtracted from the second and the
difference is returned in matrix1( ), replacing any previous values. The
solution matrix contains values of the same data type as the input matrixes.
Once the procedure has been performed, the contents of matrix2( ) are
meaningless.


MatSubtype% uses the following arguments:

matrix1( )
----------
A matrix consisting of m x n dimensions.

matrix2( )
----------
A matrix consisting of m x n dimensions.


A result code is returned that indicates the success or failure of the
FUNCTION procedure. Possible result codes are:
    0    Normal completion. No error occurred.
- 4   Matrixes not of the same dimension. That is, there are not the same
number of rows in matrix1 as there are in matrix2 or there are not the same
number of columns in matrix1 as in matrix2.



MatMult FUNCTION

MatMultI%
MatMultL%
MatMultS%
MatMultD%
MatMultC%

Syntax
errcode% = MatMulttype%(matrix1( ), matrix2( ), matrix3( ))

Remarks
The MatMulttype% procedure performs matrix multiplication of two matrixes.
The first matrix must have the same number of columns (n in an m x n matrix)
as the number of rows in the second matrix (n in an n x k matrix). The input
matrixes contain values whose data type is defined by the last letter in the
procedure name (I, L, S, D, or C). The first matrix is multiplied by the
second and the product is returned in matrix3( ). The solution matrix
contains values of the same data type as the input matrixes. Once the
procedure has been performed, the contents of the input matrixes are
meaningless.

MatMulttype% uses the following arguments:

matrix1( )
----------
A matrix consisting of m x n dimensions.

matrix2( )
----------
A matrix consisting of n x k dimensions.

matrix3( )
----------
Solution matrix consisting of m x k dimensions.


A result code is returned that indicates the success or failure of the
FUNCTION procedure. Possible result codes are:
    0   Normal completion. No error occurred.
- 3  Inside dimension not the same. The number of columns in matrix1 is not
the same as the number of rows in matrix2.
- 5  Dimensions for the solution matrix not correctly declared. The matrix
does not have the proper number of rows and columns.


Note
----
Matrix division is performed using the MatInvtype% procedure to multiply one
matrix by the inverse of the second; that is, A/B = A * Inverse(B).



MatDet FUNCTION

MatDetI%
MatDetL%
MatDetS%
MatDetD%
MatDetC%

Syntax
errcode% = MatDettype%(matrix ( ), determinant)

Remarks
The MatDettype% procedure finds the determinant of a square matrix; that is,
a matrix that has the same number of rows and columns (n x n). The input
matrix contains values whose data type is defined by the last letter in the
procedure name (I, L, S, D, or C). The resulting determinant, of the same
data type as the input matrix values, is placed in determinant. After the
procedure is performed, the contents of matrix( ) are meaningless.

MatDettype% uses the following arguments:

matrix ( )
----------
A matrix consisting of n x n dimensions.

determinant
-----------
The determinant for matrix ( ).


A result code indicates the success or failure of the FUNCTION procedure.
Possibilities are:
    0   Normal completion. No error occurred.
- 2  Matrix not square. The matrix does not have the same number of rows as
columns.




MatInv FUNCTION

MatInvS%
MatInvD%
MatInvC%

Syntax
errcode% = MatInvtype%(matrix ( ))

Remarks
The MatInvtype% procedure finds the multiplicative inverse of a square
matrix; that is, a matrix that has the same number of rows and columns (n x
n). The input matrix contains values whose data type is defined by the last
letter in the procedure name (S, D, or C). The resulting inverse matrix, of
the same data type as the input matrix values, is returned in matrix( ),
replacing any previous values.

The argument matrix ( ) is a matrix consisting of n x n dimensions.
A result code indicates the success or failure of the FUNCTION procedure.
Possibilities are:
    0   Normal completion. No error occurred.
- 1  The determinant for the matrix is 0. No inverse of the input matrix
exists.
- 2  Matrix not square. The matrix does not have the same number of rows as
columns.


Note
----
Matrix division is performed using the MatInvtype% procedure to multiply one
matrix by the inverse of the second, that is, A/B = A * Inverse(B).



MatSEqn FUNCTION

MatSEqnS%
MatSEqnD%
MatSEqnC%

Syntax
errcode% = MatSEqntype%(matrix1( ), matrix2( ))

Remarks
The MatSEqntype% procedure solves a system of linear equations contained in
a square matrix; that is, a matrix that has the same number of rows and
columns (n x n). Gaussian elimination is used to solve the equations. The
input matrix contains values whose data type is defined by the last letter
in the procedure name (S, D, or C). The first matrix is the square input
matrix that contains the coefficients for a system of simultaneous
equations. The second matrix, matrix2( ), is the space where the solution is
returned. The solution space is an n x 1 matrix. The solution matrix
contains values of the same data type as the input matrix. Once the
procedure has been performed, the identity matrix is in matrix1( ).

MatSEqntype% uses the following arguments:

matrix1( )
----------
A matrix consisting of n x n dimensions.

matrix2( )
----------
Solution array consisting of 1 x n dimensions.


A result code is returned that indicates the success or failure of the
FUNCTION procedure. Possible result codes are:
    0   Normal completion. No error occurred.
- 1  Determinant for matrix is 0. No inverse of the input matrix exists.
- 2  Matrix not square. The matrix does not have the same number of rows as
columns.
- 3  Inside dimension not the same. The number of columns in matrix1 is not
the same as the number of rows in matrix2.



Presentation Graphics Toolbox


The first part of this section describes the SUB and FUNCTION procedures
that are supported by the Presentation Graphics toolbox. The second part
describes the SUB and FUNCTION procedures that are supported by the Fonts
toolbox. The Fonts toolbox can be used with the Presentation Graphics
toolbox or independently to draw graphics text.

The Presentation Graphics toolbox (CHRTB.BAS), included with the BASIC 7.0
Compiler, contains a set of routines for defining, analyzing, and printing
charts on the screen.

There are five kinds of charts, each available in two styles as shown here:

Style    Bar        Column    Line            Scatter        Pie

1        Plain      Plain     Lines and       Lines and      Percent
                                    points         points         displayed
2        Stacked    Stacked   Points only     Points only    No percent

To use the toolbox, you first must declare the dimensions for a variable as
the user-defined type ChartEnvironment. The definition for this type is
found in the CHRTB.BI header file. This file also contains definitions for
constants that can be used as arguments to the procedures described in this
section. Using these constants in place of hand-coded numerics will make
your program cleaner and easier to debug.

Presentation Graphics Error Codes
If an error occurs during the execution of a presentation graphics
procedure, the variable ChartErr will contain a non-zero value.
For non-BASIC errors, the error numbers can be tested using numerics or
constants as defined in the CHRTB.BI header file. The meaning of a non-BASIC
error:

Number    Constant name      Type of error

15        cBadLogBase        LogBase <= 0
20        cBadScaleFactor    ScaleFactor = 0
25        cBadScreen         Invalid screen mode
30        cBadStyle          Invalid chart style
105       cBadDataWindow     Data window calculated
                                    too small
110       cBadLegendWindow   Legend-window coordinates
                                    invalid
135       cBadType           Invalid chart type
155       cTooFewSeries      Too few series
                                    (first% > last%)1
160       cTooSmallN         No data in series (n% = 0)2
165       cBadPalette        Palette not dimensioned
                                    correctly
170       cPalettesNotSet    SetPaletteDef procedure hasn't
                                    been used
175       cNoFontSpace       No more room for new fonts


Numbers greater than 100 are fatal errors and will cause charting routines
to exit.
If BASIC generates an error, the value of ChartErr is equal to 200 plus the
BASIC error number. (See Appendix D, "Error Messages" for a complete list of
BASIC error messages.)



Chart Sub

Action
Draws bar, column, and line charts.


Syntax
Chart env, cat$(), value!(), n%

Remarks
The Chart procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

cat$()
------
A one-dimensional string array of category names.

value!()
--------
A one-dimensional single-precision array that contains the
chart data.

n%
--
An integer that contains the number of data items in value!().


The value!() and cat$() arrays must have a lower bound of 1.
The AnalyzeChart routine uses the same arguments as Chart. AnalyzeChart
analyzes and defines parameters in the chart environment based on the input
data, but it does not print a chart on the screen.


ChartMS Sub

Action
Draws multi-series bar, column, and line charts.


Syntax
ChartMS env, cat$(), value!(), n%, first%, last%, serieslabel$()

Remarks
The ChartMS procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

cat$()
------
A one-dimensional string array of category labels.

value!()
--------
A two-dimensional single-precision array of values that contains multiple
series of data.

n%
--
An integer that contains the number of data items in each series to be
charted.

first%
------
An integer that indicates the first series in array value!() to be charted.

last%
-----
An integer that indicates the last series in array value!() to be charted.

serieslabel$()
--------------
A one-dimensional string array that contains labels for the different data
series.


Dimensions for the value!() and serieslabel$() arrays are declared as
follows:

DIM Val!( 1 to n%, first% to last%)
DIM serieslabel$( first% to last%)

To chart all series, set first% to 1 and last% to the last series number in
array value!(). To chart several contiguous series, set first% to the lowest
series number and last% to the highest series number desired.
An analysis routine called AnalyzeChartMS (included in the Presentation
Graphics toolbox) uses the same arguments as ChartMS. AnalyzeChartMS
analyzes and defines parameters in the chart environment based on the input
data, but it does not print a chart on the screen.


ChartPie Sub

Action
Draws bar, column, and line charts.


Syntax
ChartPie env, cat$(), value!(), expl%(), n%

Remarks
The ChartPie procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

cat$()
------
A one-dimensional string array of category names.

value!()
--------
A one-dimensional single-precision array that contains the
chart data.

expl%()
-------
A one-dimensional integer array containing flags that determine whether each
element of the pie chart is exploded. If the value of an expl%() array
element is nonzero, that slice of the pie chart is exploded. If the array
element is zero, the slice is not exploded.

n%
--
An integer that contains the number of data items in value!().


The value!(), cat$(), and expl%() arrays must have a lower bound of 1.
An analysis routine called AnalyzePie (included in the Presentation Graphics
toolbox) uses the same arguments as ChartPie. AnalyzePie analyzes and
defines parameters in the chart environment based on the input data, but it
does not print a chart on the screen.



ChartScatter Sub

Action
Draws single-series scatter charts.


Syntax
ChartScatter env, valx!(), valy!(), n%

Remarks
The ChartScatter procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

valx!()
-------
A one-dimensional single-precision array of values for the x axis.

valy!()
-------
A one-dimensional single-precision array of values for the y axis.

n%
--
An integer that contains the number of data items to be charted.


The valx!() and valy!() arrays must have a lower bound of 1.
An analysis routine called AnalyzeScatter (included in the Presentation
Graphics toolbox) uses the same arguments as ChartScatter. AnalyzeScatter
analyzes and defines parameters in the chart environment based on the input
data, but it does not print a chart on the screen.



ChartScatterMS Sub

Action
Draws multi-series scatter charts.


Syntax
ChartScatterMS env, valx!(), valy!(), n%, first%, last%, serieslabel$()

Remarks
The ChartScatterMS procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

valx!()
-------
A two-dimensional single-precision array of values for multiple series of
data for the x axis.

valy!()
-------
A two-dimensional single-precision array of values for multiple series of
data for the y axis.

n%
--
An integer that contains the number of data items to be charted.

first%
------
An integer that indicates the first series to be charted.

last%
-----
An integer that indicates the last series to be charted.

serieslabel$()
--------------
A one-dimensional string array that contains labels for the different data
series.


Dimensions for the valx!(), valy!() and serieslabel$() arrays are declared
as follows:

DIM valx!( 1 to n%, first% to last%)
DIM valy!( 1 to n%, first% to last%)
DIM serieslabel$( first% to last%)

To chart all series, set first% to 1 and last% to the last series number in
array value!(). To chart several contiguous series, set first% to lowest
series number and last% to the highest series number desired.

An analysis routine called AnalyzeScatterMS (included in the Presentation
Graphics toolbox) uses the same arguments as ChartScatterMS.
AnalyzeScatterMS analyzes and defines parameters in the chart environment
based on the input data, but it does not print a chart on the screen.



ChartScreen Sub

Action
Sets the screen mode to be used when displaying a chart.


Syntax
ChartScreen n%

Remarks
The argument n% is an integer that contains a valid screen-mode number.
This procedure must be used to set the screen mode instead of the standard
BASIC SCREEN statement.
If an invalid screen mode is used, the variable ChartErr will contain the
number 25.


See Also:  SCREEN Statement




DefaultChart Sub

Action
Initializes the elements of the variable type ChartEnvironment for the
specified chart type and style.


Syntax
DefaultChart env, type%, style%

Remarks
The DefaultChart procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

type%
-----
An integer that defines the type of chart (1-5).

style%
------
An integer that defines the style of the chart (1-2).


The variable type% can use either numeric data or constants found in the
CHRTB.BI file to define the chart as shown in the following table:

Value    Constant    Type of chart

1        cBar        Bar
2        cColumn     Column
3        cLine       Line
4        cScatter    Scatter
5        cPie        Pie

The value of the variable style% determines the style of the chart as shown
here:

Value   Bar      Column    Line             Scatter          Pie

1       Plain    Plain     Lines & points   Lines & points   Percent
2       Stacked  Stacked   Points only      Points only      No percent

For program clarity, the following constants (found in the CHRTB.BI file)
should be used in place of numeric arguments:

Numeric argument    Equivalent constant

1                   cPlain, cLines, cPercent
2                   cStacked, cNoLines, cNoPercent



GetPaletteDef Sub

Action
Gets a copy of the current internal chart palette.


Syntax
GetPaletteDef palc%(), pals%(), palp$(), palch%(), palb%()

Remarks
The GetPaletteDef procedure uses the following arguments:

palc%()
-------
A one-dimensional integer array of color numbers corresponding to the
palette entries.

pals%()
-------
A one-dimensional integer array of line styles corresponding to the palette
entries.

palp$()
-------
A one-dimensional string array of fill patterns corresponding to the palette
entries.

palch%()
--------
A one-dimensional integer array of plot-character numbers corresponding to
the palette entries.

palb%()
-------
A one-dimensional integer array of line styles used for drawing window
borders and grid lines.


Dimensions for each array should be declared from 0 to cPalLen, a constant
found in the CHRTB.BI header file. Note that all palette arrays have a lower
bound of 0 (not 1, which is used for data and category-string arrays).


For more information on fill patterns, see the entries for PAINT and PALETTE
in Part 1, "Language Reference."



GetPattern$ FUNCTION

Action
Returns a string that can be used by BASIC as a pixel pattern.


Syntax
GetPattern$(bits%, patternNum%)

Remarks
The GetPattern$ and MakeChartPattern$ procedures are used in combination
with the GetPaletteDef and SetPaletteDef procedures to change the fill
pattern for pie, column, and bar charts. GetPattern$ constructs a value for
refPattern$, which is one of the arguments used by MakeChartPattern$.
The GetPattern$ procedure uses the following arguments:

Parameter      Description

bits%          Use 2 for screen mode 1, 8 for screen mode 13, and 1 for all
other screen modes.
patternNum%    An integer between one and cPalLen.

For more information, see the entry for the MakeChartPattern$ procedure
later in this section.


LabelChartH Sub

Action
Prints a user-defined string horizontally on a chart.


Syntax
LabelChartH env, x%, y%, font%, color%, string$

Remarks
The LabelChartH procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

x%
--
An integer that indicates the left position of the first character, in
pixels, relative to the chart window.

y%
--
An integer that indicates the bottom of the first character, in pixels,
relative to the chart window.

font%
-----
An integer that contains the number of the font (in currently loaded list)
to use.

color%
------
An integer that contains the color number in the chart palette used to
assign color to the string.

string$
-------
The text string to be printed.


The LabelChartH procedure must be called after calling the charting sub.
If an invalid font number (such as 0) is contained in font%, the first font
loaded is used. If no fonts are loaded, the default font contained in the
Presentation Graphics toolbox files is used.



LabelChartV Sub

Action
Prints a user-defined string vertically on a chart.


Syntax
LabelChartV env, x%, y%, font%, color%, string$

Remarks
The LabelChartV procedure uses the following arguments:

env
---
A variable dimensioned as type ChartEnvironment.

x%
--
An integer that indicates the left position of the first character, in
pixels, relative to the chart window.

y%
--
An integer that indicates the top of the first character, in pixels,
relative to the chart window.

font%
-----
An integer that contains the number of the font (in currently loaded list)
to use.

color%
------
An integer that contains the color number in the chart palette used to
assign color to the string.

string$
-------
The text string to be printed.


The LabelChartV procedure must be called after calling the charting sub.

Each character is printed vertically and appears in a vertical column.
If an invalid font number (such as 0) is contained in font%, the first font
loaded is used. If no fonts are loaded, the default font contained in the
Presentation Graphics toolbox files is used.




MakeChartPattern$ FUNCTION

Action
Changes fill pattern and color.


Syntax
MakeChartPattern$(refPattern$, foreground%, background%)

Remarks
The MakeChartPatern$ and GetPattern$ procedures are used in combination with
the GetPaletteDef and SetPaletteDef procedures to change the fill pattern
for pie, column, and bar charts.

The GetPattern$ procedure uses the following arguments:

refPattern$    A string representing the pixel pattern.
foreground%    Attribute to map to the pixels in refPattern$ that are
defined as being on.
background%    Attribute to map to the pixels in refPattern$ that are
defined as off.

Note that if foreground% and background% are the same value, the fill
pattern appears as a solid color.
Constructing a value for refPattern$ is difficult. When using the
Presentation Graphics toolbox, you can simplify the process by using the
GetPattern$ procedure to choose an internally-defined pattern.
MakeChartPattern$ maps colors to the string returned by GetPattern$ to
produce the combination of color and pattern you want. For more information,
see the entry for the GetPattern$ procedure earlier in this section.


ResetPaletteDef Sub

Action
Rebuilds the internal chart palette for the current screen mode.


Syntax
ResetPaletteDef




SetPaletteDef Sub

Action
Replaces the internal chart palette with new values.


Syntax
SetPaletteDef palc%(), pals%(), palp$(), palch%(), palb%()

Remarks
The SetPaletteDef procedure uses the following arguments:

palc%()
-------
A one-dimensional integer array of color numbers corresponding to the
palette entries.

pals%()
-------
A one-dimensional integer array of line styles corresponding to the palette
entries.

palp$()
-------
A one-dimensional string array of fill patterns corresponding to the palette
entries.

palch%()
--------
A one-dimensional integer array of plot-character numbers corresponding to
the palette entries.

palb%()
-------
A one-dimensional integer array of line styles used for drawing window
borders and grid lines.


The dimensions for each array must be declared from 0 to cPalLen, a constant
found in the CHRTB.BI header file. Note that all palette arrays have a lower
bound of 0 (not 1, which is used for data and category string arrays).
For more information on fill patterns, see the entries for PAINT and PALETTE
in Part 1, "Language Reference."


Part 3:  Fonts Tool Box


The Fonts toolbox (FONTB.BAS), included with this version of BASIC, contains
a set of routines that perform font-management tasks such as registering,
loading, selecting, and printing fonts on the screen.
Nine font files are supplied: Courier fonts in COURA.FON, COURB.FON, and
COURE.FON, Helvetica fonts in HELVA.FON, HELVB.FON and HELVE.FON, and Times
Roman fonts in TMSRA.FON, TMSRB.FON and TMSRE.FON. Each of these files
contains six font sizes. Besides these two font files, the Fonts toolbox
will work with any standard Windows bitmap .FON file.

To use the Fonts toolbox, you must compile and link the FONTASM.OBJ and
FONTB.BAS modules into a .LIB or .QLB library file. Once this library
exists, you can use it just like any other library. The Fonts toolbox can be
used independently of the Presentation Graphics toolbox to draw graphics
text.

Several of the procedures use the font-header information defined in the
user-defined type FontInfo. This type is defined in the FONTB.BI header
file. This file also contains definitions for constants that can be used as
arguments to the procedures described in this section. Using these constants
in place of hand-coded numbers makes your program cleaner and easier to
debug.



Font Error Codes

If an error occurs during the execution of a font function or sub procedure,
the variable FontErr will contain a non-zero value.

For non-BASIC errors, the error numbers can be tested using numerics or
constants as defined in the FONTB.BI header file. The meaning of a non-BASIC
error is shown in Table 3.9.

╓┌───────────┌────────────────────────────────────────────────┌──────────────╖
Number      Constant name                                    Type of error
────────────────────────────────────────────────────────────────────────────
FontNum     The location of the font in the registered list
            or the loaded list.

Ascent      The pixel distance from the character baseline
            to the top of the character box.

Points      The point size of the current font as defined
            in the  LoadFont% function.

Number      Constant name                                    Type of error
────────────────────────────────────────────────────────────────────────────

PixWidth    The width of the character bitmap. A value of 0
            specifies a proportional font. A nonzero value
            specifies the pixel width of the characters in
            a fixed-space font.

PixHeight   The height of the character bitmap.

Leading     The number of blank lines at the top of the
            character definition to act as leading between
            lines.

AvgWidth    The average width of characters in pixels.

MaxWidth    The pixel width of the widest character in the
            font.

FileName    The filename from which the font was loaded.
            The filename has the extension .FON.
Number      Constant name                                    Type of error
────────────────────────────────────────────────────────────────────────────
            The filename has the extension .FON.

FaceName    The name of the typeface (for example,
            Helvetica, Courier) taken from the filename.






Note

When using the  GetFontInfo procedure, be sure you have access to the .FON
file on disk so that it can find the FontNum, FileName, and FaceName values
for the currently selected font.

For more information on the elements of the variable type FontInfo, see
documentation on font file format in Chapter 7, "File Formats" in the
Programmer's Reference, which is part of the Microsoft Windows Software
Development Kit.


GetGTextLen% Function

Action
Returns the pixel length of a string based on the currently selected font.

Syntax
    GetGTextLen% ( txt$)


Remarks
    GetGTextLen% is an integer that contains the pixel length of the string
supplied in the argument  txt$. The pixel length returned from the
GetGTextLen% function is based on the currently selected font. From this
pixel length, you then can determine whether a string will fit on a
particular screen (for example, CGA, EGA).



GetMaxFonts Sub

Action
Gets the maximum number of fonts that can be registered and loaded.

Syntax
    GetMaxFonts ( maxregistered%,  maxloaded%)


Remarks
The  GetMaxFonts procedure uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    maxregistered%                         An integer that is the maximum
                                        number of fonts that can be
                                        registered.

    maxloaded%                             An integer that is the maximum
                                        number of fonts that can be loaded.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        number of fonts that can be loaded.





    GetMaxFonts returns the current number of fonts that can be registered and
loaded as set in the  SetMaxFonts routine. The default is 10.

See Also
    GetTotalFonts,  SetMaxFonts



GetRFontInfo Sub

Action
Gets the font information on the currently registered font.

Syntax
    GetRFontInfo ( n%, fontinfo)


Remarks
The  GetRFontInfo procedure uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    n%                                     The number of the registered font.

    fontinfo                               A variable of type FontInfo that
                                        receives the font-header
                                        information.





The FontInfo data structure type is defined as follows:

FontInfo
TYPE FontInfo
FontNumASINTEGER
AscentASINTEGER
PointsASINTEGER
PixWidthASINTEGER
PixHeightASINTEGER
LeadingASINTEGER
AvgWidthASINTEGER
MaxWidthASINTEGER
FileNameASSTRING   *   cMaxFileName
FaceNameASSTRING   *   cMaxFaceName
END TYPE

The following list describes the parts of the FontInfo data structure:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Part                                    Description
────────────────────────────────────────────────────────────────────────────
FontNum                                 The location of the font in the
Part                                    Description
────────────────────────────────────────────────────────────────────────────
FontNum                                 The location of the font in the
                                        registered list or the loaded list.

Ascent                                  The pixel distance from the
                                        character baseline to the top of
                                        the character box.

Points                                  The point size of the current font
                                        as defined in the  LoadFont%
                                        function.

PixWidth                                The width of the character bitmap.
                                        A value of 0 specifies a
                                        proportional font. A non-zero
                                        value specifies the pixel width of
                                        the characters in a fixed-space
                                        font.

PixHeight                               The height of the character bitmap.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
PixHeight                               The height of the character bitmap.

Leading                                 The number of blank lines at the
                                        top of the character definition to
                                        act as leading between lines.

AvgWidth                                The average width of characters in
                                        pixels.

MaxWidth                                The pixel width of the widest
                                        character in the font.

FileName                                The filename from which the font
                                        was loaded. The filename has the
                                        extension .FON.

FaceName                                The name of the typeface (for
                                        example, Helvetica, Courier) taken
                                        from the filename.
Part                                    Description
────────────────────────────────────────────────────────────────────────────
                                        from the filename.





Note
When using  GetRFontInfo, make sure you have access to the .FON file on disk
so that it can find the FontNum, FileName, and FaceName values for the
currently selected font.

For more information on the elements of the variable type FontInfo, see the
Microsoft Windows developer documentation on font file format.



GTextWindow Sub

Action
Retains the logical coordinates of window boundaries. (See note below.)

Syntax

    GTextWindow ( x1,  y1,  x2,  y2,  Scrn%)


Remarks
The  GTextWindow procedure uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    x1                                     Integer containing the minimum X
                                        value (logical coordinate).

    y1                                     Integer containing the minimum Y
                                        value.

    x2                                     Integer containing the maximum X
                                        value.
Argument                                Description
────────────────────────────────────────────────────────────────────────────
                                        value.

    y2                                     Integer containing the maximum Y
                                        value.

    Scrn%                                  Integer containing either cTRUE
                                        (used with WINDOW SCREEN statement
                                        to show Y values increase top to
                                        bottom) or cFALSE (used with
                                        WINDOW statement to show window Y
                                        values increase bottom to top).

    registered%                            The number of currently registered
                                        fonts.

    loaded%                                The number of currently loaded
                                        fonts.





See Also
    GetMaxFonts,  SetMaxFonts



LoadFont% Function

Action
Loads the font information from the .FON files or memory for the specified
registered fonts and returns the number of fonts actually loaded.

Syntax
    LoadFont% ( fontspec$)


Remarks
The argument  fontspec$ is a specification used to load one or more of the
registered fonts. The specification for each font consists of one or more of
the following:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Specification                           Description
────────────────────────────────────────────────────────────────────────────
n #                                     Loads font number  # in the list
                                        of currently registered fonts.

t  name                                 Specifies the desired font  name.
                                        (There must be a space between t
                                        and  name.)

s #                                     Specifies point size  #. When s is
                                        specified, only the fonts designed
                                        for the screen mode specified by m
                                        are used.

h #                                     Specifies pixel height  # of a
                                        font.

m #                                     Specifies screen mode  #. This is
Specification                           Description
────────────────────────────────────────────────────────────────────────────
m #                                     Specifies screen mode  #. This is
                                        used for sizing fonts with s.  The
                                        default is the current screen mode.

b                                       Selects the best fit based on the
                                        size specified in the s or h
                                        options. The specification b is
                                        ignored with vector fonts because
                                        they can be any size.





╓┌────┌──────────────────────────────────────────────────────────────────────╖
────────────────────────────────────────────────────────────────────────────
f    Loads only a single fixed-space font.
p    Loads only the first proportionally spaced font that registered.




Any previously loaded fonts are removed from memory. To load more than one
font, multiple specifications are needed.

Multiple specifications are separated by slash characters, and blanks are
ignored. If the specifications do not match a registered font or if an
invalid font is specified, then font number one (n1) is used.

The  LoadFont% function loads the character-bit maps into the loaded fonts
array. This array corresponds to the registered fonts array which stores the
font-header information. Before you can use the  LoadFont% function, you
must use the  RegisterFont% function.

Note
The total size of the font data should be less than or equal to 64K unless
the /AH option is used when invoking QBX. The /AH option allows the use of
larger arrays.

For more information on selecting a particular loaded font, see the
SelectFont procedure.

Example

The following example demonstrates the  LoadFont% function.

r% = RegisterFonts("tmsrb.fon")' r% should = 6 after call.
l% = LoadFont("h8/h12/h24")' l% should = 3 after call.
' 3 fonts (8,12,24 pts) will be loaded and usable.
SelectFont 2' The 12-point font is current.
SetGTextColor 10' Color 10 is light green.
textlen% = OutGText (1,1,"TmsRmn 12-point")
END


Note that to load fonts according to their order in the font file, l% would
take the form:


l% = LoadFont%("n1,n3,n6")' Load the first, third, and sixth fonts.




OutGText% Function

Action
Outputs text in the currently selected font, using the current graphics
color at the current graphics cursor position, and returns the pixel length
of the character output.

Syntax
    OutGText% ( x,  y,
txt$)



Remarks
The  OutGText% function uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    x                                      A single-precision number that is
                                        the x coordinate of the upper-left
                                        boundary of the first character.

    y                                      A single-precision number that is
                                        the y coordinate of the upper-left
                                        boundary of the first character.

    txt$                                   Text string to output.





After the  OutGText% function has completed outputting the text, it returns
the pixel length of the character string, and  x and  y are changed to the
upper-right position of the last character.



RegisterFonts% function

Action
Registers the font-header information from a specified .FON file and returns
the number of fonts registered.

Syntax
    RegisterFonts% ( filename$)


Remarks
The  RegisterFonts% procedure registers the font-header information from the
.FON file specified in  filename$. The font-header information is stored in
the registered-fonts array. This array corresponds to the loaded-fonts array
which contains the character-bit maps of the fonts stored in the .FON file.
Because an .FON file may hold one or more fonts,  RegisterFonts% returns the
number of fonts registered by the function.

This procedure will register any number of fonts up to the maximum set with
the  SetMaxFonts procedure or to the limit of available memory.


Note
When using the  RegisterFonts% procedure, be sure you have access to the
.FON file on disk so that it can find the filename of the currently selected
font.

For more information on loading the fonts, see the  LoadFont% procedure.



RegisterMemFont% function

Action
Registers the font-header information of fonts that reside in memory and
returns the number of fonts registered.

Syntax
    RegisterMemFont% ( fontseg%,  fontoffset%)


Remarks
The  RegisterMemFont% procedure uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    fontseg%                               An integer that is the segment
                                        address of the in-memory font.

    fontoffset%                            An integer that is the offset
                                        address of the in-memory font..



    SelectFont ( n)



Remarks
The argument  n contains the number of the loaded font that is selected and
becomes the active font.

If  n is greater than the maximum number of loaded fonts, the procedure
automatically selects the font number that corresponds to the remainder from
the modular division between  n and the number of currently loaded fonts.
For example, if  n is 12 and the maximum of loaded fonts is 8, then the font
number selected is 4.



SetGCharSet Sub

Action
Sets the character set used in subsequent graphics characters.

Syntax
    SetGCharSet  (charset%)


Remarks
The argument  charset% is the character set used in mapping input characters
to output characters.  charset% is an integer with two possible values:
cIBMChars and cWindowsChars. The two values are constants defined in the
FONTB.BI file.



SetGTextColor Sub

Action
Sets the character color used in subsequent graphic characters.

Syntax
    SetGTextColor ( color%)


Remarks
The argument  color% is  an integer that is the pixel value of the color to
use in graphic characters.



SetGTextDir Sub

Action
Sets the horizontal or vertical orientation of graphics characters.

Syntax
    SetGTextDir (dir%)


Remarks
The argument  dir% is an integer that specifies a direction for the graphics
characters. Possible values for  dir%, and the resulting character
orientation (counterclockwise rotation) are:

╓┌────────────┌──────────────────────────────────────────────────────────────╖
Value        Character direction
────────────────────────────────────────────────────────────────────────────
0            0 degrees (no rotation)
1            90 degrees (top of character is to the left)
2            180 degrees (characters are inverted)
3            270 degrees (top of character is to the right)





SetMaxFonts Sub

Action
Sets the maximum number of fonts that are allowed to be registered and
loaded.

Syntax
    SetMaxFonts ( maxregistered%,  maxloaded%)


Remarks
The  SetMaxFonts procedure uses the following arguments:

╓┌───────────────────────────────────────┌───────────────────────────────────╖
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    maxregistered%                         An integer that specifies the
Argument                                Description
────────────────────────────────────────────────────────────────────────────
    maxregistered%                         An integer that specifies the
                                        maximum number of fonts that can
                                        be registered.

    maxloaded%                             An integer that specifies the
                                        maximum number of fonts that can
                                        be loaded.





The  SetMaxFonts procedure allocates a maximum number of font-header
elements to hold font information. The font information is registered when
the  RegisterFonts% function is called. Therefore,  SetMaxFont is called
prior to  RegisterFonts% or  LoadFont%. If  SetMaxFonts is not called, the
default number is 10.

    SetMaxFonts acts as a complete reinitialization by removing any previously
registered or loaded fonts from memory and then setting the new maximum
limits of fonts that can be loaded or registered.



UnRegisterFonts Sub

Action
Removes registered fonts from memory.

Syntax
    UnRegisterFonts ( )


Remarks
The  UnRegisterFonts procedure reduces the array storing the font headers to
one element, thereby removing the registered fonts from memory.

Note
When you use  UnRegisterFonts to remove the font-header information from the
registered fonts array, you reduce the array to only one position.
Therefore, if you want to re-register fonts, you must call  SetMaxFonts to
reset the maximum number of fonts that can be registered; for example,
SetMaxFonts(6,6), before calling the  RegisterFonts% function.





♀The User Interface Toolbox

The User Interface toolbox is a group of BASIC procedures and
assembly-language routines that is included with Microsoft BASIC. Together,
these tools allow you to add professional-looking windows and menus to your
programs.

The User Interface toolbox includes many of the user interface features of
the QBX programming environment. When you use the QBX user interface, you
are using many of the features that the toolbox can bring to your own
programs.
*    You can define pull-down menus to support:
        Color
        Mouse
        Access keys
        Shortcut keys

*    You can choose these options in overlapping character-based windows:
        Color
        Closable windows
        Movable windows
        Resizable windows
        Title bars
        Window-border character

*    You can use list boxes and alert boxes.

*    You can specify dialog boxes with:
        Edit fields
        Option buttons
        Command buttons
        Area buttons


The BASIC source code to all of the toolbox procedures is provided with
Microsoft BASIC. You can use these procedures as listed, or alter or expand
their functionality to meet your requirements. Even though most of the
procedures are written in BASIC, they are fast enough for most applications.
There is also an assembly-language object routine, UIASM.OBJ, to ensure that
you get quick response from your user-interface design. This
assembly-language module is linked into the libraries and Quick libraries
created from the User Interface toolbox.

What Makes Up the User Interface Toolbox

The User Interface toolbox actually consists of four parts - that is, four
separate BASIC source-code files - and an include file for each. The files
are:

*    MENU.BAS, MENU.BI
*    WINDOW.BAS, WINDOW.BI
*    MOUSE.BAS, MOUSE.BI
*    GENERAL.BAS, GENERAL.BI

In each case, the .BAS file contains the actual code for the procedures and
the .BI file contains user-defined type definitions and procedure
declarations used in the .BAS file.

The following discussion briefly explains the contents of each part of the
User Interface toolbox.

Menus
The MENU.BAS source-code file contains all the procedures that let you
create custom menus in your programs. These procedures are dependent on the
other parts of the User Interface toolbox (GENERAL.BAS and MOUSE.BAS). If
you use the procedures in MENU.BAS, you must include GENERAL.BI, MOUSE.BI,
and MENU.BI in your program so you have the proper declarations and
definitions. In addition to procedure declarations, the header file MENU.BI
contains definitions of several user-defined types that are used in global
variables to store menu configuration information.

A more detailed explanation of menus and their application is described in
the MENU.BAS section below.

Windows
The WINDOW.BAS source-code file contains the procedures that let you create
custom character-based windows in your programs. WINDOW.BAS is dependent on
all the other parts of the User Interface toolbox; therefore, when you use
the procedures in WINDOW.BAS, you must include GENERAL.BI, MOUSE.BI,
MENU.BI, and WINDOW.BI so that all declarations and definitions on which
WINDOW.BAS depends are available.

The header file WINDOW.BI contains procedure declarations along with the
definitions of user-defined types. These user-defined types are used to
store information about the characteristics of windows, buttons, and edit
fields.


Mouse
The MOUSE.BAS source-code file provides mouse support. The procedures in
this code can be used by themselves if need be, but they were designed as an
integral part of the User Interface toolbox. The routines specifically
support the Microsoft Mouse. A Microsoft Mouse and driver are recommended.
However, the procedures support any pointing device with a 100 percent
Microsoft-Mouse-compatible driver. A Microsoft driver (MOUSE.COM) is shipped
with BASIC.

If you use the procedures in MOUSE.BAS, you must include GENERAL.BI and
MOUSE.BI in your program so you will have the proper declarations and
definitions. The header file MOUSE.BI includes procedure declarations for
the MOUSE.BAS file.


General
The GENERAL.BAS source-code file contains a number of general purpose
character-based routines that are used in both the MENU.BAS and WINDOW.BAS
files. While these files can be used by themselves, they are intended to
support the other procedures in the User Interface toolbox. If you use any
of the procedures in GENERAL.BAS, you must include the header file,
GENERAL.BI.

The header file GENERAL.BI contains a user-defined type definition (RegType)
that is used with the Interrupt routine to access DOS interrupt services for
mouse support. This DOS interrupt also returns the shift state of special
keys, and scrolls screen areas. GENERAL.BI contains a number of global
constant definitions that apply throughout the User Interface toolbox. These
definitions are described in the following table:

Constant    Value    Comment

FALSE         0
TRUE         -1
MINROW        2      Minimum number of rows on screen
MAXROW       25      Maximum number of rows on screen
MINCOL        1      Minimum number of columns on screen
MAXCOL       80      Maximum number of columns on screen
MAXMENU      10      Maximum number of menus on menu bar
MAXITEM      20      Maximum number of items on a menu
MAXWINDOW    10      Maximum number of windows on screen
MAXBUTTON    50      Maximum number of buttons on screen
MAXEDITFIELD 20      Maximum number of edit fields on screen
MAXHOTSPOT   20      Maximum number of active areas on screen

Note
----
An active area is defined as any area that can be selected by the user,
including all types of buttons and edit fields, and any of the special
characters used to affect windows.



How to Use the Toolbox in Your Programs

You can incorporate the User Interface toolbox into your programs in three
ways. The first is to simply include the source-code files you plan to use
in your program. For each source-code file you include, be sure to also
include the associated .BI file. Use the $INCLUDE metacommand to include
external files in your program.

The second way is to load each BASIC source-code file as a separate module
and use a Quick library only for the assembly-language routines. You should
use this method if you are planning to alter or expand the functionality of
the User Interface toolbox. Create the Quick library you need with the
following command:

LINK /Q UIASM.OBJ QBX.LIB, UIASM.QLB,,QBXQLB.LIB;

The final method - and most practical when creating stand-alone programs -
is to create a Quick library that uses the procedures in the BASIC
source-code files and the assembly-language files. This is somewhat more
difficult, but is still quite easy. If you chose to have Quick libraries
created when you first installed BASIC, you already have the Quick library
you need. If you didn't, you'll have to make it yourself. To begin, be sure
that you are in the QBX directory where all of the .LIB files that came with
the program are located.

Creating a complete Quick library involves several steps. First you'll have
to create a Quick library that includes needed procedures that are already
in the QBX libraries (QBX.QLB and QBX.LIB) plus the User Interface toolbox
object file, UIASM.OBJ. You can do this at the system prompt with the
following command:

LINK /Q UIASM.OBJ QBX.LIB, UIASM.QLB,,QBXQLB.LIB;

Next, create the parallel .LIB library using the same files you just used to
make the Quick library. Use the following command:
LIB UIASM.LIB+UIASM.OBJ+QBX.LIB;

Once you've created the first two libraries, you can create the libraries
that include not only the assembly-language routines, but the BASIC
procedures as well. The easiest way is to do this from the QBX programming
environment. Start QBX with the /L option and specify the Quick library that
you just created, as follows:

QBX /L UIASM.QLB

Once you are in the QBX programming environment, use the File menu to load
each of the individual files you want to include in your User Interface
toolbox library. For example, if you want to use menus in your program, load
GENERAL.BAS, MOUSE.BAS, and MENU.BAS. GENERAL.BAS and MOUSE.BAS are required
because of dependencies that exist between the components of the User
Interface toolbox. If you want windows, load GENERAL.BAS, MOUSE.BAS,
MENU.BAS, and WINDOW.BAS.

With all of the files loaded, choose Make Library from the Run menu. When
prompted for a library name, use the name UITBEFR.QLB. Press Return and two
libraries will be created for you. The first is the Quick library that you
will use whenever you want to incorporate menus into your programs that run
in QBX. The second is the parallel .LIB file that will allow you to create a
stand-alone .EXE file from your BASIC program.

If you change any of the BASIC code that comprises the User Interface
toolbox, you can relink those object modules and create new libraries and
Quick libraries as needed. More complete information about creating
libraries and using mixed-language programming can be found in Chapter 18,
"Using LINK and LIB" in the Programmer's Guide.

If you use a library or Quick library that contains procedures from one or
more of the User Interface toolbox source-code files, you must include the
.BI file for that source-code file into your program before you call any of
the library's procedures. If you include a complete source-code file, it is
not necessary to include the .BI file, because an $INCLUDE metacommand is
already in the source-code file. However, if you include the source-code
file in your program, you must ensure that you also include any other files
(either .BAS or .BI) that the included code might depend on. For example, if
you use WINDOW.BAS, you must also include all of the other parts of the User
Interface toolbox. The procedures in WINDOW.BAS depend on definitions,
declarations, and procedures in each of the other parts.


Detailed Description
The following sections contain a detailed descriptions of each of the
individual parts of the User Interface toolbox. Because the User Interface
toolbox is character based, many procedures require row and column
coordinates as arguments. Where these are required, the following
definitions apply:

row%, col%     An integer pair that describes a screen position.
row1%, col1%   An integer pair that describes the upper-left corner of an
area.
row2%, col 2%  An integer pair that describes the lower-right corner of an
area.


Note
----
The row% and col% coordinates can be actual screen coordinates. However,
often they are coordinates that are relative to the upper-left corner of the
current window.


MENU.BAS
Using the procedures in MENU.BAS is straightforward. In most cases, the
demonstration program UIDEMO.BAS provides enough information for a BASIC
programmer of some experience to get started. However, a few notes of
introduction are in order.

When you use the procedures in MENU.BAS, you must provide the following
global array declarations in your program, in the order shown:

COMMON SHARED /uitools/GloMenu AS MenuMiscType
COMMON SHARED /uitools/GloTitle() AS MenuTitleType
COMMON SHARED /uitools/GloItem() AS MenuItemType
DIM GloTitle(MAXMENU) AS MenuTitleType
DIM GloItem(MAXMENU, MAXITEM) AS MenuItemType

The order is important because the block defined by COMMON in the Quick
library must agree with the block defined by COMMON in the programming
environment. These global arrays are used to store information about the
menus you define.

As previously mentioned, the menus in the User Interface toolbox work like
those in the QBX programming environment. Menu titles are displayed on a
menu bar that extends across the top of the screen in row 1. Associated with
each menu are one or more menu items. From the programmer's standpoint,
menus are numbered from left to right, beginning at 1. Menu items -that is,
those choices associated with each menu - are numbered from top to bottom,
also beginning at 1. For any given menu, menu item 0 is always the menu
title.

The MenuColor procedure lets you select the color scheme for your menus. A
single MenuSet statement is all that is required to set up each menu title
on the menu bar or each menu item associated with a menu.

Menus can be selected with the mouse - by pointing and clicking - or with
the keyboard, by pressing the Alt key and the highlighted letter in the
desired menu title. When a menu is selected, the choices associated with
that menu will pull down, or drop, from the menu bar so that you can see the
choices available. When a pull-down menu is displayed, menu items can be
chosen by pointing and clicking with the mouse, or pressing the highlighted
key associated with that choice. The key combinations used in the latter
selection technique are called access keys. Access keys consist of a series
of menu-item-selection keystrokes; each series begins by pressing the Alt
key.

You also can set up shortcut keys to use in lieu of the mouse or the regular
access keys. Shortcut keys can use any character or extended character,
except those that use the Alt key. For example, you can use Ctrl+X,
Ctrl+F10, or simply F3). To enable a shortcut key, use a ShortCutKeySet
statement to identify the menu and menu item with the definition of the
short-cut key.

Before actually building your menus, you need to initialize global arrays to
speed up menu response. Use the MenuInit procedure to initialize the arrays
you declared and initialize the mouse.

The following code fragment illustrates how to put together a short menu
with one title, two item choices and a means of exiting the menu:

MenuInit             ' Initialize everything, including the mouse.
MenuSet 1,0,1,"Menu Title",1     ' Set up menu title.
MenuSet 1,1,1,"Selection 1 F1",11     ' Set up first selection.
MenuSet 1,2,1,"Selection 2 F2",11     ' Last parameter determines
                                ' highl