# QBasic/Appendix
## Commands
#### ABS

Returns the 'absolute' value of the expression, turning a negative to a positive (e.g. -4 to 4)

#### ACCESS

This sets the access of a file that has been declared into the program. There are three settings that the programmer can set. These are:
FOR APPEND opens the file as a text file and sets the file pointer to the end of the file, thereby appending new output to the file. If omitted, FOR RANDOM is the default, which would open the file as a sequence of fixed-length records and set the file pointer to the start of the file. New data would overwrite existing data in the file without warning.

#### ASC("C")

Prints the ASCII code number of the character found within the brackets. If the programmer put in a string into brackets, only the first character of the string will be shown.

#### ATN

Part of the inbuilt trigonometry functions. An expression that evaluates to a numeric vale is converted to it's Arc-Tangent.

#### BEEP

The BIOS on the motherboard is instructed to emit a "Beep" sound from the PC 'speaker'. See also SOUND and PLAY.
An older, outdated alternative is to use : PRINT CHR$(07)
This was replaced later by the BEEP command.

#### BLOAD

Loads a file saved with BSAVE into memory.
* file_path$ is the file location
* memory_offset is an integer specifying the offset in memory to load the file to
The starting memory address is determined by the offset and the most recent call to the DEF SEG statement

#### BSAVE

Saves the contents of an area in memory to a file that can be loaded with BLOAD
* file_path$ is the file location
* memory_offset is an integer specifying the offset in memory to save
* length the number of bytes to copy
The starting memory address is determined by the offset and the most recent call to the DEF SEG statement

#### CALL ABSOLUTE

Pushes the provided arguments, which must be INTEGER, from left to right on the stack and then does a far call to the assembly language routine located at address. The code segment to use is set using DEF SEG. Normally QBasic will push the address of arguments, but if an argument is preceded by BYVAL the value of the argument will be pushed.
Note that because QBasic pushes the arguments from left to right, if you provide three arguments for example the stack will look like this:
Example:
QBasic doesn't set BP to the stack frame of your machine language routine, but leaves it pointing to the stack frame of the calling QBasic procedure, which looks like this:
The offsets indicated with -/+???? will depend on the sizes and presence of variables, return value and arguments. For example, an INTEGER variable will take two bytes, but a LONG variable four. As one might expect considering how QBasic passes arguments, variables are stored in reverse order of declaration. Contrary to when calling a machine language routine, the arguments here will always be addresses. For arguments passed by value, space is allocated on the stack and the address of that space is passed to the procedure.

#### CASE

Executes the statements after the first CASE statement where a test matches expression. The tests can be of the following forms:
This is an example of a program with no CASE commands that assigns different paths to values:
This is what a program looks like with the CASE command:

#### CHAIN

This chains execution to another QBasic program. Values may be passed to the other program by using the COMMON statement before the CHAIN statement. Note that execution doesn't return to the first program unless the second program uses CHAIN to transfer execution back to the first.

#### CHDIR

This is used for setting the working directory, also known as the current directory. The directory name is declared exactly like in DOS and long file names aren't supported. For example:
Note that this doesn't change the current drive and every drive has its own working directory. You can set the current drive like this:

#### CHR$

