Reference Guide

QBasic Online Help Index

Keywords By Programming Task

DO LOOP

DO [{WHILE | UNTIL} condition]
  [statementblock]
LOOP

DO
  [statementblock]
LOOP [{WHILE | UNTIL} condition]

condition

A numeric expression that Basic evaluates as true (nonzero) or false (zero).

Example:

i% = 0
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%

See also EXIT   FOR...NEXT   WHILE...WEND

END

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

DEF

Ends a multiline DEF FNfunction definition.

FUNCTION

Ends a FUNCTION procedure definition.

IF

Ends a block IF...THEN...ELSE statement.

SELECT

Ends a SELECT CASE block.

SUB

Ends a SUB procedure.

TYPE

Ends a user-defined data type definition.

If no argument is supplied, END ends the program and closes all files.

Example:

PRINT "Game over."
END

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

EXIT

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

DEF

Exits a DEF FNfunction.

DO

Exits a DO loop.

FOR

Exits a FOR loop.

FUNCTION

Exits a FUNCTION procedure.

SUB

Exits a SUB procedure.

Example:

i% = 0
DO
  i% = i% + 1
  IF i% = 500 THEN EXIT DO
LOOP
PRINT "EXIT at"; i%

See also DEF FN   DO...LOOP   FOR...NEXT   FUNCTION   SUB

FOR NEXT

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

counter

A numeric variable used as the loop counter.

start and end

The initial and final values of the counter.

increment

The amount the counter is changed each time through the loop.

Example:

FOR i% = 1 TO 15
  PRINT i%
NEXT i%
FOR i% = 7 TO -6 STEP -3
  PRINT i%
NEXT i%

See also DO...LOOP   EXIT   WHILE...WEND

IF THEN ELSE

IF condition1 THEN
  [statementblock-1]
[ELSEIF condition2 THEN
  [statementblock-2]]...
[ELSE
  [statementblock-n]]
END IF

IF condition THEN statements [ELSE statements]

condition1

condition2

Any expression that can be evaluated as true (nonzero) or false (zero).

statementblock-1

statementblock-2

statementblock-n

One or more statements on one or more lines.

statements

One or more statements, separated by colons.

Example:

INPUT "1 or 2? ", i%
IF i% = 1 OR i% = 2 THEN
  PRINT "OK"
ELSE
  PRINT "Out of range"
END IF

See also ON...GOSUB   ON...GOTO   SELECT CASE

GOSUB / RETURN

GOSUB line1
.
.
.
RETURN [line2]

line1

The label or line number of the first line of the subroutine.

line2

The label or line number where the subroutine returns.

If you don't supply a label or line number for RETURN, the program continues execution at the statement following the GOSUB (for subroutine calls) or where an event occurred (for event handling). See the ON keyword for information about event-handling statements.

SUB and CALL statements provide a better alternative to GOSUB subroutines.

Example:

FOR i% = 1 TO 20
  GOSUB Square
NEXT i%
END

Square:
PRINT i%, i% * i%
RETURN

See also CALL   ON Keyword   ON...GOSUB   SUB

GOTO

GOTO line

line

The label or number of the line to execute next.

DO...LOOP, SELECT CASE, IF...THEN...ELSE, SUB, and FUNCTION provide better ways to control the flow of your program.

GOTO is also used as a keyword in the ON ERROR statement.

Example

See also DO...LOOP   FUNCTION   IF...THEN...ELSE   ON ERROR   ON...GOTO   SELECT CASE   SUB

ON

• Enables error trapping when used with the ON ERROR statement.
• Enables event trapping when used with the event ON statements (COM ON, KEY ON, PEN ON, PLAY ON, STRIG ON, and TIMER ON).
• Specifies an event to trap when used with the ON event statements (ON COM, ON KEY, ON PEN, ON PLAY, ON STRING, and ON TIMER).
• Specifies an expression to evaluate when used with the ON...GOSUB and ON...GOTO statements.

See also COM, ON COM   KEY, ON KEY   ON ERROR   ON...GOSUB, ON...GOTO   PEN, ON PEN   PLAY, ON PLAY   STRIG, ON STRIG   TIMER, ON TIMER

ON GOSUB / ON GOTO

ON expression% GOSUB line-list
ON expression% GOTO line-list

expression%

An expression in the range 0 through 255.

line-list

A set of labels or line numbers. If the value of the expression is 1, the program branches to the first line in the list; if the expression is 2, it branches to the second line, and so on.

SELECT CASE provides a better way to perform multiple branching.

Example:

FOR i% = 1 TO 2
  ON i% GOSUB one, Two
NEXT i%
END

one:
PRINT "One"
RETURN
Two:
PRINT "Two"
RETURN

See also ON Keyword   SELECT CASE

SELECT CASE

SELECT CASE testexpression
CASE expressionlist1
  [statementblock-1]
[CASE expressionlist2
  [statementblock-2]]...
[CASE ELSE
  [statementblock-n]]
END SELECT

testexpression

Any numeric or string expression.

expressionlist1

expressionlist2

One or more expressions to match testexpression. The IS keyword must precede any relational operators in an expression.

statementblock-1

statementblock-2

statementblock-n

One or more statements on one or more lines.

The expressionlist arguments can have any of these forms or a combination of them, separated by commas:

expression[,expression]...
expression TO expression
IS relational-operator expression

expression

Any numeric or string expression compatible with testexpression.

relational-operator

One of the following relational operators: <, <=, >, >=, <>, or =.

Example:

INPUT "Enter acceptable level of risk (1-5): ", Total
SELECT CASE Total

  CASE IS >= 5
    PRINT "Maximum risk and potential return."
    PRINT "Choose stock investment plan."

  CASE 2 TO 4
    PRINT "Moderate to high risk and potential return."
    PRINT "Choose mutual fund or corporate bonds."

  CASE 1
    PRINT "No risk, low return."
    PRINT "Choose IRA."

END SELECT

See also IF...THEN...ELSE

STOP

STOP

The STOP keyword also suspends trapping of events in these statements:
COM, ON COM   KEY, ON KEY   PEN, ON PEN   PLAY, ON PLAY   STRIG, ON STRIG   TIMER, ON TIMER

Example:

FOR i% = 1 TO 10
  PRINT i%
  IF i% = 5 THEN STOP     'STOP pauses; F5 Continues.
NEXT i%

See also END   SYSTEM

SYSTEM

SYSTEM

See also END   STOP

CONST

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

constantname

The name of the constant. This name can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

expression

An expression that is assigned to the constant. The expression can consist of literals (such as 1.0), other constants, any arithmetic or logical operators except exponentiation (^), or a single literal string.

Example:

CONST PI = 3.141593
INPUT "Radius of Circle: "; R
PRINT "Area = "; PI * R ^ 2

DATA / READ / RESTORE

DATA constant[,constant]...
READ variablelist
RESTORE [line]

constant

One or more numeric or string constants specifying the data to be read. String constants containing commas, colons, or leading or trailing spaces are enclosed in quotation marks (" ").

variablelist

One or more variables, separated by commas, that are assigned data values. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

line

The label or line number of a DATA statement. If line is omitted, the next READ statement reads values in the first DATA statement in the program.

DATA statements can be entered only at the module level. They cannot be used in procedures.

Example:

FOR i% = 1 TO 3
  READ a%, b$
  PRINT a%, b$
  RESTORE
NEXT i%
DATA 1, "Repeat"

DIM / REDIM

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

SHARED

Specifies that variables are shared with all SUB or FUNCTION procedures in the module.

variable

The name of an array or variable.

subscripts

Dimensions of the array, expressed as follows:
[lower TO] upper [,[lower TO] upper]...

lower

The lower bound of the array's subscripts. The default lower bound is zero.

upper

The upper bound.

AS type

Declares the data type of the array or variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

DIM declares either static or dynamic arrays. Unless array storage has been determined by $STATIC, $DYNAMIC, or COMMON, arrays dimensioned with numbers are static and arrays dimensioned with variables are dynamic. REDIM always declares dynamic arrays.

Static array storage is allocated when you start a program and remains fixed. Dynamic array storage is allocated while a program runs.

Example:

' $DYNAMIC
DIM a(49, 49)
REDIM a(19, 14)

See also COMMON   ERASE   OPTION BASE   SHARED, STATIC   $STATIC, $DYNAMIC

ERASE

ERASE arrayname [,arrayname]...

arrayname

The name of an array.

For static arrays, ERASE sets each element of a numeric array to zero and each element of a string array to null.

For dynamic arrays, ERASE frees the memory used by the array. You must redeclare the array's dimensions with REDIM or DIM before using it.

Example:

DIM a%(0)
a%(0) = 6
PRINT "Before: "; a%(0)
ERASE a%
PRINT "After: "; a%(0)

See also CLEAR   DIM, REDIM

OPTION BASE

OPTION BASE {0 | 1}

The DIM statement TO clause provides a better way to set the lower bound of an array subscript.

See also DIM, REDIM   LBOUND, UBOUND

REM

REM remark
' remark

remark

Any text.

Remarks are ignored when the program runs unless they contain metacommands.

A remark can be inserted on a line after an executable statement if it is preceded by the single-quote (') form of REM or if REM is preceded by a colon (:).

Example:

REM    This is a comment.
'      This is also a comment.
PRINT "Test1"       'This is a comment after a PRINT statement.
PRINT "Test2":   REM This is also a comment after a PRINT statement.

See also $STATIC, $DYNAMIC

SWAP

SWAP variable1, variable2

variable1 and variable2

Two variables of the same data type.

Example:

a% = 1: b% = 2
PRINT "Before: "; a%, b%
SWAP a%, b%
PRINT "After: "; a%, b%

TYPE

TYPE usertype
  elementname AS typename
  [elementname AS typename]
.
.
.
END TYPE

usertype

The name of the data type being defined. The name can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

elementname

An element of the user-defined data type.

typename

The element's type (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

Use DIM, REDIM, COMMON, STATIC, or SHARED to create a variable of a user-defined data type.

Example:

TYPE Card
  Suit AS STRING * 9
  Value AS INTEGER
END TYPE
DIM Deck(1 TO 52) AS Card
Deck(1).Suit = "Club"
Deck(1).Value = 2
PRINT Deck(1).Suit, Deck(1).Value

See also COMMON   DIM, REDIM   SHARED, STATIC

CALL

[CALL] name [([argumentlist])]

name

The name of the SUB procedure to call.

argumentlist

The variables or constants to pass to the SUB procedure. Separate multiple arguments with commas. Specify array arguments with the array name followed by empty parentheses.

If you omit the CALL keyword, also omit the parentheses around argumentlist. Either declare the procedure in a DECLARE statement before calling it, or save the program and QBasic automatically generates a DECLARE statement.

To specify an argument whose value will not be changed by the procedure, enclose the argument in parentheses.

Example:
The program REMLINE.BAS illustrates calling SUB procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also CALL ABSOLUTE   DECLARE   SUB

DECLARE

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

name

The name of the procedure.

parameterlist

One or more variables that specify parameters to be passed to the procedure when it is called:
variable[( )] [AS type] [, variable[( )] [AS type]]...

variable

A Basic variable name.

type

The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type). ANY allows any DATA type.

DECLARE

is required if you call SUB procedures without CALL. QBasic automatically generates DECLARE statements when you save your program.

Example:
The program REMLINE.BAS illustrates declaring FUNCTION and SUB procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also CALL   FUNCTION   SUB

FUNCTION

FUNCTION name [(parameterlist)] [STATIC]
[statementblock]
name = expression
[statementblock]
END FUNCTION

name

