en:singlepage

Program Syntax

test

Statements

BASIC-256 programs consist of a series of statements separated by newlines, which are executed in order.

2016/08/13 14:06 · admin

Label

A line may optional begin with a label followed without a space with a colon to be used as a destination of a goto, gosub, or onerror.

print "before"
gosub display
print "after"
end

display:  print "in gosub"
return

2016/08/13 12:35 · admin

Compound Statement

Multiple statements may be included on a single line by separating then with a : (colon), this is called a compound statement. In the context of the language a single statement is also considered a “compound statement”.

total= 0: for t=1 to 10: total = total + t: next t: print "the total of 1 to 10 is " + total

Special care should be taken when including if/then statements in a compound line:

2016/08/13 12:49 · admin

Example

The following is a sample program that shows single line statements, compound statements, and use of a label.

print "hello ";
gosub world
end

world: ### print out world
print "w";
print "o";: print "r";: print chr(asc("a")+11);
print right('Dd',1)
return

2016/01/01 22:41

Numeric Constants

Numeric constants are any numeric characters, preceded by an optional minus sign to indicate negative numbers, and an optional decimal followed by more numeric characters to indicate floating point values. Numbers come in two types: 1) integers and 2) decimal numbers.

Examples include:

Integer Numbers
10
-2345
0

Positive integer values may also be expressed in binary (base 2), octal (base 8), and hexadecimal (base 16). Precede binary values with 0b (0b1110 = 14), octal with 0o (0o177 = 127), and hexadecimal with 0x (0xff = 255).

Decimal Numbers
-234.567
56.87
0.0123
PI

Very large and small numbers may also be represented in scientific E notation (added in version 0.9.9.46). http://en.wikipedia.org/wiki/Scientific_notation

Scientific E Notation
E Notation	Decimal Number
2e0	2
3e2	300
1.234e10	12340000000
-5.3e4	-53000
2e-1	0.2
5.12e-9	0.00000000512

2016/01/01 22:41

String Constants