This returns the string character symbol of an ASCII code value.
Often used to 'load' characters into string variables when that character cannot be typed (e.g. the Esc key or the F{n} (Function Keys) or characters that would be 'recognised' and acted upon by the QBASIC interpreter. The following four characters cannot occur in a QBasic string literal:
* 0 Null: all characters up to the end of the line will get deleted, including this one.
* 10 Line Feed: signals the end of the line.
* 13 Carriage Return: this character will get deleted.
* 34 Quotation Mark: signals the end of the string literal.
Here is a list of some character codes :-

#### CINT

This rounds the contents of the brackets to the nearest integer.
4574

#### CIRCLE

Lets the programmer display a circle. Like all graphics commands, it must be used with the SCREEN command.

#### CLEAR

Resets all variables, strings, arrays and closes all files. The reset command on QBasic.

#### CLOSE

Closes all open files
Closes only the file opened as data stream 2. Other files remain open

#### CLS

Clears the active screen. Erases all text, graphics, resets the cursor to the upper left (1,1), and also applies the current background color (this has to be set using the COLOR command) to the whole screen.

#### COLOR

This lets you change the colour of the text and background used when next 'printing' to the current output window. It can be done like this:
You have a choice of sixteen colours:
These values are the numbers that you put in the COLOR command.
Note Only screen modes 0, 7, 8, 9, 10 support a background color. To 're-paint' the whole screen in a background colour, use the CLS command.

#### COMMON

Declares a variable as 'global', which allows its value to be accessed across multiple QBasic programs / scripts (see also the CHAIN command)
Each program that declares 'variablename' as COMMON will share the same value.
NOTE. All COMMON statements must appear at the start of the program (i.e. before any executable statements).

#### CONST

Fixes a variable so it can not be changed within the program.
For example :-
Assigns the value 3.14159265 to PI.
PI must be assigned a value before it is used to calculate PI2. Typically all CONST are declared at the beginning of a program.

#### DATA

Use in conjunction with the READ and RESTORE command. Mostly used in programs dealing with graphics, this command lets QBasic read a large number of constants. The READ command accesses the data while the RESTORE command "refreshes" the data, allowing it to be used again.

#### DATE$

A system variable that always contains the current date as a string in mm-dd-yyyy format. Use it like this:

#### DEF SEG

Sets the current segment address.
* address is a segment address that can contain a value of 0 through 65535.
If address is omitted, DEF SEG resets the current segment address to the default data segment. DEF SEG is used by BLOAD, BSAVE, CALL ABSOLUTE, PEEK, and POKE

#### DEST(Only QB64!)

_DEST sets the current write-to page or image. _DEST image_handle sends the destination image to an image of handle stored in long variable image_handle. _DESt 0 sends the destination image to the current screen being used.

#### DIM

This is used to declare an array (early versions of QBasic required all variables to be defined, not just arrays greater than 10)
The Array name can be of any type (Integer, Double, String etc). If not declared, single precision floating point is assumed. Strings can be 'declared' using $ sign (Integers with the '%' sign). The QBASIC interpreter tolerates numeric arrays of up to 10 count without these needing to be declared.
NOTE Early versions of QBasic did not explicitly set the contents of an array to zero (see CLEAR command)
Create an integer array called table% containing 100x2 = 200 entries
Create a string array called form$ containing 5 strings
Create an array called quotient that contains 20 double precision numbers

#### DO .. LOOP

Used to create a loop in the program. The [condition] is tested only after the [program] code is executed for the first time (see also WHILE). For example:
This does not work But the following does

#### DRAW

Used to draw a straight line from the current 'cursor' position in the current colour. DRAW defines the direction (up, down etc.) and the length of the line (in pixels). For example:-
The letter in front of each number is the direction:
The drawing 'cursor' is left at the position where the line ends. u50 draws from 50,50 upwards ending at 50,0 r50 draws from 50,0 to the right, ending at 100,0 d50 draws from 100,0 downwards, ending at 100,50 l50 draws from 100,50 to the left, ending at 50,50
The example shown will thus draw a red 'wire frame' square.
See also LINE and CIRCLE commands.
Note: The diagonal from 0,0 to 100,100 will be 100 * root(2) pixels long (i.e. 141)

#### END

Signifies the end of the program. When QBasic sees this command it usually comes up with a statement saying: "Press Any Key to Continue".

#### END TYPE / END DEF / END SUB / END FUNCTION / END IF / END SELECT

* END TYPE ends a TYPE definition.
* END DEF ends a DEF FN function definition.
* END SUB ends a SUB procedure definition.
* END FUNCTION ends a FUNCTION procedure definition.
* END IF ends a multiline IF block.
* END SELECT ends a SELECT CASE block.

#### ENVIRON

NOTE: If you are running QBasic on a Windows system, you will not be able to use this command.
This command helps you set an environment variable for the duration of the session. On exit from the QBasic.exe interpreter, the variables revert to their original values.

#### EOF

This checks if there are still more data values to be read from the file specified in. EOF returns a boolean / binary value, a one or zero. 0 if the end of file has not been reached, 1 if the last value in the file has been read (see also LINE INPUT)
Note that, since the INPUT is executed before UNTIL is reached, File.txt must contain at least one line of text - if the file is empty, you will receive an 'ERROR (62) Input past end of file'.

#### ERASE

Used to erase all dimensioned arrays.

#### ERROR

System variable holding a numeric value relating to the processing of the previous line of code. If the line completed without error, ERROR is set to 0. If the line failed, ERROR is set to one of the values shown below. Most commonly used to redirect program flow to error handling code as in :-
If ERROR is non=zero, program flow jumps to the line number or label specified. If ERROR is zero, program flow continues with the next line below.
To manually test your program and check to see if the error handling routine runs OK, ERROR can be set manually :-
Set ERROR = number
The error numbers are as follows:
Note that ERROR is set when execution fails, not when the code is 'read' - so, for example, a 'divide by 0' will be found before the result is assigned to a non-existent array variable or written to a non-existent file.

#### EXIT

Allows the immediate exit from a subroutine or a loop, without processing the rest of that subroutine or loop code
Exits from a DEF FN function.
Exits from a DO loop, execution continues with the command directly after the LOOP command
Exits from a FOR loop, execution continues with the command directly after the NEXT command
Exits a FUNCTION procedure, execution continues with the command directly after the function call
Exits a SUB procedure.

#### FOR .. NEXT

The variable is set to the [start value], then program code is executed and at the Next statement the variable is incremented by 1 (or by the STEP value, if any is specified). The resulting value is compared to the [end value] and if not equal program flow returns to the line following the FOR statement.
For example:
200 199 198
Care must be taken when using STEP, since it is quite possible to step past the (end value) with the result that the FOR loop will run 'for ever' (i.e. until the user aborts the interpreter or an error occurs), for example :-
200 198 196 194 192 ... 0 -2 -4 ... -32768 ERROR overflow

#### GOSUB

Command processing jumps to the subroutine specified. When the RETURN command is encountered, processing returns to this point and continues with the line below the GOSUB.

#### IF

Compares variables or strings. For example, if you wanted to examine whether or not a user-entered password was the correct password, you might enter: IF a$ = "password" THEN PRINT "Password Correct" Where a$ is the user entered password. Some operators include: "="- equal to "<"- less than (only used when variable or string is a number value) ">"- greater than (only used when variable or string is a number value) "<>"- does not equal "<="- less than or equal to (only used when variable or string is a number value) ">="- greater than or equal to (only used when variable or string is a number value) One can also preform actions to number values then compare them to other strings or variables using the if command, such as in the below examples: IF a+5 = 15 THEN PRINT "Correct" IF a*6 = b*8 THEN PRINT "Correct"

#### INCLUDE (QUICKbasic Only)

QUICKBasic supports the use of include files via the $INCLUDE directive:
Note that the include directive is prefixed with an apostrophe, dollar, and that the name of the file for inclusion is enclosed in single quotation mark symbols.

#### INKEY$

This is used when you want a program to function with key input from the keyboard. Look at this example on how this works:
You can use this in conjunction with the CHR$ command or type the letter (e.g. A).

#### INPUT

Displays the String Literal, if a semi colon follows the string literal, a question mark is displayed, and the users input until they hit return is entered into the variable. The variable can be a string or numeric. If a user attempts to enter a string for a numeric variable, the program will ask for the input again. The String Literal is option. If the string literal is used, a comma (,) or semicolon (;) is necessary.

#### INPUT #

Reads a string / value from the specified file stream (see also LINE INPUT #)
Reads 4 values from the file that is OPEN as #1. a$ is assigned all text until a ',' (comma) or end of line is reached, b$ the next segment of text, then two numeric values are interpreted and assigned to n and m.
Note that, within the file, numbers can be separated by 'anything' - so, if a number is not found (for 'n' or 'm') on the current 'line' of the file, the rest of the file will be searched until a number is found. Input is then left 'pointing' at the position in the file after the last number required to satisfy the input statement (see also 'seek #' command)

#### INSTR

Returns the character position of the start of the first occurrence of Find$ within Search$, starting at character position 'start%' in Search$. If Find$ is not found, 0 is returned. start% is optional (default = 1, the first character of Search$)
returns 4

#### LEFT$

A$ is set to the N left most characters of B$.
returns "Get th"
See also RIGHT$, MID$.

#### LET

Early versions of the QBasic.exe command interpreter required use of the 'LET' command to assign values to variables. Later versions did not.
is equliavent to :-

#### LINE

Used for drawing lines in QBasic. The first X and Y are used as coordinates for the beginning of the line and the second set are used for coordinating where the end of the line is. You must put a SCREEN command at the beginning of the program to make it work.
Note. When in SCREEN 13, the Colour Number == the Palette number

#### LINE INPUT #

Reads a complete line as text characters from the file OPEN as stream #1 and places it in a$.
To find the 'end of line', the QBasic interpreter seaches for the 'Carriage Return' + 'Line Feed' (0x0D, 0x0A) characters. When reading text files created on UNIX/LINUX systems (where the 'Line feed' 0x0A is used on it's own to signify 'end of line'), LINE INPUT will not recognise the 'end of line' and will continue to input until the end of file is reached. For files exceeding 2k characters, the result is an "Out of String Space" Error as a$ 'overflows'. One solution is to use a text editor able to handle UNIX files to open and 'save as' before attempting to process the file using QBasic.

#### LOADIMAGE (QB64 Only)

(NOTE! The commands in this section refer to a third-party program called "QB64". Neither QUICKbasic nor Qbasic support _LOADIMAGE, _NEWIMAGE, OR _PUTIMAGE commands. Both QUICKbasic and Qbasic have a "SCREEN" command, but it works diffently in those languages than in QB64.)
_LOADIMAGE("image.jpg")
Shows an image. Must be used with the commands SCREEN, _NEWIMAGE and _PUTIMAGE.
Example:
DIM rabbit AS LONG SCREEN _NEWIMAGE(800, 600, 32) rabbit = _LOADIMAGE("rabbit.jpg") _PUTIMAGE (100,100), rabbit

#### LOOP

Used to create a loop in the program. This command checks the condition after the loop has started. This is used in conjunction with the DO command.

#### LPRINT

Prints out text to a printer. The LPRINT command expects a printer to be connected to the LPT1(PRN) port. If a printer is not connected to LPT1, QBasic displays a "Device fault" error message.
If your printer is connected to a COM port instead, use the MS-DOS MODE command to redirect printing from LPT1 to COMx (for example, to redirect to COM1, use the following command:
If you need to cancel the redirection when finished, use the following command:

#### MID$

In the first use, a$ is set to the substring taken from string$ strating with character start% taking Length% characters. If length% is omitted, the rest of the line (i.e. start% and all the characters to the right) are taken.
In the second use, length% characters of string$ are replaced by b$ starting at start%. If length% is omitted, the rest of the line is replaced (i.e. start% and all the characters to the right)
See also LEFT$ RIGHT$ LEN

#### MOD

Returns the remainder of an integer divide of a by b
For example, 10 MOD 3 returns 1

#### NEWIMAGE(Only QB64!)

_NEWIMAGE is used to set a long variable as the screen dimensions, or can be used with the SCREEN command (See later in Appendix) to directly set the screen details. It is very useful as you can enlarge the SCREEN mode '13' which has RGB color settings if you find the default size too small.
Syntax: _NEWIMAGE(width,length,screen_mode)
* width and length are long variables, while screen_mode is the screen mode format you wish to change.
Like,
where, 256 is the amount of colours
It is also used to prepare the window screen surface for the image you want to put (first load it using LOADIMAGE).

#### OPEN

This opens a file. You have to give the DOS file name, for example:
Opens the existing file data.txt for reading as data stream #1. Since no path is specified, the file must be in the same folder as the QBasic.exe - if not, processing halts with a 'file not found' error
Opens an empty file named RUN.LOG in the C:\TEMP folder for writing data stream #2. Any existing file of the same name is replaced.

#### PALETTE

For VGA (SCREEN mode 13) only, sets the Palette entry to a new RGB color. The palette number must be in the range 1-256. The required colour is a LONG integer created from the sum of (required Blue * 65536) + (required Green * 256) + required Red.

#### RANDOMIZE

RANDOMIZE will set the seed for QBasic's random number generator. With QBasic, it's standard to simply use RANDOMIZE TIMER to ensure that the sequence remains the same for each run.
The example is a mathematical operation to get a random number from 1 to 100.
INT stands for Integer, RND for Random and "*" stands for the limit upto which the random number is to be chosen. The "+ 1" is just there to ensure that the number chose is from 1 to 100 and not 0 to 99.
Note: Subsequent calls of this function do not guarantee the same sequence of random numbers.

#### READ

Used in conjunction with the DATA command, this command lets QBasic read data. This is mostly used when dealing with large quantities of data like bitmaps.

#### REM or '

When the interpreter encounters REM or " ' " (a single quote) at the start of a line, the rest of the line is ignored

#### RETURN

Signifies that it is the end of a subroutines

#### RND

RND will provide a random number between 0 and 1.
The example is a mathematical operation to get a random number from 1 to 100. RANDOMIZE TIMER will set the initial seed to a unique sequence. INT stands for Integer, RND for Random and "*" stands for the limit upto which the random number is to be chosen. The "+ 1" is just there to ensure that the number chose is from 1 to 100 and not 0 to 99.
Internally, the seed a 24-bit number, iterated in the following method: rnd_seed = (rnd_seed*16598013+12820163) MOD 2^24

#### PLAY

Used to play notes and a score in QBasic on the PC speaker. The tones are indicated by letters A through G. Accidentals are indicated with a "+" or "#" (for sharp) or "-" (for flat) immediately after the note letter. See this example:
Whitespaces are ignored inside the string expression. There are also codes that set the duration, octave and tempo. They are all case-insensitive. PLAY executes the commands or notes the order in which they appear in the string. Any indicators that change the properties are effective for the notes following that indicator.

#### PRINT

Displays text to the screen. The Argument can be a string literal, a string variable, a numeric literal or a numeric variable. All arguments are optional.
Saves data to the file that is 'OPEN FOR OUTPUT AS #[n]' or we can use ? symbol for print command

#### PSET

This command displays pixels, either one at a time or a group of them at once. For the command to work, the program must have a SCREEN command in it.

#### SCREEN

This command is used for displaying graphics on the screen. There are ten main types of screen modes that can be used in QBasic depending on the resolution that you want. Here is a list of what screen modes you can choose from:
SCREEN 0: Textmode, cannot be used for graphics. This the screen mode that text based programs run on.
SCREEN 1: 320 x 200 Resolution. Four Colours
SCREEN 2: 640 x 200 Resolution. Two Colours (Black and White)
SCREEN 7: 320 x 200 Resolution. Sixteen Colours
SCREEN 8: 640 x 200 Resolution. Sixteen Colours
SCREEN 9: 640 x 350 Resolution. Sixteen Colours
SCREEN 10: 640 x 350 Resolution. Two Colours (Black and White)
SCREEN 11: 640 x 480 Resolution. Two Colours
SCREEN 12: 640 x 480 Resolution. Sixteen Colours
SCREEN 13: 320 x 200 Resolution. 256 Colours. (Recommended)
Note. In SCREEN 13 you have a colour Palette of 256 colours. The PALETTE is pre-set by Windows however you can change the RGB values using the PALETTE command.

#### SEEK

Repositions the 'input #' pointer to the beginning of the file.

#### SGN

Yields the 'sign' of a value, -1 if < 0, 0 if 0, 1 if > 0

#### SHELL

The 'SHELL' command is used in Qbasic to issue a command to Command Prompt/Windows Shell . The 'Shell' command is used along with a string that contains commands that would be understood by any of the above software. The string enclosed commands are much like that of MS-DOS
Example: SHELL can be used with a 'DIR' command to make a directory of files in a certain folder or path.

#### SLEEP

Execution is suspended for n seconds

#### SOUND

Unlike the BEEP command, this produces a sound from the PC speakers that is of a variable frequency and duration. The frequency is measured in Hertz and has a range from 37 to 32767. Put in one of these numbers in the frequency section. The duration is clock ticks that is defaulted at 18.2 ticks per second.

#### STR$

Converts a numeric value into a text (string) character
The numeric value is converted into text characters and placed into A$. Use to convert numbers into a text string.
WARNINGS.
1) If the result is positive, a leading 'space' is added (STR$(123) = " 123" and not "123" as might be expected). If the result is negative, instead of a space you get a '-' (minus sign), i.e. STR$(-123) = "-123" and not " -123" as might be expected from the positive behaviour.
2) When converting a float (mumb!, numb#) less than 0.1, the string value may be rendered in 'scientific notation', with 'D' used rather than '*10^' (for example "5.nnnnnnD-02" rather than " .05nnnnnn" or "5.nnnnnn*10^-02"). This only occurs when the number of significant digits needs to be preserved (so .03000000 is rendered as " .03", whilst .030000001 becomes " 3.0000001D-02"), again perhaps not what you might expect.
See also CHR$ for converting an ascii value into a string character.
See also LEFT$, MID$, RIGHT$ for extracting sub-strings from a line of text.

#### SYSTEM

The .bas exits, the QBasic.exe interpreter is closed and 'control' passes to the Command Window c:\ prompt (or next line of a calling .cmd script etc.)
NOTE!: This only works when you start your program at the command prompt using the "/run" parameter! (EX: "Qbasic /run MyProg.bas") Otherwise, Qbasic assumes you opened your program to make changes, and thus "SYSTEM" drops you back at the editor screen.

#### THEN

Used in conjunction with the GOTO or IF condition commands. It tells the computer what to do if a certain condition has been met.

#### TO

Usually used to input a number of variables.
This example will print all numbers from 400 to 500. Instead of declaring all values separately, we can get them all declared in one go.

#### USING

Used to format the output of data from PRINT commands. Normally, the QBasic interpreter will print a number as 8 characters with as many leading spaces as necessary. To change this behavour, the USING command can be used to format the output. For example ..
THEN PRINT #1, USING "0##"; n; ELSE PRINT #1, USING "00#"; n;
.. will output n from 0 to 999 with leading zeros. Note the ';' after the n. This means 'don't start a new line' and results in the next PRINT #1 adding data directly after the comma (',') Qbasic automatically inserts instead of a line.

#### VAL

Converts the [variable string] contents into a numeric value so it can be used in calculations. If (name) is an INTEGER type, the VAL is rounded down. See also STR$.
A$ = "2"
B$ = "3"
X = VAL(A$) + VAL(B$)
PRINT A$; " + "; B$; " ="; X

#### WHILE ... WEND

The condition is tested and if true (or NOT true) the [program] code is executed until WEND is reached, at which point control passes back to the WHILE line.
While the end of file #1 has not been reached, read each complete line and write it to file #2.
Unlike FOR and DO, it is not possible to EXIT from a WHILE loop