The name of the function and the data type it returns, specified by a data-type suffix (%, &, !, #, or $).

parameterlist

One or more variables that specify parameters to be passed to the function when it is called:
variable[( )] [AS type] [, variable[( )] [AS type]]...

variable

A Basic variable name.

type

The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

STATIC

Specifies that the values of the function's local variables are saved between function calls.

expression

The return value of the function.

When you call the function, you can specify that an argument's value will not be changed by the function by enclosing the argument in parentheses.

Example:
The program REMLINE.BAS illustrates calling FUNCTION procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also DECLARE   DEF FN   EXIT   SHARED, STATIC   SUB

RUN

RUN [{linenumber | file$}]

linenumber

The line number in the current program where execution should begin. If no line number is specified, execution begins at the first executable line.

file$

The name of a Basic source file. QBasic assumes a .BAS extension.

RUN closes all files and clears program memory before loading a program. Use the CHAIN statement to run a program without closing open files.

Example:

'Assumes the program TEST.BAS is in a \DOS directory.
RUN "C:\DOS\TEST.BAS"

See also CHAIN

SHELL

SHELL (commandstring$)

commandstring$

The name of a DOS command or batch file.

Your program resumes when the DOS command or batch file completes.

If you omit the command string, SHELL invokes a DOS shell and displays the DOS prompt. Use the EXIT command to resume your program.

Example:

SHELL "DIR"

SHARED / STATIC

SHARED variable[()] [AS type] [,variable[()] [AS type]]...
STATIC variable[()] [AS type] [,variable[()] [AS type]]...

variable

The name of the module-level variable to share or variable to make static. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

AS type

Declares the data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type).

Example:
The program REMLINE.BAS illustrates using the SHARED and STATIC statements. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also COMMON   DIM, REDIM

SUB

SUB name[(parameterlist)] [STATIC]
[statementblock]
END SUB

name

The name of the SUB procedure, up to 40 characters long, with no data type suffix.

parameterlist

One or more variables that specify parameters to be passed to the SUB procedure when it is called:
variable[( )] [AS type] [, variable[( )] [AS type]]...

variable

A Basic variable name.

type

The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

STATIC

Specifies that the values of the SUB procedure's local variables are saved between function calls.

When you call the SUB procedure, you can specify that an argument's value will not be changed by the procedure by enclosing the argument in parentheses.

Example:
The program REMLINE.BAS illustrates calling SUB procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also CALL   DECLARE   EXIT   FUNCTION   SHARED, STATIC

CLS

CLS [{0 | 1 | 2}]

CLS

Clears either the text or graphics viewport. If a graphics viewport has been set (using VIEW), clears only the graphics viewport. Otherwise, clears the text viewport or entire screen.

CLS 0

Clears the screen of all text and graphics.

CLS 1

Clears the graphics viewport or the entire screen if no graphics viewport has been set.

CLS 2

Clears the text viewport.

See also VIEW   VIEW PRINT   WINDOW

LOCATE / CSRLIN / POS

LOCATE [row%] [,[column%] [,[cursor%] [,start% [,stop%]]]]
CSRLIN
POS(expression)

row% and column%

The number of the row and column to which the cursor moves.

cursor%

Specifies whether the cursor is visible: 0 = invisible, 1 = visible

start% and stop%

Integer expressions in the range 0 through 31 that specify the first and last cursor scan lines. You can change the cursor size by changing the cursor scan lines.

expression

Any expression.

Example:

CLS
LOCATE 5, 5
MyRow% = CSRLIN
MyCol% = POS(0)
PRINT "Position 1 (Press any key)"
DO
LOOP WHILE INKEY$ = ""
LOCATE (MyRow% + 2), (MyCol% + 2)
PRINT "Position 2"

INKEY$

INKEY$

INKEY$ returns a null string if there is no character to return.

For standard keys, INKEY$ returns a 1-byte string containing the character read.

For extended keys, INKEY$ returns a 2-byte string made up of the null character (ASCII 0) and the keyboard scan code.

Example:

PRINT "Press Esc to exit..."
DO
LOOP UNTIL INKEY$ = CHR$(27)    '27 is the ASCII code for Esc.

See also Keyboard Scan Codes

INP / OUT

INP(port%)
OUT port%, data%

port%

A number in the range 0 through 65,535 that identifies The port.

data%

A numeric expression in the range 0 through 255 to send to the port.

Example:

x% = INP(&H3FC)          'Read COM1 Modem Control Register.
OUT &H3FC, (x% XOR 1)    'Change Data Terminal Ready bit.

See also WAIT

INPUT / LINE INPUT

INPUT [;] ["prompt"{; | ,}] variablelist
LINE INPUT [;] ["prompt";] variable$
INPUT #filenumber%, variablelist
LINE INPUT #filenumber%, variable$

prompt

An optional literal string that is displayed before the user enters data. A semicolon after prompt appends a question mark to the prompt string.

variablelist

One or more variables, separated by commas, in which DATA entered from the keyboard or read from a file is stored. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

variable$

Holds a line of characters entered from the keyboard or read from a file.

filenumber%

The number of an open file.

INPUT uses a comma as a separator between entries.
LINE INPUT reads all characters up to a carriage return.

For keyboard input, a semicolon immediately after INPUT keeps the cursor on the same line after the user presses the Enter key.

Example:

CLS
OPEN "LIST" FOR OUTPUT AS #1
DO
  INPUT "   NAME:       ", Name$  'Read entries from the keyboard.
  INPUT "   AGE:        ", Age$
  WRITE #1, Name$, Age$
  INPUT "Add another entry"; R$
LOOP WHILE UCASE$(R$) = "Y"
CLOSE #1
'Echo the file back.
OPEN "LIST" FOR INPUT AS #1
CLS
PRINT "Entries in file:": PRINT
DO WHILE NOT EOF(1)
  LINE INPUT #1, REC$  'Read entries from the file.
  PRINT REC$           'Print the entries on the screen.
LOOP
CLOSE #1
KILL "LIST"

See also INKEY$   INPUT$   OPEN Statement File Modes

KEY

KEY key%, stringexpression$
KEY LIST
KEY ON
KEY OFF

key%

The number of a function key. Use 1 through 10 for function keys F1 through F10. Use 30 and 31 for function keys F11 and F12 on extended keyboards.

stringexpression$

A string of up to 15 characters that is returned when the function key is pressed.

LIST

Displays the assignments for each key.

ON

Turns on the function-key display line.

OFF

Turns off the function-key display line.

Example:

KEY 4, "MENU" + CHR$(13)
KEY LIST
KEY 4, ""
KEY LIST

See also KEY, ON KEY (Event Trapping)

LPOS

LPOS(n%)

n%

Indicates one of the printer ports: 0 = LPT1, 1 = LPT1, 2 = LPT2, 3 = LPT3

Example:

'This example requires a printer.
LPRINT
FOR i% = 1 TO 20
  LPRINT i%;
  IF LPOS(1) >= 10 THEN LPRINT     'Begin a new line.
NEXT i%

PRINT / LPRINT