String constants are zero or more characters enclosed by either double quotation marks(“) or single quotation marks (').

Examples

'I said “Hello.”'

“Tuesday Rocks”

'123'

“it is Smith's”

2016/01/01 22:42

Variables

You can think of a variable as a place in the computer's memory to store things. Each variable has a name that must begin with a letter, and may consist of any number of letters, numbers, and dollar signs. Their names are case sensitive, the variable 'a' is not the same as the variable “A”.

In BASIC-256 you do not need to define a variable before you use it. The variable is created when it is assigned a value for the first time and will retain its value until the program ends or the variable is unassigned.

Example

a = 99	Assigns the integer 99 to the variable a
nom = “Jim”	Assigns the string “Jim” to the variable nom
print “Say hello to ” + nom	Appends the string in nom the the string “Say hello to ” and displays the result
a = a + 1	Takes the value of a and adds one to it, then store the new value back into a

History

1.99.99.8

variable typing was removed

2016/01/01 22:42

Arrays

Arrays are allocated using the DIM command or re-sized using REDIM. They may hold numeric or string data. Access to specific elements in an array is accomplished by using square brackets along with the integer offset of the element, starting from zero. Arrays may also be dimensioned and accessed using two dimensions.
Array lengths may also be extracted using [?] [?,] and [,?] on the end of the array variable.

By default arrays may be indexed using an integer in the range of 0 to array_length-1. You may optionally change the numeric array index to a range of 1 to array_length by using the ArrayBase statement.

Assigning values to an array

Values may be assigned to an array in one of five ways:

1. By using the Dim statement to reserve space for the array in the computer's memory and then assigning each individual element.

dim a(10)
for t = 0 to a[?]-1
    a[t] = t
next t

2. By using a list to create and assign an array.

a = {{0,1,2},{3,4,5},{6,7,8}}

or

b[] = {1,2,3,4}

3. By using the Dim statement to copy an existing array into another array.

a = {1,2,3,4}
dim b = a[]

4. By using the Explode or Explodex functions to split a string into an array.

a = explode("how now brown cow"," ")

5. Using the fill assignment operator (with or without dim)

dim c fill "stuff"
dim e[] fill 0
b fill ""
a[] fill -1

Passing Arrays of Data to Builtin Functions and Statements

When passing an array of data, like to the sound statement, you may include an empty set of brackets [] after the variable name. This was added to reduce the confusion between a regular variable and a variable containing an array of values.

History

1.99.99.55	added dim logic to copy one array to another
1.99.99.57	added the fill assignment operator
1.99.99.72	added the array passing note
2.0.0.0	Added ability to change array base

2016/01/01 22:40

Anonymous Arrays

An anonymous array is a set of numeric values or a set of string values, separated by commas, and enclosed in braces {}. Anonymous array can be used to rapidly assign a group of values to an array. If the Anonymous array is longer than the dimensioned array then the array will be automatically re-dimensioned (Redim) to the correct length.

Anonymous Arrays can also be used in the Poly, Sound, and Stamp statements in place of an array variable.

Example

dim myarray(4)
myarray = {1, 2, 3, 4}

dim words(1)
words = {"how","now","brown","cow"}
for n = 0 to words[?]-1
 print words[n]
next n

2016/01/01 22:40

Operators

What is an operation and operator…

Arithmetic Operators

Arithmetic operators are simply the operations of simple math with integer and floating point numbers.

Arithmetic Operators
Operator	Name	Example	Comments
+	Addition	a + b	Add two numeric values. If both are an integer, then the result will be an integer. If one or both are floating point numbers then the result will be floating point. If one or both values are strings the plus operator will concatenate the strings.²
-	Subtraction	a - b	Subtract two numeric values. If both were integer and the operation did not overflow then an integer will be returned else a floating point number will be the result.
*	Multiplication	a * b	Multiply the two numbers. If both were integer and the operation did not overflow then an integer will be returned else a floating point number will be the result.
/	Division	a / b	Returns a floating point number of times that b goes into a.
\	Integer Division	a \ b	Returns the number of whole times that b goes into a.
%	Modulo	a % b	Returns the remainder of the integer division of a and b.
mod	Modulo	a mod b	Returns the remainder of the integer division of a and b.

History

2.0.0.0

Added 'mod' alias for modulo.

2016/08/09 18:03 · admin

String Operators

String operators perform an operation called concatenation. Concatenation is joining two or more strings together to make a longer string.

String Operators
Operator	Name	Example	Comments
;	Concatenation	a ; b	Always concatenates (converts numbers to strings)²
+	Concatenation	a + b	Appends b to the end of a (If either (or both) a and b are not numbers, see IsNumeric). ²
&	Concatenation	a & b	Appends b to the end of a (If either (or both) a and b are not numbers, see IsNumeric). ³
*	Repeat	a * i	Repeats string a, integer i times. If i ⇐ 0 an empty string will be returned.

History

2.0.0.0

Added string repeat using the '*' operator.

2016/08/09 11:21 · admin

Comparison Operators

Comparison operators compare two values and return a Boolen (true/false) value. These Operators are most commonly used in statements like If, Case and While.

Comparison Operators
Operator	Name	Example	Comments
=	Equal	a = b	Returns true of two values are equal
<	Less Than	a < b
>	Greater Than	a > b
<=	Less Than or Equal	a <= b
>=	Greatet Than or Equal	a >= b
<>	Not Equal	a <> b

2016/08/09 11:02 · admin

Logical Operators

Logical operators work on Boolean (true/false) values. These values often come as Boolean Constants and Comparison Operators.

Logical Operators
Operator	Name	Example	Comments
NOT	Logical Negation	NOT a
AND	Logical Conjunction	a AND b
OR	Logical Disjunction	a OR b
XOR	Logical Exclusive Disjunction	a XOR b

Not

Also known as Boolean negation.

not true	false
not false	true

And

Also known as a Boolean product.

false and false	false
false and true	false
true and false	false
true and true	true

Or

Also known as Boolean addition.

false or false	false
false or true	true
true or false	true
true or true	true

Xor

The exclusive or. “You can have you cake XOR you can eat it.”

false xor false	false
false xor true	true
true xor false	true
true xor true	false

2016/08/09 11:16 · admin

Variable Operators

Most operators work with one or two expressions (integers, floating point numbers, strings, and Boolean values), but there are a few operators that work specifically with variables, arrays, and array elements. These operators will directly change the value stored in a variable.

Variable Operators
Operator	Name	Example	Comments
=	Assign a Number to a Variable	a = 9
		z = “Hola.”
		q$ = 9.9
+=	Add to a Variable	a += 7	Same as a = a + 7
	Concatenate to a Variable	f += “.”	Same as f = f + “.”
-=	Subtract from a Variable	a -= 9	Same as a = a - 9
*=	Multiply a Variable	a *= 2	Same as a = a * 2
/=	Divide a Variable	a /= 8	Same as a = a / 8
++	Increment Prefix	++a	Increment (add one) the the variable and return the value after the increment. (may be applied ONLY to numeric variables or array elements)
++	Increment Suffix	a++	Return the value of the variable and then increment the variable by one for the next time it is accessed. (may be applied ONLY to numeric variables or array elements)
–	Decrement Prefix	–a	Decrement (subtract one) the variable and return the value after the decrement. (may be applied ONLY to numeric variables or array elements)
–	Decrement Suffix	a–	Return the value of the variable and then decrement the variable by one for the next time it is accessed. (may be applied ONLY to numeric variables or array elements)
fill	Array Fill	a fill 99	Fills an array (that was previously dimensioned) with a single value (may be a string or numeric expression)

2016/08/09 18:16 · admin

Bitwise Operators

Bitwise operators only work with long integer values (since 1.99.99.19) in the range of −2,147,483,648 to 2,147,483,647. Any attempt to use a number outside this range will produce, warnings, error, and/or unexpected results.

Bitwise Operators
Operator	Name	Example	Comments
~	Bitwide Negation	~a
&	Bitwise Conjunction	a & b	If one or both values are strings the ampersand operator will concatenate the strings into a single string.³
\|	Bitwise Disjunction	a \| b	Returns the bits of integer a or integer b.

2016/08/09 11:19 · admin

Order of Operations

Operators are evaluated according to a strict set of rules. These rules are called the “Order of Operations”.

Order of Operations
Level	Operators	Category/Description
1	( )	Grouping
2	^	Exponent
3	- ~	Unary Minus and Bitwise Negation (NOT)
4	* / \	Multiplication, Division, and Integer Division
5	%	Integer Remainder (Mod)
6	+ - ;	Addition/Concatenation, and Subtraction
7	& \|	Bitwise And and Bitwise Or
8	< ⇐ > >= = <>	Comparison (Numeric and String)
9	NOT	Not
10	AND	Logical And
11	OR	Logical Or
12	XOR	Logical Exclusive Or

2016/08/09 18:33 · admin

2016/01/01 22:41

Abs (Function)

Format

abs ( numeric_expression )

returns float_expression or integer_expression depending on the type of expression passed.

Description

Returns the absolute value of a numeric_expression.

Example

print abs(-45)
print abs(6.45)

will print

45
6.45

Acos (Function)

Format

acos ( numeric_expression )

returns float_expression

Description

Computes the arc-cosine of expression. Angles are expressed in radians (0 to 2pi).

Asc (Function)

Format

asc ( string_expression )

returns integer_expression

Description

Converts the first character in a string_expression expression to an integer representing it's UNICODE value.

Asc	Chr	Asc	Chr	Asc	Chr	Asc	Chr	Asc	Chr	Asc	Chr
32	SPACE	48	0	64	@	80	P	96	`	112	p
33	!	49	1	65	A	81	Q	97	a	113	q
34	“	50	2	66	B	82	R	98	b	114	r
35	#	51	3	67	C	83	S	99	c	115	s
36	$	52	4	68	D	84	T	100	d	116	t
37	%	53	5	69	E	85	U	101	e	117	u
38	&	54	6	70	F	86	V	102	f	118	v
39	'	55	7	71	G	87	W	103	g	119	w
40	(	56	8	72	H	88	X	104	h	120	x
41	)	57	9	73	I	89	Y	105	i	121	y
42	*	58	:	74	J	90	Z	106	j	122	z
43	+	59	;	75	K	91	[	107	k	123	{
44	,	60	<	76	L	92	\	108	l	124	\|
45	-	61	=	77	M	93	]	109	m	125	}
46	.	62	>	78	N	94	^	110	n	126	~
47	/	63	?	79	O	95	_	111	o	127

Example

print asc("A")
print asc("blue")

will print

65
98

History

0.9.4

New To Version

2016/01/01 22:40

Asin (Function)

Format

asin ( numeric_expression )

returns float_expression

Description

Computes the arc-sine of an angle expressed in radians (0 to 2pi).

Atan (Function)

Format

atan ( numeric_expression )

returns float_expression

Description

Computes the arc-tangent of an angle expressed in radians (0 to 2pi).

Ceil (Function)

Format

ceil ( numeric_expression )

returns integer_expression

Description

Returns the lowest integer that is greater than or equal to expression.

Value	int()	ceil()	floor()
-4.56	-4	-4	-5
-0.56	0	0	-1
0.56	0	1	0
5.56	5	6	5

Changedir (Statement)

Format

changedir string_expression
changedir ( string_expression )

Description

Change the current working directory to the path specified in expression. For all systems (including Windows) a forward slash (/) will be used to separate folders in a full path.

History

0.9.6r

New To Version

2016/01/01 22:40

Chr (Function)

Format

chr ( numeric_expression )

returns string_expression

Description

Converts the integer expression into a single character string expression with the UNICODE value of the number.

Example

print chr(66)+chr(111)+chr(111)+chr(33)

will print

Boo!

History

0.9.4

New To Version

2016/01/01 22:40

Circle (Statement)

Format

circle x_position, y_position, radius_expression
circle ( x_position, y_position, radius_expression )

Description

Draws a circle centered at x,y with a radius r using the current pen and brush colors.

Example

clg

color red
circle 75,75,50

penwidth 5
color orange, yellow
circle 150,150,75

penwidth 10
color blue, clear
circle 225,225,50

draws

Clickb (Function)

Format

clickb
clickb ( )

returns integer_expression

Description

Returns the buttons that the user last clicked on the mouse (if over the graphic output). Returns 0 if no click has been recorded.

Return Values
Constant	Value
MOUSEBUTTON_NONE	0
MOUSEBUTTON_LEFT	1
MOUSEBUTTON_RIGHT	2
MOUSEBUTTON_CENTER	4
MOUSEBUTTON_DOUBLECLICK	32

2016/08/14 15:38 · admin

Example

# clear any prior mouse click
clickclear
# wait for the user to click the mouse
print "click mouse on the graphics output"
while clickb = 0
  pause .01
endwhile
# show where the user clicked
print "The user clicked at (" + clickx + "," + clicky + ")"

History

0.9.4d	New To Version
1.99.99.58	Added Named Constants

2016/01/01 22:40

Clickclear (Statement)

Format

clickclear
clickclear ( )

Description

Sets ClickB, Clickx, and Clicky to zero so that we can easily tell when the next mouse click is recorded.

Example

See sample program on Clickb.

History

0.9.4d

New To Version

2016/01/01 22:40

Clickx (Function)

Format

clickx
clickx ( )

returns integer_expression

Description

Returns the mouse x location of the mouse pointer over the graphic output last time the user clicked a mouse button.

Example

See sample program on Clickb.

History

0.9.4d

New To Version

2016/01/01 22:40

Clicky (Function)

Format

clicky
clicky ( )

returns integer_expression

Description

Returns the mouse y location of the mouse pointer over the graphic output last time the user clicked a mouse button.

Example

See sample program on Clickb.

History

0.9.4d

New To Version

2016/01/01 22:40

Clg (Statement)

Format

clg
clg color_name
clg ( color_name )
clg rgb_expression
clg ( rgb_expression )

Description

Clears the graphics output window or sets it to the specified color.

History

1.99.99.25

Added optional color

2016/01/01 22:40

Close (Statement)

Format

close
close ( )
close open_file_number
close ( open_file_number )

Description

Closes an open file. If no file is open to that file number, this command does nothing. If the file number is not specified file number zero (0) will be used.

History

2016/01/01 22:40

Cls (Statement)

Format

cls

Description

Clears the text output window.

Color (Statement)

Format

color color
color ( color )
color pen_color, brush_color
color ( pen_color, brush_color )

Description

Sets the current drawing color to colorname or to an ARGB value where ((a * 256 + r) * 256 + g) * 256 + b. If a single color is specified both the pen and the brush will be set to the same color. There are several ways to define a color in BASIC256:

one of the defined color constants (see table below);
an integer to define the color where ((a * 256 + r) * 256 + g) * 256 + b,
- a - transparency 0 = transparent to 255 = opaque
- r - red 0 = off to 255 = full on
- g - green 0 = off to 255 = full on
- b - blue 0 = off to 255 = full on
the rgb function passing it 3 or 4 numbers from 0-255,
using an svg color name as a string as defined by the W3C,
or using a string with a “#” followed by 6 or 8 hexadecimal digits (“#ff0000”, “#a0ffffff”)

When drawing solid shapes (Chord,Circle,Pie,Poly,Rect, and Stamp) the border of the shape will be drawn with the pen color and the shape itself will be filled with the brush color. A brush color of CLEAR is used to not fill a closed shape.

If the current pen and brush are both set to CLEAR the pixels or shapes drawn will clear the pixels of the graphics output area and make them transparent. This is especially useful when creating sprites using the Spriteslice command.

Color Constant (Name)	ARGB Values	Integer
BLACK	255, 0, 0, 0	4278190080
WHITE	255, 255, 255, 255	4294506744
RED	255, 255, 0, 0	4294901760
DARKRED	255, 128, 0, 0	4286578688
GREEN	255, 0, 255, 0	4278255360
DARKGREEN	255, 0, 128, 0	4278222848
BLUE	255, 0, 0, 255	4278190335
DARKBLUE	255, 0, 0, 128	4278190208
CYAN	255, 0, 255, 255	4278255615
DARKCYAN	255, 0, 128, 128	4278222976
PURPLE	255, 255, 0, 255	4294902015
DARKPURPLE	255, 128, 0, 128	4286578816
YELLOW	255, 255, 255, 0	4294967040
DARKYELLOW	255, 128, 128 ,0	4286611456
ORANGE	255, 255, 102, 0	4294927872
DARKORANGE	255, 176, 61 ,0	4289344256
GREY	255, 164, 164 ,164	4288980132
DARKGREY	255, 128, 128 ,128	4286611584
CLEAR	0, 0, 0, 0	0

2016/08/12 21:00 · admin

Deprecated Form

In version 0.9.9.26 the statement form “color red, blue, green” or “color ( red, blue, green )” was deprecated and a warning will be displayed when it is encountered. It should be replaced with “color rgb ( red, blue, green )”.

Example

clg
color rgb(128,128,128)
rect 0,0,graphwidth, graphheight

penwidth 5
color green,red
circle 100,100,50

penwidth 1
color rgb(255,160,160)
circle 100,100,25

penwidth 5
color "firebrick","#fab856"
rect 150,150,100,100

color "papayawhip", "clear"
rect 175,175,100,100

Will draw the following:

History

0.9.5m	added “COLOR r,g,b” form and numeric representation of color names
0.9.9.26	Added brush color and deprecated the “COLOR r,g,b”.
0.9.9.28	Changed color values to include Alpha (transparency) and changed color constants to new ARGB values.
0.9.9.45	changed values to positive numbers following formula as documented.
2.0.99.4	Added ability to use string names and hex values for colors.

2016/01/01 22:40

Cos (Function)

Format

cos ( numeric_expression )

returns float_expression

Description

Computes the cosine of an angle expressed in radians.

Note

The cos function does not produce an exact result.

Example

clg
color black
# draw a line across the graphic output
line 0,150,300,150
# where do we start
lastx = 0
lasty = cos(0) * 50 + 150
# now step across the line and draw
for x = 0 to 300 step 5
   angle = x / 300 * 2 * pi
   y = cos(angle) * 50 + 150
   line lastx, lasty, x, y
   lastx = x
   lasty = y
next x

Draws

Currentdir (Function)

Format

currentdir
currentdir ( )

returns string_expression

Description

Returns the fully qualified path name to BASIC-256's current directory. For all systems (including Windows) a forward slash (/) will be used to separate folders in a full path.

History

0.9.6r

New To Version

2016/01/01 22:40

Day (Function)

Format

day
day ( )

returns integer_expression

Description

Returns the current system clock's day of the month (1-31).

Example

print "today's date is ";
print (month + 1) + "/" + day + "/" + year

will print|

today's date is 11/30/2009

History

0.9.4

New To Version

2016/01/01 22:40

DBClose (Statement)

Format

dbclose
dbclose ( )
dbclose database_number
dbclose ( database_number )

Description

Close an open SQLite database file. Database connections are numbered from 0 to 7. If the database number is omitted then database file #0 will be closed.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBCloseSet (Statement)

Format

dbcloseset
dbcloseset ( )
dbcloseset database_number
dbcloseset ( database_number )
dbcloseset database_number , database_recordset_number
dbcloseset ( database_number, database_recordset_number )

Description

Close the currently open record set opened by DBOpenSet.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBExecute (Statement)

Format

dbexecute sql_statement
dbexecute ( sql_statement )
dbexecute database_number , sql_statement
dbexecute ( database_number , sql_statement )

Description

Execute an SQL statement contained in the string expression on the open SQLite database file. This statement does not create a record set.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBFloat (Function)

Format

dbfloat ( numeric_expression )
dbfloat ( database_number , numeric_expression )
dbfloat ( database_number , database_recordset_number , numeric_expression )
dbfloat ( string_expression )
dbfloat ( database_number , string_expression )
dbfloat ( database_number , database_recordset_number , string_expression )

returns float_expression

Description

Return a floating point (decimal value) from the specified column number or name of the current row of the open recordset. If the field is a NULL value the decimal number 0.0 will be returned. NULL may be tested for by using the DBNull function.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections
0.9.9.22	Added column name or alias

2016/01/01 22:40

DBInt (Function)

Format

dbint ( numeric_expression )
dbint ( database_number , numeric_expression )
dbint ( database_number , database_recordset_number , numeric_expression )
dbint ( string_expression )
dbint ( database_number , string_expression )
dbint ( database_number , database_recordset_number , string_expression )

returns integer_expression

Description

Return an integer value from the specified column number or name of the current row of the open recordset. If the field is a NULL value the integer number 0 will be returned. NULL may be tested for by using the DBNull function.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections
0.9.9.22	Added column name or alias

2016/01/01 22:40

DBOpen (Statement)

Format

dbopen file_name
dbopen ( file_name )
dbopen database_number , file_name
dbopen ( database_number , file_name )

Description

Open an SQLite database file. If the file does not exist then create it. Up to eight database connections can be made at a time in a program. If the database number is not specified then connection 0 will be used.

Example

#database foo - create a database, populate a table, open a recordset and read data from table.

# create a new database file or open it
dbopen "dbtest.sqlite3"

# delete old foo table - trap error if new database
onerror errortrap
dbexecute "drop table foo;"
offerror
# create and populate
dbexecute "create table foo (id integer, words text, value decimal);"
dbexecute "insert into foo values (1,'one',3.14);"
dbexecute "insert into foo values (2,'two',6.28);"
dbexecute "insert into foo values (3,'three',9.43);"

# open a recordset and loop through the rows of data
dbopenset "select * from foo order by words;"
while dbrow()
	print dbint(0) + dbstring(1) + dbfloat(2)
end while
dbcloseset

# wrap everything up
dbclose
end

errortrap:
# accept error - display nothing - return to next statement
return

will display

1one3.14
3three9.43
2two6.28

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBOpenset (Statement)

Format

dbopenset sql_statement
dbopenset ( sql_statement )
dbopenset database_number , sql_statement
dbopenset ( database_number , sql_statement )
dbopenset database_number , database_recordset_number , sql_statement
dbopenset ( database_number , database_recordset_number , sql_statement )

Description

Perform an SQL statement and create a record set so that the program may loop through and use the results.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBRow (Function)

Format

dbrow
dbrow ( )
dbrow ( database_number )
dbrow ( database_number , database_recordset_number )

returns boolean_expression

Description

Function that advances the record set to the next row. Returns a true value if there is a row or false if we are at the end of the record set.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections

2016/01/01 22:40

DBString (Function)

Format

dbstring ( numeric_expression )
dbstring ( database_number , numeric_expression )
dbstring ( database_number , database_recordset_number , numeric_expression )
dbstring ( string_expression )
dbstring ( database_number , string_expression )
dbstring ( database_number , database_recordset_number , string_expression )

returns string_expression

Description

Return a string from the specified column number or name of the current row of the open recordset. If the field is a NULL value the empty string “” will be returned. NULL may be tested for by using the DBNull function.

Example

See example of usage on DBOpen page.

External Links

More information about databases in general and SQLite specifically can be found at SQLite Home Page and SQL at Wikipedia.

History

0.9.6y	New to Version
0.9.9.19	Added ability to have 8 database connections
0.9.9.22	Added column name or alias

2016/01/01 22:40

Degrees (Function)

Format

degrees ( numeric_expression )

returns float_expression

Description

Converts an angle in radians to degrees.

Dim (Statement)

Format

Fill an Existing Array With a Single Value

dim variable fill expression
dim variable[] fill expression

Description

Returns a newly created single dimensional array of length integer or a 2 dimensional array that can be addressed by row and column. By default the elements in the array are left uninitialized (empty), You may add the fill option to fill all elements with a single value.

The first element of an array has an index of 0 (zero). Indexes range from 0 to length-1.

The dim statement can also be used to create a new array that is a duplicate of another array. The form “DIM var = var” does this by dimensioning a new array in memory and copying all of the data from the original array.

Example

dim z = {1, 2, 3, 4, 5}
print z[0] + " " + z[4]

will print

1 5

Example Two

dim c(4)
c[0] = "cow"
c[1] = "brown"
c[2] = "how"
c[3] = "now"
print c[2] + " " + c[3] + " ";
print c[1] + " " + c[0] + "?"

will print

how now brown cow?

History

1.99.99.55	Cleaned up documentation and added array copy.
1.99.99.56	Added fill clause
1.99.99.57	Added additional fill options
1.99.99.72	added the [] when setting one array from another

2016/01/01 22:40

End (Statement)

Format

end

Description

Halts program execution.

Example

print "I am done."
end
print "Or am I?"

will print

I am done.

Eof (Function)

Format

eof
eof()
eof(open_file_number)

returns boolean_expression

Description

Returns a binary flag (true/false) that will signal if we have read to the End Of File (EOF). If file number is not specified then file number zero (0) will be used.

If the open file number is a serial port (opened with OpenSerial) then EOF returns a true value when there is pending data to receive. EOF that we are at the end of data but with this type of data source, new data may be received at any time. This behaviour is different than with a file.

History

0.9.4	New To Version
1.1.4.0	Added serial port logic

2016/01/01 22:40

Exists (Function)

Format

exists ( file_name )

returns boolean_expression

Description

Returns a binary flag (true/false) that will signal if the file path or directory specified by the expression exists.

History

0.9.4	New To Version
2.0.0.12	Added test for directory/folder

2016/01/01 22:40

FastGraphics (Statement)

Format

fastgraphics

Description

Turns fastgraphics mode on, until the program is halted. Fastgraphics mode means that the graphics display is not updated until a REFRESH command is issued. It can be used to significantly speed up complex animations and eliminate flicker.

Note

When doing animation, it's recommended to do all of your drawing commands in subroutines and use a single REFRESH command after all drawing has been done for that frame.

Float (Function)

Format

float ( expression )

returns float_expression

Description

Convert expression to a floating point (decimal) number. Float will convert a string or an integer to a decimal value. If the expression can not be converted then a zero will be returned.

History

0.9.4

New To Version

2016/01/01 22:41

Floor (Function)

Format

floor ( numeric_expression )

returns integer_expression

Description

Returns the greatest integer that is less than or equal to expression

Value	int()	ceil()	floor()
-4.56	-4	-4	-5
-0.56	0	0	-1
0.56	0	1	0
5.56	5	6	5

Font (Statement)

Format

font font_name, font_size_in_point, font_weight
font ( font_name, font_size_in_point, font_weight )

Description

Sets the font used by the text command to font_name. The size that the font will be draw on on the screen is defined in points (1/72“). The third value represents the line weight (from 1 to 100) used in drawing the text on the screen. Typical weights are: Light=25, Normal=50, and Bold=75.

Common Windows Fonts

Example

color grey
rect 0,0,graphwidth,graphheight
color red
font "Times New Roman",18,50
text 10,100,"This is Times New Roman"
color darkgreen
font "Tahoma",28,100
text 10,200,"This is BOLD!"

Will draw.

New To Version

0.9.4

2016/01/01 22:41

GetColor (Function)

Format

getcolor
getcolor()

returns rgb_expression

Description

Returns the ARGB value of the current drawing pen color (last set by color statement). ARGB is calculated by the formula ( (a * 256 + r) * 256 + b) * 256 + g where alpha, red, green, and blue are between 0 and 255. If the drawing color has been set to CLEAR a 0 will be returned.

Example

color red, blue
print getcolor

will print

-65536

History

0.9.5m	New to version
0.9.9.28	Changed to return ARGB value

2016/01/01 22:41

GetSlice (Function)

Format

getslice(x_position, y_position, width, height)

returns List of Values

Description

Return a 2 dimensional array of the pixels in the rectangle defined by the parameters.

Example

clg
color red
plot 1,1
color green
plot 1,2
color blue
plot 2,1
color yellow
plot 2,2

vals = getslice(1, 1, 2, 3)

for rows = 0 to 2
  for cols = 0 to 1
    print "("+rows+","+cols+")="+vals[rows,cols]
  next cols
next rows

displays

(0,0)=-65536
(0,1)=-16776961
(1,0)=-16711936
(1,1)=-256
(2,0)=0
(2,1)=0

New To Version

0.9.6b

History

0.9.6b	New To Version
1.99.99.65	Changed return value to a 2 dimensional array of pixel values

2016/01/01 22:41

Goto (Statement)

Format

goto label

Description

Jumps to the specified label.

Example

print "I";
goto skipit
print " don't";
skipit: #
print " want cookies."

will print

I want cookies.

Notes

As of version 0.9.9.2 Goto, Gosub, and labels can not be used in Function and Subroutine definitions.

2016/01/01 22:41

Graphheight (Function)

Format

graphheight
graphheight()

returns integer_expression

Description

Returns the height (y dimension) of the current graphics display window.

History

0.9.3

New To Version

2016/01/01 22:41

Graphsize (Statement)

Format

graphsize graphich_width, graphich_height
graphsize ( graphich_width, graphich_height )

Description

Changes the size of the graphics display window and redraws the BASIC256 application.

History

0.9.3

New To Version

2016/01/01 22:41

Graphwidth (Function)

Format

graphwidth
graphwidth()

returns integer_expression

Description

Returns the width (x dimension) of the current graphics display window.

History

0.9.3

New To Version

2016/01/01 22:41

Hour (Function)

Format

hour
hour()

returns integer_expression

Description

Returns the current system clock's hour of the day (0-23).

Example

# display nice date
dim months$(12)
months$ = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
print year + "-" + months$[month] + "-" + right("0" + day, 2)
# display pretty time
h = hour
if h > 12 then
h = h - 12
ampm$ = "PM"
else
ampm$ = "AM"
end if
if h = 0 then h = 12
print  right("0" + h, 2) + "-" + right("0" + minute, 2) + "-" + right("0" + second, 2) + " " + ampm$

Will print something like.

2010-July-15
10-00-02 PM

History

0.9.4

New To Version

2016/01/01 22:41

Instr (Function)

Format

instr ( haystack_string_expression , needle_string_expression )
instr ( haystack_string_expression , needle_string_expression , start_expression )
instr ( haystack_string_expression , needle_string_expression , start_expression , boolean_expression)

returns integer_expression

Description

Check to see if the string needle_string_expression is contained in the string haystack_string_expression. If it is, then this function will return the index of starting character of the first place where needle_string_expression occurs. Otherwise, this function will return 0.

You may optionally specify a starting location for the search to begin start_expression. If the start is 1 or greater the search will begin from the specified character from the start. If the start is < 0 then the search will begin from the nth character from the end. The search will ALWAYS look forward.

An optional boolean_expression may be used to specify that the search will treat upper and lower case letters the same.

Note

String indices begin at 1.

Example

print instr("Hello", "lo")
print instr("101,222,333",",",5)

will display

4
8

History

0.9.6.55	New to Version
1.99.99.53	Added start position < 0

2016/01/01 22:41

Int (Function)

Format

int ( expression )

returns integer_expression

Description

Convert expression to an integer (whole) number. Int will convert a string or a float to an integer value. If the expression can not be converted then a zero will be returned.

Value	int()	ceil()	floor()
-4.56	-4	-4	-5
-0.56	0	0	-1
0.56	0	1	0
5.56	5	6	5

Imgload (Statement)

Format

imgload x_position, y_position, file_name
imgload ( x_position, y_position, file_name )
imgload x_position, y_position, scale_expression, file_name
imgload ( x_position, y_position, scale_expression, file_name )
imgload x_position, y_position, scale_expression, rotation_expression, file_name
imgload ( x_position, y_position, scale_expression, rotation_expression, file_name )

Description

Load an image or picture from a file and paint it on the Graphics Output Window.
The parameters x_position and y_position represent the location on the screen for the CENTER of the loaded image. This behaviour is different than all of the other graphics statements. The axis of rotation will also be this CENTER point.
The Imgload starement will read in most common image file formats including: BMP (Windows Bitmap), GIF (Graphic Interchange Format),JPG/JPEG (Joint Photographic Experts Group), and PNG (Portable Network Graphics).
Optionally scales size of the loaded image by the defined scale (1=normal size). Also optionally rotates the image by a specified angle around the images center (clockwise in radians).

History

0.9.6l

New to Version

2016/01/01 22:41

Input (Statement)

Format

input prompt, variable
input variable
input prompt, array_variable [ index ]
input array_variable [ index ]
input prompt, array_variable [ row_index, column_index ]
input array_variable [ row_index, column_index ]

input float prompt, variable
input float variable
input float prompt, array_variable [ index ]
input float array_variable [ index ]
input float prompt, array_variable [ row_index, column_index ]
input float array_variable [ row_index, column_index ]

input integer prompt, variable
input integer variable
input integer prompt, array_variable index ]
input integer array_variable [ index ]
input integer prompt, array_variable [ row_index, column_index ]
input integer array_variable [ row_index, column_index ]

input string prompt, variable
input string variable
input string prompt, array_variable [ index ]
input string array_variable [ index ]
input string prompt, array_variable [ row_index, column_index ]
input string array_variable [ row_index, column_index ]

Description

Waits for the user to type a line of text into the text output window. When the user hits the enter or return key, the user's input is stored in to a variable.

Using just INPUT, if the user types a valid number it will be converted and stored as either an integer or a float. If INPUT is unable to convert what is typed, it will be saved as a string.

You may force the type conversion by specifying INPUT FLOAT, INPUT INTEGER, or INPUT STRING.

User may optionally be prompted for the input by prompt.
References to array elements may also be specified.

History

1.99.99.14

Added INPUT FLOAT, INPUT INTEGER, INPUT STRING and made INPUT try to assign variable the correct type (integer, float, or string) based upon the user entry.

2020/11/22 21:31

Key (Function)

Format

key
key()
key(getUnicode)

returns integer_expression

Description

Immediately returns an integer value corresponding to the currently pressed keyboard key (if the argument is omitted or false), returns the Unicode character number if the argument is true. If no key has been pressed since the last call to the key function then the number zero (0) will be returned.

In Unicoide mode the key function will not return keypresses like backspace, escape, arrows, shift, alt, or the control keys. It will return upper/lowercase letters.

Note

if key = 47 then print key

will not display the desired results, because it's calling key twice in succession, and will return different values each time. This code will do what you want:

a = key
if a = 47 then print a

Partial List of Keys

ESC=16777216	Space=32
0=48	1=49	2=50	3=51	4=52	5=53	6=54	7=55
8=56	9=57
A=65	B=66	C=67	D=68	E=69	F=70	G=71	H=72
I=73	J=74	K=75	L=76	M=77	N=78	O=79	P=80
Q=81	R=82	S=83	T=84	U=85	V=86	W=87	X=88
Y=89	Z=90
Down Arrow=16777237	Up Arrow=16777235	Left Arrow=16777234	Right Arrow=16777236

Click here for a complete list of key values

Example

#press any keys
loop:
pause 1
a = key
print a+"  "+chr(a)
goto loop

Example

# get unicode letters until you press a control x
while true
	k = key(true)
	if k <> 0 then
		print k, chr(k)
		if k = 24 then exit while
	endif
	pause .1
end while

History

2.0.0.11

added optional Unicode character argument

2016/01/01 22:41

LastError (Function)

Format

lasterror
lasterror ( )

returns integer_expression

Description

Returns the last runtime error number.

Example

See examples of usage on OnError and ThrowError pages.

History

0.9.6z

New To Version

2016/01/01 22:41

LastErrorExtra (Function)

Format

lasterrorextra
lasterrorextra ( )

returns string_expression

Description

Returns statement specific “extra” information about the error.

Example

See examples of usage on OnError and ThrowError pages.

History

0.9.6z

New To Version

2016/01/01 22:41

LastErrorLine (Function)

Format

lasterrorline
lasterrorline ( )

returns integer_expression

Description

Returns the line number in the program where the runtime error happened.

Example

See examples of usage on OnError and ThrowError pages.

History

0.9.6z

New To Version

2016/01/01 22:41

LastErrorMessage (Function)

Format

lasterrormessage
lasterrormessage ( )

returns string_expression

Description

Returns a string representing the last runtime error.

Example

See examples of usage on OnError and ThrowError pages.

History

0.9.6z

New To Version

2016/01/01 22:41

Left (Function)

Format

left( string_expression, length_expression)

returns string_expression

Description

If length is greater than or equal to zero, returns a portion of the specified string_expression, starting from the first character on the left and continuing for length_expression characters. If length is less than zero then remove length_expression characters from the left of the string.

Example

print left("Hello", 2)
print left("Hello", -2)

will display

He
llo

History

0.9.5b	New To Version
1.99.99.53	Added length < 0

2016/01/01 22:41

Length (Function)

Format

length( string_expression )
length( array )
length( map )

returns integer_expression

Description

Returns the number of characters in string_expression, the number of elements in a map, or the number of values in an array.

NOTE: The length function returns the total number of items in a two dimensional array (rows * columns).

Line (Statement)

Format

line x1_position, y1_position, x2_position, y2_position
line ( x1_position, y1_position, y2_position, y2_position )

Description

Draws a line from the point (x1_position, y1_position) to the point (x2_position, y2_position) with the current pen color. The width of the line may be adjusted using the PenWidth statement.

Example

clg

color black

line 50,50,200,200

penwidth 5
line 100,200,200,200

penwidth 10
line 100,200,50,50

draws

History

2016/01/01 22:41

Log (Function)

Format

log ( numeric_expression )

returns float_expression

Description

Return the base e lograthim of numeric_expression.

History

0.9.5w

New To Version

2016/01/01 22:41

Lower (Function)

Format

lower ( string_expression )

returns string_expression

Description

Returns string_expression with all alphabetic characters converted to lower case.

History

0.9.5e

New To Version

2016/01/01 22:41

Mid (Function)

Format

mid( string_expression, start_expression, length_expression)

returns string_expression

Description

Returns a portion of the specified string_expression, starting from the start character, and continuing for length_expression characters or the end of the string_expression.

Example

print mid("Hello", 2, 3)
print mid("Hello", 2, 999)

will display

ell
ello

History

0.9.5b	New To Version
1.99.99.53	Added length < 0
1.99.99.53	Added start position < 0

2016/01/01 22:41

Minute (Function)

Format

minute
minute ( )

returns integer_expression

Description

Returns the current system clock's minute of the hour (0-59).

Example

# display nice date
dim months$(12)
months$ = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
print year + "-" + months$[month] + "-" + right("0" + day, 2)
# display pretty time
h = hour
if h > 12 then
h = h - 12
ampm$ = "PM"
else
ampm$ = "AM"
end if
if h = 0 then h = 12
print  right("0" + h, 2) + "-" + right("0" + minute, 2) + "-" + right("0" + second, 2) + " " + ampm$

Will print something like.

2010-July-15
10-00-02 PM

History

0.9.4

New To Version

2016/01/01 22:41

Month (Function)

Format

month
month ( )

returns integer_expression

Description

Returns the current system clock's month. January is 0, February is 1… December is 11.

Example

cls
dim n$(12)
n$ = {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}
print day + "-" + n$[month] + "-" + year

on New Years will display

1-Jan-2010

History

0.9.4

New To Version

2016/01/01 22:41

Mouseb (Function)

Format

mouseb
mouseb ( )

returns integer_expression

Description

Returns the buttons that currently pressed on the mouse (if over the graphic output). Returns 0 if no click has been recorded.

Return Values
Constant	Value
MOUSEBUTTON_NONE	0
MOUSEBUTTON_LEFT	1
MOUSEBUTTON_RIGHT	2
MOUSEBUTTON_CENTER	4
MOUSEBUTTON_DOUBLECLICK	32

2016/08/14 15:38 · admin

History

0.9.4d	New To Version
1.99.99.58	Added Named Constants

2016/01/01 22:41

Mousex (Function)

Format

mousex
mousex ( )

returns integer_expression

Description

Returns the current or last mouse x location of the mouse pointer over the graphic output.

History

0.9.4d

New To Version

2016/01/01 22:41

Mousey (Function)

Format

mousey
mousey ( )

returns integer_expression

Description

Returns the current or last mouse y location of the mouse pointer over the graphic output.

History

0.9.4d

New To Version

2016/01/01 22:41

NetClose (Statement)

Format

netclose
netclose ( )
netclose network_socket_number
netclose ( network_socket_number )

Description

Close the specified network connection (socket). If network_socket_number is not specified socket number zero (0) will be used.

Example

See example of usage on NetConnect page.

History

0.9.6.31

New To Version

2016/01/01 22:41

NetConnect (Statement)

Format

netconnect server_name, port_number
netconnect ( server_name, port_number )
netconnect network_socket_number, server_name, port_number
netconnect ( network_socket_number, server_name, port_number )

Description

Open a network connection (client) to a server. The IP address or host name of a server are specified in the server_name argument, and the specific network port number in the port_number argument. If network_socket_number is not specified socket number zero (0) will be used.

Example

Open two instances of BASIC-256 on a single computer. Paste the “server” code into one and the “client” code into the other. Run the server first and the client second. You can see how the messages are sent back and forth between the two different processes.

Server Code

# get a message and send back success
print "wait for connection on " + netaddress()
netlisten 9997
print "got connection"
do
   while not netdata
      pause .1
      print ".";
   end while
   n$ = netread
   print n$
   netwrite "I got '" + n$ + "'."
until n$ = "end"
netclose

will display (where xxx.xxx.xxx.xxx is the IPv4 address of your computer)

wait for connection on xxx.xxx.xxx.xxx
got connection
.1 Hi There
....2 Hi There
........3 Hi There
..........4 Hi There
.....5 Hi There
.......6 Hi There
....7 Hi There
..........8 Hi There
....9 Hi There
.....10 Hi There
.end

Client Code

# have the user enter a message and send it to the server
input "enter message?", m$
netconnect "127.0.0.1", 9997
for t = 1 to 10
   pause rand
   netwrite t + " " + m$
   print netread
next t
netwrite "end"
print netread
netclose

will display

enter message?Hi There
I got '1 Hi There'.
I got '2 Hi There'.
I got '3 Hi There'.
I got '4 Hi There'.
I got '5 Hi There'.
I got '6 Hi There'.
I got '7 Hi There'.
I got '8 Hi There'.
I got '9 Hi There'.
I got '10 Hi There'.
I got 'end'.

History

0.9.6.31

New To Version

2016/01/01 22:41

NetData (Function)

Format

netdata
netdata ( )
netdata ( network_socket_number )

returns boolean_expression

Description

Returns a true value if there is data waiting to be read in using the NetRead function, else returns false. If network_socket_number is not specified socket number zero (0) will be used.

Example

See example of usage on NetConnect page.

History

0.9.6.31

New To Version

2016/01/01 22:41

NetListen (Statement)

Format

netlisten port_number
netlisten ( port_number)
netlisten network_socket_number, port_number
netlisten ( network_socket_number, port_number)

Description

Open up a network connection (server) on a specific port address and wait for another program to connect. If network_socket_number is not specified socket number zero (0) will be used.

Example

See example of usage on NetConnect page.

History

0.9.6.31

New To Version

2016/01/01 22:41

NetRead (Function)

Format

netread
netread ( )
netread ( network_socket_number )

returns string_expression

Description

Read data from the specified network connection and return it as a string. This function will wait until data is received. If network_socket_number is not specified socket number zero (0) will be used.

Example

See example of usage on NetConnect page.

History

0.9.6.31

New To Version

2016/01/01 22:41

NetWrite (Statement)

Format

netwrite string_expression
netwrite ( string_expression )
netwrite network_socket_number, string_expression
netwrite ( network_socket_number, string_expression )

Description

Send a string to the specified open network connection. If network_socket_number is not specified socket number zero (0) will be used.

Example

See example of usage on NetConnect page.

History

0.9.6.31

New To Version

2016/01/01 22:41

Open and Openb (Statement)

Format

open file_name
open(file_name)
open open_file_number, file_name
open(open_file_number, file_name)
openb file_name
openb(file_name)
openb open_file_number, file_name
openb(open_file_number, file_name)

Description

Opens a file for reading and writing. The file_name is specified as a string, and may be an absolute or relative path. If the file number is not specified file number zero (0) will be used.
Openb opens the file in a “binary safe” mode. This type of file open is recommended for files where the Readbyte and Writebyte statements are used for input/output.

Note

BASIC256 may have up to 8 files open at a single time. The files are numbered from 0 to 7. Opening a file to a number while another is already open to that number will close the open file.

History

0.9.?

openb was added to open binary files

2016/01/01 22:41

OffError (Statement)

Format

offerror

Description

Removes the last error trap defined with the OnError statement. If all of the traps have been removed then error trapping is restored to the default behavior.

You may not execute an OffError statement inside a Try / Catch / End Try statement.

Example

See examples of usage on OnError and ThrowError pages.

History

0.9.6z

New To Version

2016/01/01 22:41

OnError (Statement)

Format

onerror label

Description

Causes the Gosub at label to be executed when a runtime error occurs. Program control may be resumed at the next statement with a Return statement in the subroutine. Error traps are kept in a stack so that the last defined trap, that has not been removed with an OffError will be the active one.

You may not execute an OnError statement inside a Try / Catch / End Try statement.

Example

# test error trapping
onerror nicetrap
print 1
next haha
print 2
open 999, "bogus.file"
print "Runs Anyway"

# test error trapping off and fail at any error (default)
offerror
print 3
next hoho
print "never get here"

end

nicetrap:
# this is the nice error handler
print "trap and run - error on line " + lasterrorline + " - error number " + lasterror + " message " + lasterrormessage + " (" + lasterrorextra + ")"
return

will display

1
trap and run - error on line 4 - error number 4 message Next without FOR ()
2
trap and run - error on line 6 - error number 5 message Invalid File Number ()
Runs Anyway
3
ERROR on line 12: Next without FOR

See additional example of usage on ThrowError page.

History

0.9.6z	New To Version
1.99.99.33	Removed the ability to use a subroutine for error trapping

2016/01/01 22:41

Pause (Statement)

Format

pause numeric_expression
pause (numeric_expression)

Description

Halts execution for the specified number of seconds. The value of seconds may be a decimal value, so sub-second precision is possible.

Pixel (Function)

Format

pixel (x_position, y_position )

returns rgb_expr

Description

Returns the RGB value of the pixel at the x_position and y_position coordinate. If the pixels has not been set since the last Clg command or was drawn with the color CLEAR a -1 will be returned.

Sample Program

The following sample program shows how to use the binary and operation and integer division to extract the red, blue, and green values from the number returned by pixel.

color red
rect 0,0,100,100

color rgb(100,50,150)
rect 100,100,100,100

color white
rect 200,200,100,100

while true
	c = pixel(mousex, mousey)
	r = (c & 0xff0000) \ 0x10000
	g = (c & 0xff00) \ 0x100
	b = (c & 0xff)
	print r,g,b
	pause .5
end while

History

0.9.5m	New To Version
2.0.0.4	Added example

2016/01/01 22:41

Plot (Statement)

Format

plot x_position, y_position
plot ( x_position, y_position )

Description

Changes the pixel located at x_position,y_position in the graphics output window to the current color.

History

2016/01/01 22:41

Poly (Statement)

Format

poly variable[]
poly ( variable[] )
poly { x1, y1, x2, y2, x3, y3 ... }
poly { {x1, y1}, {x2, y2}, {x3, y3} ... }

Description

Draws a polygon. The sides of the polygon are defined by the values stored in the array, which should be stored as x,y pairs, sequentially. The length of a one dimensional array/2 or the number of rows on a two dimensional array will define the number of points.

One dimensional arrays and lists must have at least six values and an even number of values. A two dimensional array may have 3 or more rows but must have two columns.

Example

# using an array
clg blue
color green
dim tri = {100, 100, 200, 200, 100, 200}
poly tri[]

# using a list
clg blue
color green
poly {{100, 100}, {200, 200}, {100, 200}}

Both programs use the poly statement to draw the following:

History

0.9.4	number of points in the array argument was removed from the poly statement
1.99.99.55	two dimensional list support was added
1.99.99.72	added required [] to passing variable array

2016/01/01 22:41

Print (Statement)

Format

print expression [ ; ]
? expression [ ; ]
print expression ,expression…
? expression ,expression…

Description

Writes text to the text output window, appending a new line. If multiple expressions are included in a single print statement, separated by commas, they will be output in 14 character wide left justified columns.

If the optional semicolon is included at the end of the statement, no new line is appended. The new line suppress is only available for print with a single expression.

Example

print "all one"
? "some";
print "more"
for t = 1 to 10
	? t, t*2
next t

Will output:

all one
somemore
1             2
2             4
3             6
4             8
5             10
6             12
7             14
8             16
9             18
10            20

History

2.0.0

Added columnar output (comma) and the '?' as shortcut

2016/01/01 22:41

PutSlice (Statement)

Format

putslice x_position, y_position, variable[]
putslice ( x_position, y_position, variable[] )
putslice x_position, y_position, { x1, y1, x2, y2, x3, y3 ... }
putslice ( x_position, y_position, { x1, y1, x2, y2, x3, y3 ... } )

Description

Put the graphics stored in the slice array on the screen at x,y.

History

0.9.6b	New To Version
1.99.99.65	Changed from a string of data to a 2 dimensional array. Removed the transparency color option.
1.99.99.72	added required [] to passing variable array

2016/01/01 22:41

Radians (Function)

Format

radians ( numeric_expression )

returns float_expression

Description

Converts an angle in degrees to radians.

History

2016/01/01 22:41

Rand (Function)

Format

rand
rand ( )

returns float_expression

Description

Returns a random number between 0 and 1. The distribution of the values is uniform.

Note

To produce random numbers between other values, simple multiply or add the appropriate numbers. For example, to generate an integer between 0 and 10, use int(rand * 10).

History

2016/01/01 22:41

Read (Function)

Format

read
read ( )
read ( open_file_number )

returns string_expression

Description

Reads and returns a token from an open file. A token is any string of characters that is separated by a space, tab, or newline character. If the file number is not specified file number zero (0) will be used.

History

2016/01/01 22:41

Readline (Function)

Format

readline
readline ( )
readline ( open_file_number )

returns string_expression

Description

Reads and returns an entire line from an open file. If the file number is not specified file number zero (0) will be used.

History

2016/01/01 22:41

Rect (Statement)

Format

rect x_position,y_position,width,height
rect ( x_position, y_position, width, height )

Description

Draws a width x height pixel rectangle using the current pen and brush colors. The top left corner is located at x_position,y_position.

Example

clg

color red
rect 50,50,150,150

penwidth 10
color blue, yellow
rect 100,100,150,150

color green, clear
rect 10,130,280,40

draws

History

2016/01/01 22:41

Redim (Statement)

Format

redim array_variable ( integer )
redim array_variable ( integer ) fill expression
redim array_variable [ integer ]
redim array_variable [ integer ] fill expression redim array_variable ( array_size_rows , array_size_columns)
redim array_variable ( array_size_rows , array_size_columns) fill expression
redim array_variable [ array_size_rows , array_size_columns]
redim array_variable [ array_size_rows , array_size_columns] fill expression

Description

Re-sizes a previously created array, preserving data. If an array is enlarged and the fill clause is not included then the new elements will not be initialized (and will be unassigned). If an array is reduced in size the elements trimmed from the end are lost.

History

0.9.5t	New To Version
1.99.99.57	Added fill for unassigned elements

2016/01/01 22:41

Refresh (Statement)

Format

refresh

Description

Updates the graphics output window to show all drawing since the previous refresh command. Refresh only works in Fastgraphics mode

Rem (Statement)

Format

rem comment
# comment

Description

Line comment. A line beginning with REM (or the shortened #) is ignored.

Reset (Statement)

Format

reset
reset()
reset(open_file_number)

Description

Clears an open file. All data stored in the file is lost. If the file number is not specified file number zero (0) will be used.

For serial ports the reset statement has not been implemented.

History

1.1.4.0

Added Serial Port

2016/01/01 22:41

Rgb (Function)

Format

rgb(red, green, blue )
rgb(red, green, blue, alpha )

returns integer_expression

Description

Returns the ARGB value of the color made up of the red, green, and blue components. Legal values for red, green, blue, and alpha are 0 to 255. if alpha (transparency) is not defined then 255 will be used making the color opaque (not-transparent).

Color Constant (Name)	ARGB Values	Integer
BLACK	255, 0, 0, 0	4278190080
WHITE	255, 255, 255, 255	4294506744
RED	255, 255, 0, 0	4294901760
DARKRED	255, 128, 0, 0	4286578688
GREEN	255, 0, 255, 0	4278255360
DARKGREEN	255, 0, 128, 0	4278222848
BLUE	255, 0, 0, 255	4278190335
DARKBLUE	255, 0, 0, 128	4278190208
CYAN	255, 0, 255, 255	4278255615
DARKCYAN	255, 0, 128, 128	4278222976
PURPLE	255, 255, 0, 255	4294902015
DARKPURPLE	255, 128, 0, 128	4286578816
YELLOW	255, 255, 255, 0	4294967040
DARKYELLOW	255, 128, 128 ,0	4286611456
ORANGE	255, 255, 102, 0	4294927872
DARKORANGE	255, 176, 61 ,0	4289344256
GREY	255, 164, 164 ,164	4288980132
DARKGREY	255, 128, 128 ,128	4286611584
CLEAR	0, 0, 0, 0	0

2016/08/12 21:00 · admin

History

0.9.5m	New to version
0.9.9.28	added alpha (transparency}

2016/01/01 22:41

Right (Function)

Format

right( string_expression, length_expression)

returns string_expression

Description

If length is greater than or equal to zero, returns a portion of the specified string_expression, starting from the first character on the right and continuing for length_expression characters. If length is less than zero then remove length_expression characters from the right of the string.

Example

print right("Hello", 2)
print right("Hello", -2)

will display

lo
Hel

History

0.9.5b	New To Version
1.99.99.53	Added length < 0

2016/01/01 22:42

Say (Statement)

Format

say expression
say ( expression )

Description

Uses the the system Text to Speech (TTS) engine to say the expression. In LINUX the FLite or eSpeak libraries are required. In Windows the current default SAPI voice will be used.

History

0.9.4	New To Version
1.0.0.0

2016/01/01 22:42

Second (Function)

Format

second
second ( )

returns integer_expression

Description

Returns the current system clock's second of the current minute (0-59).

Example

# display nice date
dim months$(12)
months$ = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
print year + "-" + months$[month] + "-" + right("0" + day, 2)
# display pretty time
h = hour
if h > 12 then
h = h - 12
ampm$ = "PM"
else
ampm$ = "AM"
end if
if h = 0 then h = 12
print  right("0" + h, 2) + "-" + right("0" + minute, 2) + "-" + right("0" + second, 2) + " " + ampm$

Will print something like.

2010-July-15
10-00-02 PM

History

0.9.4

New To Version

2016/01/01 22:42

Seek (Statement)

Format

seek location
seek ( location )
seek open_file_number, location
seek ( open_file_number, location )

Description

Moves the read/write location to a specific location (offset in bytes from the start of the file) within an open file. If the file number is not specified file number zero (0) will be used.

For serial ports, the seek statement is not implemented.

History

0.9.4	New To Version
1.1.4.0	Added Serial Port

2016/01/01 22:42

Sin (Function)

Format

sin ( numeric_expression )

returns float_expression

Description

Computes the sine of expression. Expression must be in radians.

Note

The sin function does not produce an exact result.

Example

clg
color black
# draw a line across the graphic output
line 0,150,300,150
# where do we start
lastx = 0
lasty = sin(0) * 50 + 150
# now step across the line and draw
for x = 0 to 300 step 5
   angle = x / 300 * 2 * pi
   y = sin(angle) * 50 + 150
   line lastx, lasty, x, y
   lastx = x
   lasty = y
next x

Draws

Size (Function)

Format

size
size ( )
size ( open_file_number )

returns integer_expression

Description

Returns the length, in bytes, of an opened file. If the file number is not specified file number zero (0) will be used.

For a serial port, size returns the number of bytes that has been received but not read. This can be used to dimension an array to hold data being received or to make sure a certian number of bytes have been received.

History

0.9.4	New To Version
1.1.4.0	Added Serial Port

2016/01/01 22:42

Sound (Statement)

Format

sound frequency, duration
sound ( frequency, duration )
sound array[]
sound ( array[] )
sound { frequency1, duration1, frequency2, duration2, ... }

Polyphonic Sounds

sound array[,]
sound ( array[,] )
sound { { frequency1, duration1 }, { frequency2, duration2 }, ... }

Description

Play a sound from the computer's speakers.Frequency is expressed in Hz and duration is expressed in milliseconds (1000 in a second). An array or list containing frequency and duration may also be passed. This eliminates any clicking between sounds when more than one is being output sequentially.

One dimensional arrays and lists must have an even number of values. A two dimensional array may have any number of rows but must have two columns.

History

0.9.5g	Sound support for LINUX systems was added
0.9.5h	Windows sound was changed to use the default sound device
1.99.99.55	two dimensional list support was added
1.99.99.72	polyphonic sounds were added and the [] on array variables is now required

2016/01/01 22:42

Spritecollide (Function)

Format

spritecollide ( sprite_number, sprite_number )

returns boolean_expression

Description

Function returns true if the two sprites are colliding. The Spritecollide function assumes that the sprites are bounded by a rectangle the size of the loaded image. Collision is calculated by using these rectangles. For round or oddly shaped sprites this function may over detect collision.

History

0.9.6n

New To Version

2016/01/01 22:42

Spritedim( Statement)

Format

spritedim posint_expr
spritedim ( posint_expr )

Description

Create sprite placeholders in memory. Sprites are accessed in your program by a sprite number from 0 to n-1.

Example

# creates a sprite with number 0
clg
fastgraphics
spritedim 1
a$="Basic 256"
Text 0,0,a$
spriteslice 0,0,0,textwidth (a$),textheight()
spriteshow 0

# rotates and enlarges sprite
for n=0 to 2*pi step .002
clg
spriteplace 0,150,150,n,n
refresh
next n

History

0.9.6n

New To Version

2016/01/01 22:42

Spriteh (Function)

Format

spriteh ( sprite_number )

returns integer_expression

Description

Returns the height, in pixels, of a loaded sprite.

History

0.9.6n

New To Version

2016/01/01 22:42

Spritehide (Statement)

Format

spritehide sprite_number
spritehide ( sprite_number )

Description

Hides a sprite. All image and position information is retained.

History

0.9.6n

New To Version

2016/01/01 22:42

Spriteload (Statement)

Format

spriteload sprite_number, file_name
spriteload ( sprite_number, file_name )

Description

Load an image or picture from a file and save it as a sprite. The sprite will be active and movable but will not display on the screen until the Spriteshow statement is executed for that sprite.

The Spriteload statement will read in most common image file formats including: BMP (Windows Bitmap), GIF (Graphic Interchange Format),JPG/JPEG (Joint Photographic Experts Group), and PNG (Portable Network Graphics).

History

0.9.6n

New To Version

2016/01/01 22:42

Spritemove (Statement)

Format

spritemove sprite_number, x_position, y_position
spritemove ( sprite_number, x_position, y_position )
spritemove sprite_number, x_position, y_position, scale_expression
spritemove ( sprite_number, x_position, y_position, scale_expression )
spritemove sprite_number, x_position, y_position, scale_expression, rotate_expression
spritemove ( sprite_number, x_position, y_position, scale_expression, rotate_expression )

Description

Move a sprite from its current position by the specified number of pixels. Motion will be limited to the current screen. Optionally the sprite may be rotated or scaled by defining optional the rrotate_expr and scale_expression parameters. The degree rotate_expression is measured in radians. Rotation and scaling are relative to the previous state of the sprite.

History

0.9.6n	New To Version
0.9.9.15	Rotate and scale added

2016/01/01 22:42

Spriteplace (Statement)

Format

spriteplace sprite_number, x_position, y_position
spriteplace ( sprite_number, x_position, y_position )
spriteplace sprite_number, x_position, y_position, scale_expression
spriteplace ( sprite_number, x_position, y_position, scale_expression )
spriteplace sprite_number, x_position, y_position, scale_expression, rotate_expression
spriteplace ( sprite_number, x_position, y_position, scale_expression, rotate_expression )

Description

Place the center of a sprite at a specific location on the screen (x,y). Like Imgload sprite positioning is relative to the center of the sprite and not the top left corner as with most other graphical statements.

Optionally the sprite may be rotated or scaled by defining optional the rotate_expression and scale_expression parameters. The degree rotate_expression is measured in radians.

Example

See Spritedim

History

0.9.6n	New To Version
0.9.9.15	Added rotate and scale

2016/01/01 22:42

Spriteshow (Statement)

Format

spriteshow sprite_number
spriteshow ( sprite_number )

Description

Show a hidden sprite.

Example

See Spritedim

History

0.9.6n

New To Version

2016/01/01 22:42

Spriteslice (Statement)

Format

spriteslice sprite_number, x_position, y_position, width, height
spriteslice ( sprite_number, x_position, y_position, width, height )

Description

Copy the rectangular region of the screen with it's top left corner represented by x_position and y_position of the specified height and width and create a sprite. The sprite will be active and movable but will not be visible until the Spriteshow statement is executed. It is recommended that you execute the Clg command before drawing and slicing the sprite. All unpainted pixels will be transparent when the sprite is drawn on the screen. Transparent pixels may also be set by drawing with the color CLEAR.

History

0.9.6o

New To Version

2016/01/01 22:42

Spritev (Function)

Format

spritev ( sprite_number )

returns boolean_expression

Description

Returns true if the sprite is visible.

History

0.9.6o

New To Version

2016/01/01 22:42

Spritew

Format

spritew ( sprite_number )

returns integer_expression

Description

Returns the width, in pixels, of a loaded sprite.

History

0.9.6n

New To Version

2016/01/01 22:42

Spritex (Function)

Format

spritex ( sprite_number )

returns integer_expression

Description

Returns the x coordinate of the center of a loaded sprite.

History

0.9.6n

New To Version

2016/01/01 22:42

Spritey (Function)

Format

spritey ( sprite_number )

returns integer_expression

Description

Returns the y coordinate of the center of a loaded sprite.

History

0.9.6n

New To Version

2016/01/01 22:42

Stamp (Statement)

Format

Description

Draws a polygon. The sides of the polygon are defined by the values stored in the array, which should be stored as x,y pairs, sequentially. The length of a one dimensional array/2 or the number of rows on a two dimensional array will define the number of points.

One dimensional arrays and lists must have at least six values and an even number of values. A two dimensional array may have 3 or more rows but must have two columns.

Description

Draws a polygon with top left corner (origin) at x, y. Optionally scales size of polygon by the defined scale (1=normal size). Also optionally rotates the polygon by a specified angle around the origin (clockwise in radians). The vertices of the polygon are defined by the values in an array, which should be stored as x,y pairs, sequentially. The length of the array/2 will define the number of points. A stamped polygon can also be specified using a list of x,y pairs enclosed in curly braces {}.

Example

Both of the code blocks below will draw a pair of green triangles on the graphics window:

clg blue
rect 0,0,300,300
color green
tri = {{0, 0}, {100, 100}, {0, 100}}
# stamp the triangle at 0,0 (full size)
stamp 100, 100, tri[]
# stamp the triangle at 200,100 (half size)
stamp 200, 100, .5, tri[]

clg blue
rect 0,0,300,300
color green
# stamp the triangle at 0,0 (full size)
stamp 100, 100, {{0, 0}, {100, 100}, {0, 100}}
# stamp the triangle at 200,100 (half size)
stamp 200, 100, .5, {0, 0, 100, 100, 0, 100}

Both programs will draw:

History

0.9.4	New To Version
1.99.99.55	two dimensional list support was added
1.99.99.72	added required [] to passing variable array

2016/01/01 22:42

String (Function)

Format

string ( expression )

returns string_expression

Description

Returns the string representation of a number.

Example

number = 30+2
print string(number)

Results with

System (Statement)

Format

system expression
system ( expression )

Description

Execute a system command in a terminal window. WARNING: This can be a very dangerous statement. Only use it if you know what you are doing.

This statement may be disabled because of potential system security issues. Availability may be configured in the IDE by going to the Preferences dialog.

Example

   
system("BASIC256 -r HelloWorld.kbs")

Brings up the program without its source code visible and runs it.

History

0.9.5h

New To Version

2016/01/01 22:42

Tan (Function)

Format

tan ( numeric_expression )

returns float_expression

Description

Computes the tangent of angle in radians.

Note

The tan function does not produce an exact result.

Example

clg
color black
# draw a line across the graphic output
line 0,150,300,150
# where do we start
lastx = 0
lasty = tan(0) * 50 + 150
# now step across the line and draw
for x = 0 to 300 step 5
   angle = x / 300 * 2 * pi
   y = tan(angle) * 50 + 150
   line lastx, lasty, x, y
   lastx = x
   lasty = y
next x

Draws

Text (Statement)

Format

text x_position, y_position, string_expression
text ( x_position, y_position, string_expression )

Description

Paints a text string on the Graphics Output Window at x_position, y_position using the current color and font.

Example

color grey
rect 0,0,graphwidth,graphheight
color red
font "Times New Roman",18,50
text 10,100,"This is Times New Roman"
color darkgreen
font "Tahoma",28,100
text 10,200,"This is BOLD!"

Will draw.

History

0.9.4

New To Version

2016/01/01 22:42

Upper (Function)

Format

upper ( string_expression )

returns string_expression

Description

Returns string_expression with all alphabetic characters converted to upper case.

Example

print upper("BlUe!")

will display

BLUE!

History

0.9.5e

New To Version

2016/01/01 22:42

Volume (Statement)

Format

volume posint_expr
volume ( posint_expr )

Description

Adjust the amplititude of the notes played with the Sound command. Levels must be numeric values from 0 to 10. The default is 5.

History

0.9.5i

New To Version

2016/01/01 22:42

WAVplay (Statement)

Format

wavplay file_name
wavplay ( file_name ) wavplay

Description

Play audio file asynchronously (in the background) or restart a previously stopped or paused audio file.

Note

As of 1.1.1.3 support for several additional types of autio files have been added (including mp3).

History

0.9.4	New To Version
1.1.1.3	Rewrote to allow for more media types.

2016/01/01 22:42

WAVstop (Statement)

Format

wavstop

Description

Stop playing the current asynchronous (background) WAV audio file.

History

0.9.4

New To Version

2016/01/01 22:42

Write (Statement)

Format

write string_expression
write ( string_expression )
write open_file_number, string_expression
write ( open_file_number, string_expression )

Description

Writes string_expression to the end of an open file. If the file number is not specified file number zero (0) will be used.

History

2016/01/01 22:42

Writeline (Statement)

Format

writeline string_expression
writeline ( string_expression )
writeline open_file_number, string_expression
writeline ( open_file_number, string_expression )

Description

Writes string_expression append with a newline character to the end of an open file. If the file number is not specified file number zero (0) will be used.

History

0.9.4

New To Version

2016/01/01 22:42

Year (Function)

Format

year
year ( )

returns integer_expression

Description

Returns the current system clock's 4 digit year.

Example

print "today's date is ";
print (month + 1) + "/" + day + "/" + year

will display

today's date is 11/30/2009

History

0.9.4

New To Version

2016/01/01 22:42

BASIC-256 Syntax Reference

Program Syntax

Statements

Label

Compound Statement

Example

Numeric Constants

String Constants

Examples

Variables

Example

See Also

History

Arrays

Assigning values to an array

Passing Arrays of Data to Builtin Functions and Statements

History

Anonymous Arrays

Example

Operators

Arithmetic Operators

History

String Operators

History

Comparison Operators

Logical Operators

Not

And

Or

Xor

Variable Operators

Bitwise Operators

Order of Operations

Links to Separate Pages

Statements and Functions - Alphabetic

Abs (Function)

Format

Description

Example

See Also

Acos (Function)

Format

Description

See Also

Asc (Function)

Format

Description

See Also

Example

See Also

History

Asin (Function)

Format

Description

See Also

Atan (Function)

Format

Description

See Also

Ceil (Function)

Format

Description

See Also

Changedir (Statement)

Format

Description

See Also

History

Chr (Function)

Format

Description

See Also

Example

See Also

History

Circle (Statement)

Format

Description

Example

See Also