PRINT [#filenumber%,] [expressionlist] [{; | ,}]
LPRINT [expressionlist] [{; | ,}]

filenumber%

The number of an open file. If you don't specify a file number, PRINT writes to the screen.

expressionlist

A list of one or more numeric or string expressions to print.

{; | ,}

Determines where the next output begins:
; means print immediately after the last value.
, means print at the start of the next print zone.
PRINT zones are 14 characters wide.

Example:

OPEN "TEST.DAT" FOR OUTPUT AS #1
PRINT #1, USING "##.###  "; 12.12345
CLOSE
OPEN "TEST.DAT" FOR INPUT AS #1
INPUT #1, a$
PRINT a$
LPRINT "This is a line"; 1
LPRINT "This is a line",
LPRINT 2

See also PRINT USING, LPRINT USING   WIDTH   WRITE

PRINT USING / LPRINT USING

PRINT [#filenumber%,] USING formatstring$; expressionlist [{; | ,}]
LPRINT USING formatstring$; expressionlist [{; | ,}]

filenumber%

The number of an open sequential file.

formatstring$;

A string expression containing one or more format specifiers.

expressionlist

A list of one or more numeric or string expressions to print, separated by commas, semicolons, spaces, or tabs.

{; | ,}

Determines where the next output begins:
; means print immediately after the last value.
, means print at the start of the next print zone.
PRINT zones are 14 characters wide.

Example:

a = 123.4567
PRINT USING "###.##"; a
LPRINT USING "+###.####"; a
a$ = "ABCDEFG"
PRINT USING "!"; a$
LPRINT USING "\ \"; a$

See also PRINT, LPRINT   WIDTH

OPEN COM

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

n

The communications port to open (1 = COM1, 2 = COM2).

optlist1

The most-often-used communications parameters:
[baud] [,[parity] [,[data] [,[stop]]]]

baud

is the baud rate of the device to be opened:
75, 110, 150, 300, 600, 1200, 2400, 4800, 9600

parity

is the method of parity checking:
N (none)   E (even)   O (odd)   S (space)   M (mark)   PE (enable error checking)

DATA

is the number of data bits per byte:
5, 6, 7, 8

stop

is the number of stop bits:
1, 1.5, 2

Defaults: 300 baud, even parity, 7 data bits, 1 stop bit.

optlist2

A list of less-often-used parameters, separated by commas:

Option	Description
ASC	Opens the device in ASCII mode.
BIN	Opens the device in binary mode.
CD[m]	Sets the timeout period (in milliseconds) on the DATA Carrier Detect (DCD) line.
CS[m]	Sets the timeout period (in milliseconds) on the Clear to Send (CTS) line.
DS[m]	Sets the timeout period (in milliseconds) on the DATA Set Ready (DS) line.
LF	Sends a line-feed character after a carriage return.
OP[m]	Specifies how long (in milliseconds) OPEN COM waits for all communications lines to become open.
RB[n]	Sets the size (in bytes) of the receive buffer.
RS	Suppresses detection of Request to Send (RTS).
TB[n]	Sets the size (in bytes) of the transmit buffer.

mode

INPUT, OUTPUT, or RANDOM (the default). See OPEN Statement File Modes .

filenum%

A number in the range 1 through 255 that identifies the communications channel as long as it is open.

reclen%

Random-access-mode buffer size (default is 128 bytes).

Example:

'Use this example for trouble shooting serial communications problems.
'Slow baud, hardware handshaking is ignored and buffers are enlarged.
OPEN "COM1:300,N,8,1,CD0,CS0,DS0,OP0,RS,TB2048,RB2048" FOR RANDOM AS #1

See also OPEN

SPC

SPC(n%)

n%

The number of spaces to skip; a value in the range 0 through 32,767!

Example:

PRINT "Text1"; SPC(10); "Text2"

See also PRINT, LPRINT   PRINT USING, LPRINT USING   SPACE$   TAB

SCREEN function

SCREEN (row%,column% [,colorflag%])

row%

The row coordinate of a character.

column%

The column coordinate of a character.

colorflag%

A value (0 or 1) that specifies what is returned.

Value	Returns
0 (or omitted)	The character's ASCII code.
1	The character's color attribute.

Example:

CLS
PRINT "Hello"
PRINT "The ASCII value of character at 1,1 is"; SCREEN(1, 1)

See also POINT   SCREEN Statement   ASCII Character Codes   Color Attributes and Values

TAB

TAB(column%)

column%

The column number of the new print position.

Example:

PRINT TAB(25); "Text"

See also PRINT, LPRINT   PRINT USING, LPRINT USING   SPC   SPACE$

VIEW PRINT

VIEW PRINT [toprow% TO bottomrow%]

toprow%

The number of the top row of the text viewport.

bottomrow%

The number of the bottom row of the text viewport.

If you omit the toprow% and bottomrow% arguments, VIEW PRINT sets the entire screen as the text viewport.

Ranges for toprow% and bottomrow% depend on the screen mode.

Example:

VIEW PRINT 10 TO 15
FOR i% = 1 TO 100      'Output will scroll.
  PRINT i%
NEXT i%

See also CLS   LOCATE   PRINT, LPRINT   SCREEN   WIDTH   Screen Modes

WAIT

WAIT portnumber%, AND-expression% [,XOR-expression%]

portnumber%

The number of the input port.

AND-expression%

An integer expression that WAIT combines with the bit pattern value using an AND operator. When the result is nonzero, WAIT stops monitoring the port.

XOR-expression%

Can be used to turn line bits on and off in the bit pattern before the AND operation is applied.

Example:

'Reads the interrupt controller port address &H20.
'Press any key to continue.
WAIT &H20, 1

See also INP, OUT   Boolean Operators

WIDTH

WIDTH [columns%] [,rows%]
WIDTH {#filenumber% | device$}, columns%
WIDTH LPRINT columns%

columns%

The desired width in columns. Screen display width must be 40 or 80 columns.

rows%

The desired screen-display height in rows. The value can be 25, 30, 43, 50, or 60, depending on your display adapter and screen mode.

#filenumber%

The number of an open file or device.

device$

The name of a device: SCRN:, COM1:, COM2:, LPT1:, LPT2:, LPT3:

Example:

OPEN "LPT1:" FOR OUTPUT AS #1
WIDTH #1, 132

See also PRINT, LPRINT   SCREEN   VIEW PRINT

CIRCLE

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

STEP

Specifies that coordinates are relative to the current graphics cursor position.

(x!,y!)

The coordinates for the center of the circle or ellipse.

radius!

The radius of the circle or ellipse in the units of the current coordinate system, determined by the most recent SCREEN, VIEW, and WINDOW statements.

color%

A color attribute that sets the circle's color. The available color attributes depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

start!

The starting angle for the arc, in radians.

end!

The ending angle for the arc, in radians.

aspect!

The ratio of the length of the y axis to the length of the x axis, used to draw ellipses.

To convert from degrees to radians, multiply degrees by (PI / 180).

Example:

'This example requires a color graphics adapter.
SCREEN 2
CIRCLE (320, 100), 200
CIRCLE STEP(0, 0), 100

See also COLOR   DRAW   LINE   SCREEN   VIEW   WINDOW   Color Attributes and Values   Screen Modes

COLOR

COLOR [foreground%] [,[background%] [,border%]]   (Screen mode 0 (text only))
COLOR [background%] [,palette%]   (Screen mode 1)
COLOR [foreground%]   (Screen modes 4, 12, 13)
COLOR [foreground%] [,background&]   (Screen modes 7-10)

foreground%

foreground&

A number that sets the foreground screen color. In screen mode 0, foreground% is a color attribute that sets the text color. In other screen modes, foreground% a color attribute or 4-bit color value (screen mode 4 only) that sets the text and line-drawing color.

background%

background&

A number that sets the background screen color. In screen mode 0, background% is a color attribute. In screen mode 1, background% is a 4-bit color value. In screen modes 7-10, background& is a color value.

border%

A color attribute that sets the screen border color.

palette%

A number (0 or 1) that specifies which of two sets of color attributes to use:

palette%	Attribute 1	Attribute 2	Attribute 3
0	Green	Red	Brown
1	Cyan	Magenta	Bright white

The available color attributes and values depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

If your system is equipped with an EGA, VGA, or MCGA adapter, use the PALETTE statement to change the color assignments of color attributes.

Example:

'This example requires a color graphics adapter.
SCREEN 7
FOR i% = 0 TO 15
  COLOR i%
  PRINT i%
NEXT i%

See also DRAW   PAINT   PALETTE, PALETTE USING   SCREEN   Color Attributes and Values   Screen Modes

GET / PUT

GET [STEP](x1!,y1!)-[STEP](x2!,y2!), arrayname[(index%)]
PUT [STEP] (x1!,y1!), arrayname[(index%)] [,actionverb]

STEP

Specifies that coordinates are relative to the current graphics cursor position.

(x1!,y1!)

The upper-left coordinates of the image captured by GET or of the screen location where PUT displays the image.

(x2!,y2!)

The lower-right coordinates of the captured image.

arrayname

The name of the array where the image is stored. See Screen Image Arrays and Compatibility to determine the required size of the array.

index%

The array index at which storage of the image begins.

actionverb

A keyword indicating how the image is displayed:

Keyword	Action
AND	Merges stored image with an existing image.
OR	Superimposes stored image on existing image.
PSET	Draws stored image, erasing existing image.
PRESET	Draws stored image in reverse colors, erasing existing image.
XOR	Draws a stored image or erases a previously drawn image while preserving the background, producing animation effects.

A PUT statement should always be executed in the same screen mode as the GET statement used to capture the image, or a compatible mode. See Screen Image Arrays and Compatibility.

Example:

'This example requires a color graphics adapter.
SCREEN 1
DIM box%(1 TO 200)
x1% = 0: x2% = 10: y1% = 0: y2% = 10
LINE (x1%, y1%)-(x2%, y2%), 2, BF
GET (x1%, y1%)-(x2%, y2%), box%
DO
  PUT (x1%, y1%), box%, XOR
  x1% = RND * 300
  y1% = RND * 180
  PUT (x1%, y1%), box%
LOOP WHILE INKEY$ = ""

See also SCREEN   Screen Modes

LINE

LINE [[STEP](x1!,y1!)]-[STEP](x2!,y2!) [,[color%] [,[B | BF] [,style%]]]

STEP

Specifies that coordinates are relative to the current graphics cursor position.

(x1!,y1!),

(x2!,y2!)

The screen coordinates of the start of the line and of the end of the line.

color%

A color attribute that sets the color of the line or rectangle. The available color attributes depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

B

Draws a rectangle instead of a line.

BF

Draws a filled box.

style%

A 16-bit value whose bits set whether or not pixels are drawn. Use to draw dashed or dotted lines.

Example:

'This example requires a color graphics adapter.
SCREEN 1
LINE (110, 70)-(190, 120), , B
LINE (0, 0)-(320, 200), 3, , &HFF00

See also CIRCLE   INPUT, LINE INPUT   PRESET, PSET   SCREEN   Color Attributes and Values   Screen Modes

PAINT

PAINT [STEP] (x!,y!)[,[{color% | tile$}] [,[bordercolor%] [,background$]]]

STEP

Specifies that coordinates are relative to the current graphics cursor position.

(x!,y!)

The screen coordinates where painting begins.

color%

A color attribute that sets the fill color.

tile$

A fill pattern that is 8 bits wide and up to 64 bytes long, defined as follows:
tile$ = CHR$(arg1) + CHR$(arg2) + ... + CHR$(argn%)
The arguments to CHR$ are numbers between 0 and 255. Each CHR$(argn%) defines a 1-byte, 8-pixel slice of the pattern based on the binary form of the number.

bordercolor%

A color attribute that specifies the color of the filled area's border. PAINT stops filling an area when it encounters a border of the specified color.

background$

A 1-byte, 8-pixel background tile slice. Specifying a background tile slice allows you to paint over an area that has already been painted.

The available color attributes depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

Example:

'This example requires a color graphics adapter.
SCREEN 1
CIRCLE (106, 100), 75, 1
LINE (138, 35)-(288, 165), 1, B
PAINT (160, 100), 2, 1

See also ASC, CHR$   CIRCLE   DRAW   LINE   SCREEN   Color Attributes and Values   Screen Modes

PALETTE / PALETTE USING

PALETTE [attribute%,color&]
PALETTE USING arrayname#((index%))

attribute%

The color attribute to change.

color&

A color value to assign to an attribute.

arrayname#

An array of color values to assign to the current screen Mode's set of attributes. The array must be large enough to assign colors to all the attributes.

index%

The index of the first array element to assign to an attribute.

The available color attributes and values depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

Example:

'This example requires a color graphics adapter.
PALETTE 0, 1
SCREEN 1
FOR i% = 0 TO 3: A%(i%) = i%: NEXT i%
LINE (138, 35)-(288, 165), 3, BF
LINE (20, 10)-(160, 100), 2, BF
DO
  FOR i% = 0 TO 3
    A%(i%) = (A%(i%) + 1) MOD 16
  NEXT i%
  PALETTE USING A%(0)
LOOP WHILE INKEY$ = ""

See also COLOR   SCREEN   Color Attributes and Values   Screen Modes

PCOPY

PCOPY sourcepage%, destinationpage%

sourcepage%

The number of a video memory page to copy.

destinationpage%

The number of the video memory page to copy to.

The value that identifies the video page is determined by the size of video memory and the current screen mode.

Example:

PCOPY 1, 3

See also SCREEN   Screen Modes

PMAP

PMAP (startcoordinate#, n%)

startcoordinate#

A window or viewport coordinate.

n%

A value indicating which coordinate is returned:

startcoordinate#	n%	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

Example:

'This example requires a graphics adapter that supports screen mode 1.
SCREEN 1
WINDOW SCREEN (0, 0)-(100, 100)
PRINT "Logical x=50, physical x="; PMAP(50, 0)
PRINT "Logical y=50, physical y="; PMAP(50, 1)

See also POINT   VIEW   WINDOW

POINT

POINT {(n%) | (x%,y%)}

(n%)

Indicates the type of coordinate to return:

n%	Returns
0	The current viewport x coordinate
1	The current viewport y coordinate
2	The current window x coordinate
3	The current window y coordinate

(x%,y%)

The coordinates of the pixel that POINT checks for color. If the coordinates are outside the current viewport, POINT returns -1.

Example:

'This example requires a color graphics adapter.
SCREEN 1
LINE (0, 0)-(100, 100), 2
LOCATE 14, 1
FOR y% = 1 TO 10
  FOR x% = 1 TO 10
    PRINT POINT(x%, y%);
  NEXT x%
  PRINT
NEXT y%

See also COLOR   PMAP   SCREEN   VIEW   WINDOW   Color Attributes and Values

PRESET / PSET

PRESET [STEP] (x!,y!) [,color%]
PSET [STEP] (x!,y!) [,color%]

STEP

Specifies that the x! and y! are expressed relative to the current graphics cursor location.

(x!,y!)

The screen coordinates of the pixel to be set.

color%

A color attribute that sets the pixel color. If color% is omitted, PRESET uses the current background and PSET uses the current foreground color.

Available color attributes depend on your graphics adapter and screen mode. Coordinate values depend on the graphics adapter, screen mode, and most recent VIEW and WINDOW statements.

Example:

'This example requires a color graphics adapter.
SCREEN 1
FOR i% = 0 TO 320
  PSET (i%, 100)
  FOR delay% = 1 TO 100: NEXT delay%
  PRESET (i%, 100)
NEXT i%

See also SCREEN   VIEW   WINDOW   Color Attributes and Values   Screen Modes

SCREEN statement

SCREEN mode% [,[colorswitch%] [,[activepage%] [,visualpage%]]]

mode%

Sets the screen mode. See Screen Modes.

colorswitch%

A value (0 or 1) that switches between color and monocolor display (modes 0 and 1 only):

Mode	Value	Action
0	0	Disables color
0	Nonzero	Enables color
1	0	Enables color
1	Nonzero	Disables color

activepage%

The screen page that text or graphics output writes to.

visualpage%

The screen page that is currently displayed on your screen.

Example:

'This example requires a color graphics adapter.
SCREEN 1        '320 x 200 graphics
LINE (110, 70)-(190, 120), , B
LINE (0, 0)-(320, 200), 3, , &HFF00

See also CIRCLE   COLOR   DRAW   LINE   PAINT   SCREEN Function   VIEW   WINDOW   Screen Modes

VIEW

VIEW [[SCREEN] (x1!,y1!)-(x2!,y2!) [,[color%] [,border%]]]

SCREEN

Specifies that coordinates are relative to the screen rather than the viewport.

(x1!,y1!)-(x2!,y2!)

The coordinates of diagonally opposite corners of the viewport.

color%

A color attribute that sets the viewport fill color.

border%

A color attribute that sets the viewport border color.

If all arguments are omitted, the entire screen is the viewport.

The available color attributes depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.

Example:

'This example requires a color graphics adapter.
SCREEN 1
VIEW (10, 10)-(300, 180), , 1
LOCATE 1, 11: PRINT "A big graphics viewport";
VIEW SCREEN (80, 80)-(200, 125), , 1
LOCATE 11, 11: PRINT "A small graphics viewport";

See also CLS   SCREEN   VIEW PRINT   WINDOW   Color Attributes and Values   Screen Modes

WINDOW

WINDOW [[SCREEN] (x1!,y1!)-(x2!,y2!)]

SCREEN

Inverts the normal Cartesian direction of the y screen coordinates so that y values increase from the top of the screen to the bottom.

(x1!,y1!)

Logical coordinates that map to the upper-left screen coordinates of the viewport.

(x2!,y2!)

Logical coordinates that map to the lower-right screen coordinates of the viewport.

WINDOW with no arguments disables the logical coordinate system.

Use the VIEW statement to change the size of the viewport.

Example:

'This example requires a color graphics adapter.
SCREEN 1
FOR i% = 1 TO 10 STEP 2
  WINDOW (-160 / i%, -100 / i%)-(160 / i%, 100 / i%)
  CIRCLE (0, 0), 10
NEXT i%

See also CLS   PMAP   POINT   SCREEN   VIEW   WIDTH

CHDIR / MKDIR / RMDIR / FILES

CHDIR pathname$
MKDIR pathname$
RMDIR pathname$
FILES [filespec$]

pathname$

The path of the new default directory, subdirectory to create, or subdirectory to remove.

filespec$

A filename or path (may include a drive and DOS wildcard characters). If you don't specify a filespec$, FILES displays all files in the current directory.

Example:

MKDIR "C:\TEMP\TEST"
CHDIR "C:\TEMP"
FILES
RMDIR "TEST"

KILL

KILL filespec$

filespec$

Identifies the file or files to delete. It may include a path and the DOS wildcard characters ? and *.

Example:

INPUT "File to delete: "; f$
KILL f$

See also FILES

NAME

NAME oldspec$ AS newspec$

oldspec$ and newspec$

The name of an existing file and the new name for the file. Each name may include a path.

Example:

INPUT "Old Name: "; OldFN$
INPUT "New Name: "; NewFN$
NAME OldFN$ AS NewFN$

See also FILES

CLOSE

CLOSE [[#]filenumber%[,[#]filenumber%]...]

filenumber%

The number of an open file or device.

CLOSE with no arguments closes all open files and devices.

Example:

CLS
INPUT "Enter filename: ", n$
OPEN n$ FOR OUTPUT AS #1
PRINT #1, "This is saved to the file."
CLOSE
OPEN n$ FOR INPUT AS #1
INPUT #1, a$
PRINT "Read from file: "; a$
CLOSE

See also END   OPEN   RESET   STOP

EOF

EOF(filenumber%)

filenumber%

The number of an open file.

Example:

CLS
OPEN "TEST.DAT" FOR OUTPUT AS #1
FOR I% = 1 TO 10
  WRITE #1, I%, 2 * I%, 5 * I%
NEXT I%
CLOSE #1
OPEN "TEST.DAT" FOR INPUT AS #1
DO
  LINE INPUT #1, a$
  PRINT a$
LOOP UNTIL (EOF(1))

See also CLOSE   LOC   LOF   OPEN

FILEATTR

FILEATTR(filenumber%,attribute%)

filenumber%

The number of an open file.

attribute%

Specifies the type of information to return. When attribute% is 1, FILEATTR returns a value indicating the File's access mode:

Value	mode
1	Input
2	Output
4	Random
8	Append
32	Binary

When attribute% is 2, FILEATTR returns the DOS file handle.

Example:

OPEN "TEST.DAT" FOR BINARY AS #1
PRINT FILEATTR(1, 1)
CLOSE

See also OPEN

FREEFILE

FREEFILE

Example:

OPEN "TEST.DAT" FOR OUTPUT AS #1
PRINT "Next file number: "; FREEFILE
CLOSE

See also OPEN

GET / PUT

GET [#]filenumber%[,[recordnumber&][,variable]]
PUT [#]filenumber%[,[recordnumber&][,variable]]

filenumber%

The number of an open file.

recordnumber&

For random-access files, the number of the record to read or write. For binary-mode files, the byte position where reading or writing starts.

variable

For GET, a variable used to receive input from the file. For PUT, a variable that contains output to write to the file. The variable is usually a variable of a user-defined data type.

Example:

TYPE TestRecord
  Student AS STRING * 20
  Score AS SINGLE
END TYPE
DIM MyClass AS TestRecord
OPEN "FINAL.DAT" FOR RANDOM AS #1 LEN = LEN(MyClass)
MyClass.Student = "MarySa"
MyClass.Score = 99
PUT #1, 1, MyClass
CLOSE #1
OPEN "FINAL.DAT" FOR RANDOM AS #1 LEN = LEN(MyClass)
GET #1, 1, MyClass
PRINT "STUDENT:", MyClass.Student
PRINT "SCORE:", MyClass.Score
CLOSE #1
KILL "FINAL.DAT"

See also FIELD   GET, PUT (Graphics)   LSET, RSET   MKn$, CVn Functions   TYPE

INPUT$

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

n

The number of characters (bytes) to read.

filenumber%

The number of an open file. If filenumber% is omitted, INPUT$ reads from the keyboard.

Example:

OPEN "TEST.DAT" FOR OUTPUT AS #1
PRINT #1, "The text"
CLOSE
OPEN "TEST.DAT" FOR INPUT AS #1
PRINT INPUT$(3, 1)        'Print first 3 characters.
CLOSE

See also INPUT, LINE INPUT

LOC

LOC(filenumber%)

filenumber%

The number of an open file or device.

For binary files, LOC returns the position of the last byte read or written.

For random-access files, LOC returns the number of the last record read from or written to the file.

For sequential files, LOC returns the current byte position in the file, divided by 128.

Example:

OPEN "TEST.DAT" FOR RANDOM AS #1
FOR i% = 1 TO 10
  PUT #1, , i%
NEXT i%
SEEK #1, 2
GET #1, , i%
PRINT "Data: "; i%; " Current record: "; LOC(1); " Next: "; SEEK(1)

See also EOF   SEEK

LOCK / UNLOCK

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

filenumber%

The number of an open file.

record&

For random-access files, the number of a record to lock, relative to the first record in the file. For binary files, the number of a byte to lock, relative to the first byte in the file.

start& and end&

The numbers of the first and last records or bytes in a range of records or bytes to lock or unlock.

For sequential files, LOCK and UNLOCK affect the entire file.

Example:

'This example runs only in a network environment.
OPEN "TEST.DAT" FOR RANDOM AS #1
FOR i% = 1 TO 10
  PUT #1, , i%
NEXT i%
LOCK #1, 2         'Lock record 2.
GET #1, 2, i%
UNLOCK #1, 2       'Unlock record 2.

LOF

LOF(filenumber%)

filenumber%

The number of an open file.

Example:

INPUT "Enter filename: "; f$
OPEN f$ FOR BINARY AS #1
PRINT "File length = "; LOF(1)
CLOSE

OPEN

OPEN file$ [FOR mode] [ACCESS access] [lock] AS [#]filenumber% [LEN=reclen%]

file$

The name of the file or device. The file name may include a drive and path.

mode

One of the following file modes: APPEND, BINARY, INPUT, OUTPUT, or RANDOM. See OPEN Statement File Modes.

access

In network environments, specifies whether the file is opened for READ, WRITE, or READ WRITE access. See OPEN Statement ACCESS Clause.

lock

Specifies the file locking in network environments: SHARED, LOCK READ, LOCK WRITE, LOCK READ WRITE.

filenumber%

A number in the range 1 through 255 that identifies the file while it is open.

reclen%

For random-access files, the record length (default is 128 bytes). For sequential files, the number of characters buffered (default is 512 bytes).

Example:

INPUT "Enter Filename: "; n$
OPEN n$ FOR OUTPUT AS #1
PRINT #1, "This is saved to the file."
CLOSE
OPEN n$ FOR INPUT AS #1
INPUT #1, a$
PRINT "Read from file: "; a$
CLOSE

See also CLOSE   FREEFILE   OPEN COM   TYPE   OPEN Statement Alternate Syntax

SEEK

SEEK(filenumber%)
SEEK [#]filenumber%, position&

filenumber%

The number of an open file.

position&

The position where the next read or write occurs. For random-access files, a record number. For other files, the byte position relative to the beginning of the file. The first byte is at position 1.

Example:

OPEN "TEST.DAT" FOR RANDOM AS #1
FOR i% = 1 TO 10
  PUT #1, , i%
NEXT i%
SEEK #1, 2
GET #1, , i%
PRINT "Data: "; i%; " Current record: "; LOC(1); " Next: "; SEEK(1)

See also GET, PUT   OPEN

WRITE

WRITE [[#]filenumber%,] expressionlist

filenumber%

The number of an open sequential file. If the file number is omitted, WRITE writes to the screen.

expressionlist

One or more variables or expressions, separated by commas, whose values are written to the screen or file.

WRITE inserts commas between items and quotation marks around strings as they are written. WRITE writes values to a file in a form that can be read by the INPUT statement.

Example:

CLS
OPEN "LIST" FOR OUTPUT AS #1
DO
  INPUT "   NAME:       ", Name$
  INPUT "   AGE:        ", Age$
  WRITE #1, Name$, Age$
  INPUT "Add another entry"; R$
LOOP WHILE UCASE$(R$) = "Y"
CLOSE #1
'Print the file to the screen.
OPEN "LIST" FOR INPUT AS #1
CLS
PRINT "Entries in file:": PRINT
DO WHILE NOT EOF(1)
  INPUT #1, Rec1$, Rec2$   'Read entries from file.
  PRINT Rec1$, Rec2$       'Print the entries on the screen.
LOOP
CLOSE #1
KILL "LIST"

See also INPUT, LINE INPUT   OPEN   PRINT, LPRINT

CLEAR

CLEAR [,,stack&]

stack&

Sets the size (in bytes) of stack space for your program.

Example:

CLEAR ,,2000

See also ERASE

FRE

FRE(numeric-expression)
FRE(stringexpression$)

numeric-expression

A value that specifies the type of memory:

Value	FRE returns
-1	The size of the largest array (nonstring) you can create
-2	The unused stack space
Any other number	The available string space

stringexpression$

Any string expression. FRE compacts the free string space into a single block, then returns the amount of available string space.

Example:

PRINT "String Space", FRE("")
PRINT "Unused Stack Space", FRE(-2)
PRINT "Array Space", FRE(-1)

PEEK / POKE

PEEK(address)
POKE address,byte%

address

A byte position relative to the current segment address set by DEF SEG; a value in the range 0 through 65,535.

byte%

A byte value to write to the specified memory location; a value in the range 0 through 255.

Example:

DEF SEG = 0
Status% = PEEK(&H417)              'Read keyboard status.
POKE &H417, (Status% XOR &H40)     'Change Caps Lock state, bit 6.

See also DEF SEG

HEX$ / OCT$

HEX$(numeric-expression&)
OCT$(numeric-expression&)

numeric-expression&

Any numeric expression. The expression is rounded to an integer or long integer before it is evaluated.

Example:

INPUT x
a$ = HEX$ (x)
b$ = OCT$ (x)
PRINT x; "decimal is "; a$; " hexadecimal and "; b$; " in octal."

INSTR

INSTR([start%,]stringexpression1$,stringexpression2$)

start%

Sets the character position where the search begins. If start% is omitted, INSTR starts at position 1.

stringexpression1$

The string to search.

stringexpression2$

The string to look for.

Example:

a$ = "Microsoft QBasic"
PRINT "String position ="; INSTR(1, a$, "QBasic")

See also LEFT$, RIGHT$   LEN   MID$

LCASE$ / UCASE$

LCASE$(stringexpression$)
UCASE$(stringexpression$)

stringexpression$

Any string expression.

Example:

Test$ = "THE string"
PRINT Test$
PRINT LCASE$(Test$); " in lowercase"
PRINT UCASE$(Test$); " IN UPPERCASE"

LEFT$ / RIGHT$

LEFT$(stringexpression$,n%)
RIGHT$(stringexpression$,n%)

stringexpression$

Any string expression.

n%

The number of characters to return, beginning with the leftmost or rightmost string character.

Example:

a$ = "Microsoft QBasic"
PRINT LEFT$(a$, 5)     'Output is:  Micro
PRINT RIGHT$(a$, 5)    'Output is:  Basic

See also MID$

LEN

LEN(stringexpression$)
LEN(variable)

stringexpression$

Any string expression.

variable

Any nonstring variable.

Example:

a$ = "Microsoft QBasic"
PRINT LEN(a$)

See also OPEN

LSET / RSET

LSET stringvariable$=stringexpression$
RSET stringvariable$=stringexpression$
LSET recordvariable1=recordvariable2

stringvariable$

Any string variable or a random-access file field defined in a FIELD statement.

stringexpression$

For LSET, the left-justified version of stringvariable$. For RSET, the right-justified version of stringvariable$.

recordvariable1

recordvariable2

Record variables of any user-defined data type.
Use LSET to assign a record variable of one data type to a different user-defined data type.

Example:

OPEN "FILEDAT.DAT" FOR RANDOM AS #1 LEN = 10
FIELD #1, 5 AS Ls1$, 5 AS Rs1$
LSET Ls1$ = "LSET"
RSET Rs1$ = "RSET"
PUT #1, 1
CLOSE #1
OPEN "FILEDAT.DAT" FOR RANDOM AS #1 LEN = 10
FIELD #1, 5 AS Ls2$, 5 AS Rs2$
GET #1, 1
PRINT "*" + Ls2$ + "*", "*" + Rs2$ + "*"
CLOSE #1

See also FIELD   GET, PUT

LTRIM$ / RTRIM$

LTRIM$(stringexpression$)
RTRIM$(stringexpression$)

stringexpression$

Any string expression.

Example:

a$ = "    Basic    "
PRINT "*" + a$ + "*"            'Output is:  *    Basic    *
PRINT "*" + LTRIM$(a$) + "*"    'Output is:  *Basic    *
PRINT "*" + RTRIM$(a$) + "*"    'Output is:  *    Basic*

MID$

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

stringexpression$

The string from which the MID$ function returns a substring, or the replacement string used by the MID$ statement. It can be any string expression.

start%

The position of the first character in the substring being returned or replaced.

length%

The number of characters in the substring. If the length is omitted, MID$ returns or replaces all characters to the right of the start position.

stringvariable$

The string variable being modified by the MID$ statement.

Example:

a$ = "Where is Paris?"
PRINT MID$(a$, 10, 5)       'Output is:  Paris
Text$ = "Paris, France"
PRINT Text$                 'Output is:  Paris, France
MID$(Text$, 8) = "Texas "
PRINT Text$                 'Output is:  Paris, Texas

See also LEFT$, RIGHT$   LEN

SPACE$

SPACE$(n%)

n%

The number of spaces you want in the string.

Example:

FOR i% = 1 TO 5
  x$ = SPACE$ (i%)
  PRINT x$; i%
NEXT i%

See also SPC   STRING$

STR$ / VAL

STR$(numeric-expression)
VAL(stringexpression$)

numeric-expression

Any numeric expression.

stringexpression$

A string representation of a number.

Example:

PRINT "Decimal 65 is represented in hexadecimal as ";
PRINT "&H" + LTRIM$(STR$(41))
PRINT VAL(RIGHT$("Microsoft 1990", 4))

STRING$

STRING$(length%,{ascii-code% | stringexpression$})

length%

The length of the string.

ascii-code%

The ASCII code of the repeating character.

stringexpression$

Any string expression. STRING$ fills the string with the first character in stringexpression$.

Example:

PRINT STRING$(5, "-");
PRINT "Hello";
PRINT STRING$(5, "-")

See also ASCII Character Codes

ABS / SGN

ABS(numeric-expression)
SGN(numeric-expression)

numeric-expression

Any numeric expression.

Example:

PRINT ABS(45.5 - 100!)           'Output is:  54.5
PRINT SGN(1), SGN(-1), SGN(0)    'Output is:  1  -1  0

ASC / CHR$

ASC(stringexpression$)
CHR$(ascii-code%)

stringexpression$

Any string expression.

ascii-code%

The ASCII code of the desired character.

Example:

PRINT ASC("Q")    'Output is:  81
PRINT CHR$(65)    'Output is:  A

See also ASCII Character Codes

ATN / COS / SIN / TAN

ATN(numeric-expression)
COS(angle)
SIN(angle)
TAN(angle)

numeric-expression

The ratio between the sides of a right triangle.

angle

An angle expressed in radians.

The ATN function returns an angle in radians.

To convert from degrees to radians, multiply degrees by (PI / 180).

Example:

CONST PI=3.141592654
PRINT ATN(TAN(PI/4.0)), PI/4.0    'Output is:  .7853981635  .7853981635
PRINT (COS(180 * (PI / 180)))     'Output is:  -1
PRINT (SIN(90 * (PI / 180)))      'Output is:  1
PRINT (TAN(45 * (PI / 180)))      'Output is:  1.000000000205103

CDBL / CSNG

CDBL(numeric-expression)
CSNG(numeric-expression)

numeric-expression

Any numeric expression.

Example:

PRINT 1 / 3, CDBL(1 / 3)    'Output is:  .3333333  .3333333333333333
PRINT CSNG(975.3421515#)    'Output is:  975.3422

See also CINT, CLNG

CINT / CLNG

CINT(numeric-expression)
CLNG(numeric-expression)

numeric-expression

For CINT, any numeric expression in the range -32,768 through 32,767.
For CLNG, any numeric expression in the range -2,147,483,648 through 2,147,483,647.

Example:

PRINT CINT(12.49), CINT(12.51)    'Output is:  12  13
PRINT CLNG(338457.8)              'Output is:  338458

See also CDBL, CSNG   FIX, INT

MKSMBF$ / MKDMBF$ / CVSMBF / CVDMBF

MKSMBF$(single-precision-expression!)
MKDMBF$(double-precision-expression#)
CVSMBF (4-byte-numeric-string)
CVDMBF (8-byte-numeric-string)

Function	Returns
MKSMBF$	A 4-byte string containing a Microsoft-Binary-format number
MKDMBF$	An 8-byte string containing a Microsoft-Binary-format number
CVSMBF	A single-precision number in IEEE format
CVDMBF	A double-precision number in IEEE format

These functions are useful for maintaining data files created with older versions of Basic.

Example:

TYPE Buffer
  SngNum AS STRING * 4
  DblNum AS STRING * 8
END TYPE
DIM RecBuffer AS Buffer
OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN = 12
SNum = 98.9
DNum = 645.3235622#
RecBuffer.SngNum = MKSMBF$(SNum)
RecBuffer.DblNum = MKDMBF$(DNum)
PUT #1, 1, RecBuffer
GET #1, 1, RecBuffer
CLOSE #1
PRINT CVSMBF(RecBuffer.SngNum), CVDMBF(RecBuffer.DblNum)

See also FIELD   MKn$, CVn

EXP / LOG

EXP(numeric-expression)
LOG(numeric-expression)

numeric-expression

For EXP, a number less than or equal to 88.02969.
For LOG, any positive numeric expression.

Example:

PRINT EXP(0), EXP(1)         'Output is:  1  2.718282
PRINT LOG(1), LOG(EXP(1))    'Output is:  0  1

FIX / INT

FIX(numeric-expression)
INT(numeric-expression)

numeric-expression

Any numeric expression.

Example:

PRINT FIX(12.49), FIX(12.54)    'Output is:  12  12
PRINT INT(12.54), INT(-99.4)    'Output is:  12  -100

See also CINT, CLNG

RANDOMIZE / RND

RANDOMIZE [seed%]
RND[(n#)]

seed%

A number used to initialize the random-number generator. If omitted, RANDOMIZE prompts for it.

n#

A value that sets how RND generates the next random number:

n#	RND returns
Less than 0	The same number for any n#
Greater than 0 (or omitted)	The next random number
0	The last number generated

Example:

RANDOMIZE TIMER
x% = INT(RND * 6) + 1
y% = INT(RND * 6) + 1
PRINT "Roll of two dice: die 1 ="; x%; "and die 2 ="; y%

SQR

SQR(numeric-expression)

numeric-expression

A value greater than or equal to zero.

Example:

PRINT SQR(25), SQR(2)    'Output is:  5  1.414214

TIME$

TIME$
TIME$ = stringexpression$

stringexpression$

The time in one of the following forms:

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.

The TIME$ function returns a string in the form hh:mm:ss.

Example:

PRINT TIME$
TIME$ = "08:00:58"    'Note: The new system time remains in effect until
                      '      you change it again.
PRINT "Time set to "; TIME$

See also DATE$

COM / ON COM

COM(n%) ON
COM(n%) OFF
COM(n%) STOP
ON COM(n%) GOSUB line

n%

The number of a COM (serial) port (1 or 2).

COM(n%) ON

Enables trapping of a communications event.

COM(n%) OFF

Disables communications event trapping.

COM(n%) STOP

Suspends communications event trapping. Events are processed once event trapping is enabled by COM ON.

line

The label or number of the first line of the event-trapping subroutine.

Example:

COM(1) ON       'Enable event trapping on port 1.
ON COM(1) GOSUB ComHandler
DO : LOOP WHILE INKEY$ = ""
COM(1) OFF
END

ComHandler:
PRINT "Something was typed at the terminal attached to COM1."
RETURN

See also OPEN COM

ERDEV / ERDEV$

ERDEV
ERDEV$

The low byte of the value returned by ERDEV contains the DOS error code. The high byte contains device-attribute information.

Example

See also ERR, ERL   ON ERROR

ERR / ERL

ERR
ERL

ERL does not return line labels. If there are no line numbers in the program, ERL returns 0.

Example

See also ERDEV, ERDEV$   ERROR   ON ERROR   RESUME   Run-Time Error Codes

ERROR

ERROR expression%

expression%

The error code of a Basic or user-defined error; a value in the range 1 through 255. To define your own error, use a value that isn't listed in the Basic Run-Time Error Codes table.

Example

See also ERDEV, ERDEV$   ERR, ERL   ON ERROR   RESUME

KEY / ON KEY

KEY(n%) ON
KEY(n%) OFF
KEY(n%) STOP
ON KEY(n%) GOSUB line

n%

A value that specifies a function key, direction key, or user-defined key:

n%	Key
0	All keys listed here (KEY(0) ON, KEY(0) OFF, and KEY(0) STOP only).
1-10	Function keys F1-F10.
11	Up Arrow key.
12	Left Arrow key.
13	Right Arrow key.
14	Down Arrow key.
15-25	User-defined keys. For more information, see Declaring User-Defined Keys.
30, 31	Function keys F11 and F12.

KEY(n%) ON

Enables event trapping for the specified key.

KEY(n%) OFF

Disables key event trapping.

KEY(n%) STOP

Suspends key event trapping. Events are processed once event trapping is enabled by KEY ON.

line

The label or number of the first line of the event-trapping subroutine.

Example:

'This example requires Caps Lock and Num Lock to be off.
CONST ESC = 27
KEY 15, CHR$(&H4) + CHR$(&H1F)              'Set up Ctrl+S as KEY 15.
ON KEY(15) GOSUB PauseHandler
KEY(15) ON
WHILE INKEY$ <> CHR$(ESC)
  PRINT "Press Esc to stop, Ctrl+S to pause."
  PRINT
WEND
END

PauseHandler:
SLEEP 1
RETURN

See also KEY (Assignment)   Declaring User-Defined Keys

ON ERROR

ON ERROR {GOTO line | RESUME NEXT}

GOTO line

Branches to the first line of the error-handling routine, specified by a label or line number. To disable error handling, specify GOTO 0.

RESUME NEXT

Resumes execution with the statement following the statement that caused the run-time error. Use the ERR function to obtain the error code for the error.

If ON ERROR isn't used, any run-time error ends your program.

Example

See also ERDEV, ERDEV$   ERR, ERL   ERROR   GOTO   RESUME

PEN / ON PEN

PEN ON
PEN OFF
PEN STOP
ON PEN GOSUB line

PEN ON

Enables light-pen event trapping.

PEN OFF

Disables light-pen event trapping.

PEN STOP

Suspends light-pen event trapping. Events are processed once event trapping is enabled by PEN ON.

line

The label or number of the first line of the event-trapping subroutine.

Example:

'This example requires a light pen.
ON PEN GOSUB Handler
PEN ON
PRINT "Press Esc to exit."
DO UNTIL INKEY$ = CHR$(27): LOOP
END

Handler:
PRINT "Pen is at row"; PEN(6); ", column"; PEN(7)
RETURN

See also PEN Function

PLAY / ON PLAY

PLAY ON
PLAY OFF
PLAY STOP
ON PLAY(queuelimit%) GOSUB line

PLAY ON

Enables play event trapping.

PLAY OFF

Disables play event trapping.

PLAY STOP

Suspends play event trapping. Events are processed once event trapping is enabled by PLAY ON.

queuelimit%

A number in the range 1 through 32. ON PLAY branches to a subroutine when there are fewer than queuelimit% notes in the music buffer.

line

The label or number of the first line of the event-trapping subroutine.

Example:

ON PLAY(3) GOSUB Background
PLAY ON
Music$ = "MBo3L8ED+ED+Eo2Bo3DCL2o2A"
PLAY Music$
LOCATE 2, 1: PRINT "Press any key to stop.";
DO WHILE INKEY$ = "": LOOP
END

Background:
i% = i% + 1
LOCATE 1, 1: PRINT "Background called "; i%; "time(s)";
PLAY Music$
RETURN

See also PLAY (Music)   PLAY Function

STRIG / ON STRIG

STRIG(n%) ON
STRIG(n%) OFF
STRIG(n%) STOP
ON STRIG(n%) GOSUB line

n%

A value that specifies a joystick trigger:

n%	Trigger
0	Lower trigger, joystick A
2	Lower trigger, joystick B
4	Upper trigger, joystick A
6	Upper trigger, joystick B

STRIG(n%) ON

Enables joystick event trapping.

STRIG(n%) OFF

Disables joystick event trapping.

STRIG(n%) STOP

Suspends joystick event trapping. Events are processed once event trapping is enabled by STRIG ON.

line

The label or number of the first line of the event-trapping subroutine.

Example:

'This example requires a joystick.
ON STRIG(0) GOSUB Handler
STRIG(0) ON
PRINT "Press Esc to exit."
DO UNTIL INKEY$ = CHR$(27): LOOP
END

Handler:
PRINT "Joystick trigger is depressed."
RETURN

See also STICK   STRIG Function

TIMER / ON TIMER

TIMER ON
TIMER OFF
TIMER STOP
ON TIMER(n%) GOSUB line

TIMER ON

Enables timer event trapping.

TIMER OFF

Disables timer event trapping.

TIMER STOP

Suspends timer event trapping. Events are processed once event trapping is enabled by TIMER ON.

n%

The number of seconds that elapse before ON TIMER branches to the event-trapping subroutine; a value in the range 1 through 86,400 (24 hours).

line

The label or number of the first line of the event-trapping subroutine.

Example:

ON TIMER(1) GOSUB TimeUpdate
TIMER ON
CLS
PRINT "Time: "; TIME$
StartTime = TIMER
WHILE TimePast < 10
  TimePast = TIMER - StartTime
WEND
END

TimeUpdate:
LOCATE 1, 7: PRINT TIME$
RETURN

See also TIMER Function

PLAY

PLAY commandstring$

commandstring$

A string expression that contains one or more of the following PLAY commands:

Octave and tone commands:
Ooctave	Sets the current octave (0 - 6).
< or >	Moves up or down one octave.
A - G	Plays the specified note in the current octave.
Nnote	Plays a specified note (0 - 84) in the seven-octave range (0 is a rest).
Duration and tempo commands:
Llength	Sets the length of each note (1 - 64). L1 is whole note, L2 is a half note, etc.
ML	Sets music legato.
MN	Sets music normal.
MS	Sets music staccato.
Ppause	Specifies a pause (1 - 64). P1 is a whole-note pause, P2 is a half-note pause, etc.
Ttempo	Sets the tempo in quarter notes per minute (32 - 255).
Mode commands:
MF	Plays music in foreground.
MB	Plays music in background.
Suffix commands:
# or +	Turns preceding note into a sharp.
-	Turns preceding note into a flat.
.	Plays the preceding note 3/2 as long as specified.

To execute a PLAY command substring from a PLAY command string, use the "X" command:
PLAY "X"+ VARPTR$(commandstring$)

Example:

'Play scale in 7 different octaves
scale$ = "CDEFGAB"
PLAY "L16"
FOR i% = 0 TO 6
  PLAY "O" + STR$(i%)
  PLAY "X" + VARPTR$(scale$)
NEXT i%

See also BEEP   PLAY Function   PLAY, ON PLAY (Event Trapping)   SOUND   VARPTR$

RESUME

RESUME [{line | NEXT}]

line

The label or number of the line where execution resumes. If line is 0 or omitted, execution resumes with the statement that caused the error.

NEXT

Resumes execution at the statement following the statement that caused the error.

Example

See also ERROR   ON ERROR

TIMER function

TIMER

Use TIMER to time programs or parts of programs, or with the RANDOMIZE statement to seed the random-number generator.

Example:

RANDOMIZE TIMER

See also RANDOMIZE, RND   TIMER, ON TIMER Statements

BEEP

BEEP

Boolean Operators

result = expression1 boolean-operator expression2

boolean-operator

Any of the following Boolean operators:

NOT	Bit-wise complement
AND	Conjunction
OR	Disjunction (inclusive "or")
XOR	Exclusive "or"
EQV	Equivalence
IMP	Implication

Each operator returns results as indicated in the following truth table. T is true (nonzero); F is false (zero):

	NOT	AND	OR	XOR	EQV	IMP
Expression1	T F	T T F F	T T F F	T T F F	T T F F	T T F F
Expression2		T F T F	T F T F	T F T F	T F T F	T F T F
Result	F T	T F F F	T T T F	F T T F	T F F T	T F T T

Boolean operations are performed after arithmetic and relational operations in order of precedence.

Expressions are converted to integers or long integers before a Boolean operation is performed.

If the expressions evaluate to 0 or -1, a Boolean operation returns 0 or -1 as the result. Because Boolean operators do bit-wise calculations, using values other than 0 for false and -1 for true may produce unexpected results.

CALL ABSOLUTE

CALL ABSOLUTE ([argumentlist,] offset%)

argumentlist

Arguments passed to a machine-language procedure as offsets from the current data segment.

offset%

The offset from the current code segment, set by DEF SEG, to the starting location of the procedure.

Example:

'Calls routine for printing the screen to a local printer.
DIM a%(2)
DEF SEG = VARSEG(a%(0))
FOR I% = 0 TO 2
  READ D%
  POKE VARPTR(a%(0)) + I%, D%
NEXT I%
DATA 205, 5, 203  : ' int 5  retf  'Machine-language code
                                   'for printing screen.
CALL ABSOLUTE(VARPTR(a%(0)))
DEF SEG

See also CALL   VARPTR, VARSEG

CHAIN

CHAIN filespec$

filespec$

The name of the program to which control is passed.

Example:

'Assumes the program TEST.BAS is in a \DOS directory.
CHAIN "C:\DOS\TEST.BAS"

See also CALL   COMMON   RUN

Color Attributes And Values

(a) EGA color numbers. VGA and MCGA use display-color values that produce visually equivalent colors.
(b) For VGA or EGA with video memory > 64K.
(c) Only for mode 0.
(d) Off when used for background.
(e) EGA with video memory <= 64K.

See also COLOR   PALETTE, PALETTE USING   SCREEN   Screen Modes

COMMON

COMMON [SHARED] variablelist

SHARED

Indicates that variables are shared with all SUB or FUNCTION procedures.

variablelist

One or more variables to be shared:
variable[( )] [AS type] [, variable[( )] [AS type]]...

variable

A Basic variable name. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

type

The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

Unless it has been declared as a static array in a preceding DIM statement, an array variable in a COMMON statement is a dynamic array.
Its dimensions must be set in a later DIM or REDIM statement.

See also CHAIN   DIM, REDIM   FUNCTION   SHARED, STATIC   SUB

DATE$

DATE$
DATE$ = stringexpression$

stringexpression$

The date in one of the following forms: mm-dd-yy, mm-dd-yyyy, mm/dd/yy, mm/dd/yyyy.

The DATE$ function returns a string in the form mm-dd-yyyy.

Example:

PRINT DATE$
DATE$ = "01-01-90"    'Note: The new system date remains in effect until
                      '      you change it again.
PRINT "Date set to "; DATE$

See also TIME$

Declaring User Defined Keys

KEY n%, CHR$(keyboardflag%) + CHR$(scancode%)

n%

A value in the range 15 through 25 that identifies the key.

keyboardflag%

One of the following values, or a sum of values, specifying whether the user-defined key is used in combination with the Shift, Ctrl, Alt, NumLock, or Caps Lock keys, or with extended keys:

Value	Key
0	No keyboard flag
1 through 3	Either Shift key
4	Ctrl key
8	Alt key
32	NumLock key
64	Caps Lock key
128	Extended keys on a 101-key keyboard

To specify multiple shift states, add the values together. For example, a value of 12 specifies that the user-defined key is used in combination with the Ctrl and Alt keys.

scancode%

The scan code for the key being declared. See Keyboard Scan Codes.

See also KEY (Assignment)   KEY, ON KEY (Event Trapping)

DEF FN

DEF FNname[(parameterlist)] = expression
DEF FNname[(parameterlist)]
    [statementblock]
  FNname = expression
    [statementblock]
  EXIT DEF]
    [statementblock]
  END DEF

parameterlist

One or more arguments in the following form:
variable[( )] [AS type] [, variable[( )] [AS type]]...

variable

A Basic variable name.

type

The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).

expression

The return value of the function.

The FUNCTION statement provides a better way to define a function.

See also EXIT   FUNCTION   SHARED, STATIC

DEF SEG

DEF SEG [=address]

address

A segment address used by BLOAD, BSAVE, CALL ABSOLUTE, PEEK, or POKE; a value in the range 0 through 65,535. If address is omitted, DEF SEG resets the current segment address to the default data segment.

Example:

DEF SEG = 0
status% = PEEK(&H417)              'Read keyboard status.
POKE &H417, (status% XOR &H40)     'Change Caps Lock state, bit 6.

See also BSAVE, BLOAD   CALL ABSOLUTE   PEEK, POKE

DRAW

DRAW commandstring$

commandstring$

A string expression that contains one or more of the following DRAW commands.

Line-drawing and cursor-movement commands
D[n%]	Moves cursor down n% units.
E[n%]	Moves cursor up and right n% units.
F[n%]	Moves cursor down and right n% units.
G[n%]	Moves cursor down and left n% units.
H[n%]	Moves cursor up and left n% units.
L[n%]	Moves cursor left n% units.
M[{+|-}]x%,y%	Moves cursor to point x%,y%. If x% is preceded by + or -, moves relative to the current point.
R[n%]	Moves cursor right n% units.
U[n%]	Moves cursor up n% units.
[B]	Optional prefix that moves cursor without drawing.
[N]	Optional prefix that draws and returns cursor to its original position.
Color, rotation, and scale commands
An%	Rotates an object n% * 90 degrees (n% can be 0, 1, 2, or 3).
Cn%	Sets the drawing color (n% is a color attribute).
Pn1%,n2%	Sets the paint fill and border colors of an object (n1% is the fill-color attribute, n2% is the border-color attribute).
Sn%	Determines the drawing scale by setting the length of a unit of cursor movement. The default n% is 4, which is equivalent to 1 pixel.
TAn%	Turns an angle n% degrees (-360 through 360).

If you omit n% from line-drawing and cursor-movement commands, the cursor moves 1 unit.

To execute a DRAW command substring from a DRAW command string, use the "X" command:
DRAW "X" + VARPTR$(commandstring$)

Example:

'This example requires a color graphics adapter.
SCREEN 1
Triangle$ = "F60 L120 E60"
DRAW "C2 X" + VARPTR$(Triangle$)
DRAW "BD30 P1,2 C3 M-30,-30"

See also PALETTE, PALETTE USING   SCREEN   VARPTR$   Color Attributes and Values

FIELD

FIELD [#]filenumber%, fieldwidth% AS stringvariable$ [,fieldwidth% AS stringvariable$] ...

filenumber%

The number of an open file.

fieldwidth%

The number of characters in the field.

stringvariable$

A variable that identifies the field and contains field data.

Record variables usually provide a better way to handle record data.

Example:

OPEN "FILEDAT.DAT" FOR RANDOM AS #1 LEN = 80
FIELD #1, 30 AS name$, 50 AS address$

See also GET, PUT   LSET, RSET   TYPE

Format Specifiers

Keyboard Codes

LBOUND / UBOUND

LBOUND(array[,dimension%])
UBOUND(array[,dimension%])

array

The name of the array.

dimension%

Indicates the array dimension whose lower or upper bound is returned. Use 1 for the first dimension, 2 for the second dimension, etc. The default is 1.

Example:

DIM a%(1 TO 3, 2 TO 7)
PRINT LBOUND(a%, 1), UBOUND(a%, 2)

See also DIM, REDIM

Open Statement Access Clause

ACCESS {READ | WRITE | READ WRITE}

READ

Opens a file for reading only.

WRITE

Opens a file for writing only.

READ WRITE

Opens a file for both reading and writing. READ WRITE mode is valid only for random-access and binary-mode files, and files opened for APPEND (sequential access).

See also OPEN

Open Statement Alternate Syntax

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

mode2$

A string expression that begins with one of the following characters and specifies the file mode:

O

Sequential output mode.

I

Sequential input mode.

R

Random-access file input/output 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.

filenum%

A number in the range 1 through 255 that identifies the file while it is open.

file$

The name of the file (may include drive and path).

reclen%

For random-access files, the record length in bytes. For sequential files, the number of characters buffered.

QBasic supports this syntax for compatibility with programs written in earlier versions of BASIC.

See also OPEN

Open Statement File Modes

APPEND

specifies that the file is to be opened for sequential output and sets the file pointer to the end of the file. A PRINT # or WRITE # statement then extends (appends to) the file.

BINARY

specifies a binary-file mode. In binary mode, you can read or write information to any byte position in the file using GET or PUT statements.

INPUT

specifies that the file is opened for sequential input.

OUTPUT

specifies that the file is opened for sequential output.

RANDOM

specifies that the file is opened in random-access file mode. RANDOM is the default file mode.

See also OPEN   OPEN COM   PRINT, LPRINT   WRITE

PEN Function

PEN(n%)

n%

Specifies the information to be returned about light pen status:

n%	Returns
0	Whether pen was used since last call (-1 if yes, 0 if no)
1	The x screen coordinate of the last pen press
2	The y screen coordinate of the last pen press
3	The current pen switch status (-1 if down, 0 if up)
4	The x screen coordinate where the pen last left the screen
5	The y screen 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

Example:

DO
  P = PEN(3)
  LOCATE 1, 1: PRINT "Pen is ";
  IF P THEN PRINT "down" ELSE PRINT "up  "
  PRINT "X ="; PEN(4), " Y ="; PEN(5); "  "
LOOP

See also PEN, ON PEN Statements   SCREEN   Screen Modes

PLAY Function

PLAY (n)

n

Any numeric expression.

Example:

Music$ = "MBT180o2P2P8L8GGGL2E-P24P8L8FFFL2D"
PLAY Music$
WHILE PLAY(0) > 5: WEND
PRINT "Just about done!"

See also PLAY (Music)   PLAY, ON PLAY (Event Trapping)

RESET

RESET

See also CLOSE   END   OPEN   STOP

Runtime Error Codes

Code	Message	Code	Message
1	NEXT without FOR	37	Argument-count mismatch
2	Syntax error	38	Array not defined
3	RETURN without GOSUB	40	Variable required
4	Out of DATA	50	FIELD overflow
5	Illegal function call	51	Internal error
6	Overflow	52	Bad file name or number
7	Out of memory	53	File not found
8	Label not defined	54	Bad file mode
9	Subscript out of range	55	File already open
10	Duplicate definition	56	FIELD statement active
11	Division by zero	57	Device I/O error
12	Illegal in direct mode	58	File already exists
13	Type mismatch	59	Bad record length
14	Out of string space	61	Disk full
16	String formula too complex	62	Input past end of file
17	Cannot continue	63	Bad record number
18	Function not defined	64	Bad file name
19	No RESUME	67	Too many files
20	RESUME without error	68	Device unavailable
24	Device timeout	69	Communication-buffer overflow
25	Device fault	70	Permission denied
26	FOR without NEXT	71	Disk not ready
27	Out of paper	72	Disk-media error
29	WHILE without WEND	73	Feature unavailable
30	WEND without WHILE	74	Rename across disks
33	Duplicate label	75	Path/File access error
35	Subprogram not defined	76	Path not found

Screen Image Arrays And Compatibility

Use bits-per-pixel-per-plane and planes values to determine the required size of the array that holds a graphics screen image. Bits-per-pixel-per-plane and planes values, along with the horizontal resolution, also determine which screen modes are compatibile:

Screen mode	Bits-per-pixel -per-plane	Planes	Horizontal resolution (in pixels)
1	2	1	320
2, 4, 11	1	1	640
3	1	1	720
7	1	4	320
8, 9(> 64K video memory), 12	1	4	640
9(64K video memory), 10	1	2	640
13	8	1	320

The following formula gives the required size, in bytes, of an array used to hold a captured image:

size% = 4 + INT(((PMAP (x2!, 0) - PMAP (x1!, 0) + 1) * (bits-per-pixel-per-plane%) + 7) / 8) * planes% * (PMAP (y2!, 1) - PMAP (y1!, 1) + 1)

GET and PUT operations are compatible in screen modes with the same horizontal resolution and bits-per-pixel-per-plane and planes values. For example, screen modes 2, 4, and 11 are compatible, and screen modes 8 and 12 are compatible.

See also SCREEN   Screen Modes

Screen Modes

SCREEN 0: Text mode only
40 x 25, 40 x 43, 40 x 50, 80 x 25, 80 x 43, or 80 x 50 text format, 8 x 8 character box (8 x 14, 9 x 14, or 9 x 16 with EGA or VGA) 16 colors assigned to any of 16 attributes (with CGA or EGA) 64 colors assigned to any of 16 attributes (with EGA or VGA) Depending on the text resolution and adapter, 8 video memory pages (0-7), 4 pages (0-3), 2 pages (0-1), or 1 page (0)
SCREEN 1: 320 x 200 graphics
40 x 25 text format, 8 x 8 character box 16 background colors and one of two sets of 3 foreground colors assigned using COLOR statement with CGA 16 colors assigned to 4 attributes with EGA or VGA 1 video memory page (0)
SCREEN 2: 640 x 200 graphics
80 x 25 text format, 8 x 8 character box 16 colors assigned to 2 attributes with EGA or VGA 1 video memory page (0)
SCREEN 3: Hercules adapter required, monochrome monitor only
720 x 348 graphics 80 x 25 text format, 9 x 14 character box Usually 2 video memory pages (0-1); 1 page (0) if a second color display adapter is installed PALETTE statement not supported Invoke the Hercules driver MSHERC.COM before using screen mode 3
SCREEN 4:
Supports Olivetti Personal Computers models M24, M240, M28, M280, M380, M380/C, and M380/T and AT&T Personal Computers 6300 series 640 x 400 graphics 80 x 25 text format, 8 x 16 character box 1 of 16 colors assigned as the foreground color (selected by the COLOR statement); background is fixed at black 1 video memory page (0) PALETTE statement not supported
SCREEN 7: 320 x 200 graphics
40 x 25 text format, 8 x 8 character box Assignment of 16 colors to any of 16 attributes If 64K EGA adapter memory, 2 video memory pages (0-1); otherwise, 8 pages (0-7)
SCREEN 8: 640 x 200 graphics
80 x 25 text format, 8 x 8 character box Assignment of 16 colors to any of 16 attributes If 64K EGA adapter memory, 1 video memory page (0); otherwise, 4 pages (0-3)
SCREEN 9: 640 x 350 graphics
80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box 16 colors assigned to 4 attributes (64K adapter memory), or 64 colors assigned to 16 attributes (more than 64K adapter memory) If 64K EGA adapter memory, 1 video memory page (0); otherwise, 2 pages (0-1)
SCREEN 10: 640 x 350 graphics, monochrome monitor only
80 x 25 or 80 x 43 text format, 8 x 14 or 8 x 8 character box Up to 9 pseudocolors assigned to 4 attributes 2 video memory pages (0-1), 256K adapter memory required
SCREEN 11 (VGA or MCGA)
640 x 480 graphics 80 x 30 or 80 x 60 text format, 8 x 16 or 8 x 8 character box Assignment of up to 256K colors to 2 attributes 1 video memory page (0)
SCREEN 12 (VGA)
640 x 480 graphics 80 x 30 or 80 x 60 text format, 8 x 16 or 8 x 8 character box Assignment of up to 256K colors to 16 attributes 1 video memory page (0)
SCREEN 13 (VGA or MCGA)
320 x 200 graphics 40 x 25 text format, 8 x 8 character box Assignment of up to 256K colors to 256 attributes 1 video memory page (0)

See also SCREEN Statement

SOUND

SOUND frequency, duration

frequency

The frequency of the sound in hertz; a value in the range 37 through 32,767.

duration

The number of system clock ticks the sound lasts; a value in the range 0 through 65,535. There are 18.2 clock ticks per second.

Example:

FOR i% = 440 TO 1000 STEP 5
  SOUND i%, i% / 1000
NEXT i%

See also PLAY

$STATIC / $DYNAMIC

{REM | '} $STATIC
{REM | '} $DYNAMIC

{REM | '}

REM or a remark character (') must precede metacommands.

$STATIC

Specifies that arrays declared in subsequent DIM statements are static arrays (unless they are declared in a non-static SUB or FUNCTION procedure). Array storage is allocated when you start the program, and remains fixed.

$DYNAMIC

Specifies that arrays declared in subsequent DIM statements are dynamic arrays. Array storage is allocated dynamically while the program runs.

DIM and REDIM usually provide a better way to specify whether arrays are dynamic or static.

See also DIM, REDIM   REM   SHARED, STATIC

STICK

STICK(n%)

n%

Indicates the coordinate returned:

n%	Returns
0	x coordinate of joystick A
1	y coordinate of joystick A
2	x coordinate of joystick B
3	y coordinate of joystick B

You must call STICK(0) before STICK(1), STICK (2), or STICK(3).
STICK(0) records the current coordinates.

Example:

Temp% = STICK(0)
PRINT STICK(2), STICK(3)

See also STRIG Function   STRIG, ON STRIG Statements

STOP

STOP

The STOP keyword also suspends trapping of events in these statements:   COM, ON COM   KEY, ON KEY   PEN, ON PEN   PLAY, ON PLAY   STRIG, ON STRIG   TIMER, ON TIMER

Example:

FOR i% = 1 TO 10
  PRINT i%
  IF i% = 5 THEN STOP     'STOP pauses; F5 Continues.
NEXT i%

See also END   SYSTEM

STRIG Function

STRIG(n%)

n%

A value that specifies a joystick status condition:

n%	Condition
0	Lower joystick A trigger was pressed since last STRIG(0)
1	Lower joystick A trigger is currently pressed
2	Lower joystick B trigger was pressed since last STRIG(2)
3	Lower joystick B trigger is currently pressed
4	Upper joystick A trigger was pressed since last STRIG(4)
5	Upper joystick A trigger is currently pressed
6	Upper joystick B trigger was pressed since last STRIG(6)
7	Upper joystick B trigger is currently pressed

STRIG returns -1 if the condition is true, 0 otherwise.

Example:

PRINT "Press Esc to exit."
DO
  IF STRIG(0) OR INKEY$ = CHR$(27) THEN EXIT DO
LOOP
DO
  BEEP                  'BEEP while trigger A is pressed.
LOOP WHILE STRIG(1)

See also STICK   STRIG, ON STRIG Statements

TIMER Function

TIMER

Use TIMER to time programs or parts of programs, or with the RANDOMIZE statement to seed the random-number generator.

Example:

RANDOMIZE TIMER

See also RANDOMIZE, RND   TIMER, ON TIMER Statements

VARPTR / VARSEG

VARPTR(variablename)
VARSEG(variablename)

variablename

Any Basic variable.

See also CALL ABSOLUTE   DEF SEG   PEEK, POKE   VARPTR$

WHILE WEND

WHILE condition
.
.
.
WEND

condition

A numeric expression that Basic evaluates as true (nonzero) or false (zero).

DO...LOOP provides a better way to execute statements in a program loop.

See also DO...LOOP   FOR...NEXT

Example Errorhandling

'Illustrates ERDEV, ERDEV$, ERL, ERR, ERROR, ON ERROR, and RESUME.
ON ERROR GOTO Handler
10 CHDIR "a:\"                'Causes ERR 71 "Disk not ready"
                              'if no disk in Drive A.
20 y% = 0
30 x% = 5 / y%                'ERR 11 "Division by zero."
40 PRINT "x% ="; x%
50 ERROR 57                   'ERR 57 "Device I/O error."

Handler:
PRINT
PRINT "Error "; ERR; " on line "; ERL
SELECT CASE ERR
  CASE 71
    PRINT "Using device "; ERDEV$; " device error code = "; ERDEV
    RESUME NEXT
  CASE 11
    INPUT "What value do you want to divide by"; y%
    RESUME                  'Retry line 30 with new value of y%.
  CASE ELSE
    PRINT "Unexpected error, ending program."
END
END SELECT

AS

• Specifies a variable type when used in the COMMON, DECLARE, DEF FN, DIM, FUNCTION, REDIM, SHARED, STATIC, and SUB statements.
• Specifies an element type in a user-defined data type when used in the TYPE statement.
• Assigns a file number to a file or device when used in the OPEN statement.
• Specifies a field name when used in the FIELD statement.
• Specifies a new file name when used in the NAME statement.

See also COMMON   DECLARE   DEF FN   DIM, REDIM   FIELD   FUNCTION   NAME   OPEN   SHARED, STATIC   SUB   TYPE

Basic Character Set

Data-Type Suffixes
!   Single-precision #   Double-precision $   String %   Integer &   Long-integer
Mathematical Operators
*   Multiplication symbol -   Minus sign /   Division symbol (slash) =   Relational operator or assignment symbol >   Greater than +   Plus sign .   Decimal point <   Less than \   Integer division symbol (backslash) ^   Exponentiation symbol (up arrow or caret)
Special
'   Comment line (single quote) ;   Controls PRINT and INPUT statement output ,   Controls PRINT and INPUT statement output :   Separates multiple statements on a single line ?   INPUT statement prompt _   Line continuation underscore (reserved for compatibility with other versions of Basic but not supported by QBasic)

BSAVE / BLOAD

BSAVE filespec$, offset%, length&
BLOAD filespec$[,offset%]

filespec$

For BSAVE, a file to which an area of memory (a byte-for-byte memory image) is copied. For BLOAD, a memory-image file created by a previous BSAVE.

offset%

For BSAVE, the offset of the starting address of the area of memory being saved. For BLOAD, the offset of the address where loading starts.

length&

The number of bytes to copy (from 0 through 65,535).

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

See also DEF SEG   VARPTR, VARSEG

Data Type Keywords

• INTEGER : A 16-bit signed integer variable.
• LONG : A 32-bit signed integer variable.
• SINGLE : A single-precision 32-bit floating-point variable.
• DOUBLE : A double-precision 64-bit floating-point variable.
• STRING * n% : A fixed-length string variable n% bytes long.
• STRING : A variable-length string variable.

See also AS   Basic Character Set   COMMON   DECLARE   DEF FN   DIM, REDIM   FUNCTION   SHARED, STATIC   SUB   TYPE

Default data types

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

letterrange

A letter or range of letters (such as A-M). QBasic sets the default data type for variables, DEF FN functions, and FUNCTION procedures whose names begin with the specified letter or letters as follows:

Statement	Default Data Type
DEFINT	Integer
DEFLNG	Long integer
DEFSNG	Single precision
DEFDBL	Double precision
DEFSTR	String

A data-type suffix (%, &, !, #, or $) always takes precedence over a DEFtype statement.

Single-precision is the default data type if you do not specify a DEFtype statement.

After you specify a DEFtype statement in your program, QBasic automatically inserts a corresponding DEFtype statement in each procedure you create.

Example:

DEFDBL A-Z
a = SQR(3)
PRINT "Square root of 3 = "; a

ENVIRON$ / ENVIRON

ENVIRON$ (env-variable$)
ENVIRON$ (n%)
ENVIRON stringexpression$

env-variable$

The name of a DOS environment variable.

n%

Specifies that ENVIRON$ returns the nth string from the environment string table.

stringexpression$

The name and setting of a DOS environment variable (such as PATH or PROMPT) in one of the following forms:
env-variable$=env-string$
env-variable$ env-string$

Changes made by the ENVIRON statement are erased when the program ends.

Example:

ENVIRON "PATH=TEST"
PRINT ENVIRON$("PATH")

VARPTR$

VARPTR$(commandstring$)

commandstring$

A string variable containing DRAW or PLAY commands.

Example:

Scale$ = "CDEFGAB"
PLAY "L16"
FOR i% = 0 TO 6
  PLAY "O" + STR$(i%)
  PLAY "X" + VARPTR$(Scale$)
NEXT i%

See also DRAW   PLAY (Music)   VARPTR, VARSEG

USING

See also PALETTE, PALETTE USING   PRINT USING, LPRINT USING

TROFF / TRON

TRON
TROFF

QBasic's debugging features make these statements unnecessary.

See also Run and Debug Keys

Run And Debugging Keys

TO

• A CASE clause of a SELECT CASE statement.
• A loop counter in a FOR...NEXT loop.
• Records to lock or unlock in a LOCK...UNLOCK statement.
• Lower and upper bounds in a DIM or REDIM statement.

See also DIM, REDIM   FOR...NEXT   LOCK, UNLOCK   SELECT CASE

STEP

See also CIRCLE   FOR...NEXT   GET, PUT   LINE   PAINT   PRESET, PSET

SLEEP

SLEEP [seconds&]

seconds&

Number of seconds to suspend the program.

If seconds& is 0 or is omitted, the program is suspended until a key is pressed or a trapped event occurs.

Example:

PRINT "Taking a 10-second nap..."
SLEEP 10
PRINT "Wake up!"

See also WAIT

OFF

See also COM, ON COM   KEY, ON KEY   KEY (Assignment)   PEN, ON PEN   PLAY, ON PLAY   STRIG, ON STRIG   TIMER, ON TIMER

MOD

numeric-expression1 MOD numeric-expression2

numeric-expression1

numeric-expression2

Any numeric expressions. Real numbers are rounded to integers.

Example:

PRINT 19 MOD 6.7    'QBasic rounds 6.7 to 7, then divides.
                    'Output is:  5

MKn$ / CVn

MKI$(integer-expression%)
MKL$(long-integer-expression&)
MKS$(single-precision-expression!)
MKD$(double-precision-expression#)
CVI(2-byte-numeric-string)
CVL(4-byte-numeric-string)
CVS(4-byte-numeric-string)
CVD(8-byte-numeric-string)

Function	Returns	Function	Returns
MKI$	A 2-byte string	CVI	An integer
MKL$	A 4-byte string	CVL	A long integer
MKS$	A 4-byte string	CVS	A single-precision number
MKD$	An 8-byte string	CVD	A double-precision number

See also FIELD   MKSMBF$, MKDMBF$, CVSMBF, CVDMBF

LET

[LET] variable=expression

variable

Any variable. Variable names can consist of up to 40 characters and must begin with a letter. Valid characters are A-Z, 0-9, and period (.).

expression

Any expression that provides a value to assign.

Use of the optional LET keyword is not recommended. The variable=expression assignment statement performs the same action with or without LET.

See also LSET, RSET

IOCTL / IOCTL$

IOCTL [#]filenumber%, string$
IOCTL$([#]filenumber%)

filenumber%

The number of an open device.

string$

The control string sent to the device.

IOCTL control strings and the information returned by IOCTL$ depend on the device driver. See your device-driver documentation for information about IOCTL control strings and what is returned by IOCTL$.

ASCII Character Codes