Blunt_Axe_Basic Project

Copyright:(c) sarbayo, 2001,02,03,04
Alpha Version 1.05

_Bxbasm_
(Blunt Axe Basic)

Bxbasic Commands

Standard Basic Commands and Functions supported in Alpha Version 1.05
=======================================================================
ASM Command
ASM mov  eax, [esi]

ASM is not a standard Basic command, but, Bxbasic passes along to the assembler any statement that follows the ASM command. Bxbasic does not syntax check the ASM text string.

=======================================================================
ABS() Function
ABS(integer)

Returns the absolute value of a number.
	integer = ABS(integer)

=======================================================================
ASC() Function
ASC(string)

Returns the ascii code of the first character in a string.
	integer = ASC(a$)
 
=======================================================================
ATN() Function
ATN(float#)

Return the arc tangent of a number.
	float# = ATN(float#)

=======================================================================
ATN2() Function
ATN2(float#,float#)

Returns the arc tangent of y/x
	float# = ATN2(y#, x#)

=======================================================================
ACOS() Function
ACOS(float#)

Returns the arc cosine of x.
	float# = ACOS(float#)

=======================================================================
ASIN() Function
ASIN(float#)

Returns the arc sine of x.
	float# = ASIN(float#)

=======================================================================
BEEP Command

Sounds the PC speaker.
	BEEP

=======================================================================
BREAK Command

Used to break out of a loop: 
	WHILE ...
		BREAK
	WEND
-or-
	LOOP ...
		BREAK
	ENDLOOP
-or-
	DO ...
		BREAK
	WHILE

=======================================================================
CLEAR Command
CLEAR var,[list,]

Sets numeric variables to zero and strings to NULL.
	CLEAR (clears all numeric and string variables)
	CLEAR a$, name$, integer%

=======================================================================
CLOSE Command
CLOSE #buffer

Closes access to a disk file. If you omit buffer, Bxbasic closes all open files.
	CLOSE
	CLOSE #1

=======================================================================
CLS Command

Clears the console screen.
	CLS

=======================================================================
CHDIR Command
CHDIR string

Changes directories to the directory on the current drive, specified by path.
	CHDIR "\mypath"
	CHDIR path$

=======================================================================
CHDRIVE Command
CHDRIVE string

Makes the disk drive specified by drivename the current drive.
	CHDRIVE "A"

=======================================================================
COLOR Command
COLOR [foreground],[background]

Selects the text display colors on the console screen. Foreground and background may be any one of 16 colors.
	COLOR Fgrnd, Bgrnd
	COLOR 11,1

Color choices are:
	No.	Color			No.	Color
	0	black			8	dark grey
	1	blue			9	light blue
	2	green			10	light green
	3	cyan			11	light cyan
	4	red			12	light red
	5	magenta		13	light magenta
	6	brown			14	yellow
	7	gray			15	white

=======================================================================
CHR$() Function
CHR$(integer)

Returns the character corresponding to the ASCII value of integer.
	string$ = CHR$(integer)

=======================================================================
COS() Function
COS(float#)

Returns the cosine of a floating point number.
	float# = COS(float#)

=======================================================================
COSH() Function
COSH(float#)

Returns the hyperbolic cosine of a floating point number.
	float# = COSH(float#)

=======================================================================
CVD() Function
CVD(8-byte string)

Converts an 8 byte string to a double precision number. Used to restore numeric data to numeric form after a disk read.
	float# = CVD(string)

=======================================================================
CVI() Function
CVI(4-byte string)

Converts a 4 byte string to an integer number. Used to restore numeric data to numeric form after a disk read.
	integer% = CVI(string)

=======================================================================
CVS() Function
CVS(8-byte string)

Converts an 8 byte string to a Single precision number. Used to restore numeric data to numeric form after a disk read.
	float! = CVS(string)

=======================================================================
CEIL() Function
CEIL(float#)

Returns the smallest double precision whole number that is not less than x.
	float# = CEIL(float#)

=======================================================================
CLOCK() Function
CLOCK()

Returns the elapsed time in clock ticks. May be used as a random seed.
	integer% = CLOCK()
	   long@ = CLOCK()

=======================================================================
DIM Command
DIM array$(num,num,...) (*strings)

Declares and dimensions a multi-dimensional string array. In this release, DIM supports string arrays only.
In this example:
	DIM string$(3,3,10)

the array is an array of 90 string pointers: 3 x 3 x 10 = 90
That is, an array of 90 address pointers and not 90 characters. The above could be best seen as 3 groups (or tablets), each containing 3 pages, with each page containing 10 rows for data (or strings). Each array string (or row) is dynamically created and populated when it is assigned to.
In this example:
	DIM string$(10)

an array of 10 string address pointers is created. Each of the 10 strings can be of any desired (within reason) length.
The following example dimensions an array and then populates three array pointers:
	DIM string$(3,3,10)
	string$(1,1,1) = "hello world!"
	string$(2,2,2) = "This is a test "
	string$(2,2,3) = "of the emergency broadcast system"

=======================================================================
DO/WHILE Command (loop)
DO/WHILE logical expression

The DO/WHILE is a loop construct and can be used anytime the user desires that the loop be executed at least once prior to being terminated.
	DO
		x = abc + xyz
	WHILE x < 100

=======================================================================
DATE$ Function

Returns the current date.
	string$ = DATE$

=======================================================================
END Command

Terminates program execution. Every program must have at lease one END statement. The END command need not be the last line in the program. ie: it can be anywhere within the program.
	IF x = 0 THEN
		GOTO TheEnd
	ENDIF
	...
TheEnd:
	END

=======================================================================
EOF() Function
EOF buffer

Returns a Boolean TRUE or FALSE based on whether or not the end-of-file has been reached. Is used in an "IF/ELSE" construct.
	IF EOF(1) THEN
		GOTO CloseFile
	ENDIF

=======================================================================
FIELD Function
FIELD #buffer, length AS name

Divides a random access file buffer into fields so that data can be written to disk or read from disk into memory. Each field is identified by a string variable name and is of a specified length. The length must be an integer constant.
	FIELD #1, 10 AS firstname$, 10 AS lastname$, 1 AS initial$

=======================================================================
FOR/NEXT Command
FOR variable = initial value TO final value STEP increment
NEXT variable

Creates a program loop that will be executed for a predetermined number of cycles. The value of 'variable' is set to that of 'initial value'. The value of 'variable' is then incremented after each cycle by the value of 'increment'.
In this example, the loop will execute for 50 cycles:

		FOR x = 1 TO 100 STEP 2
			' do stuff
		NEXT x

=======================================================================
FILES Command
FILES string

Displays a list of disk files and directories. 'String' specifies a certain criteria to be met. The wild cards: * and ? may be used.
	FILES "*.bas"
	FILES "\windows\*.exe"

=======================================================================
FLOOR() Function
FLOOR(float#)

Returns the largest whole number that is less than or equal to x.
	float# = FLOOR(float#)

=======================================================================
GET Command
GET #buffer, record

Reads a record from a random access disk file and places it in the specified buffer. Record is an integer value. The default record if none is specified is the next logical record.
	GET #1,ndx

=======================================================================
GOSUB/RETURN Command
GOSUB label
RETURN

Branches to the subroutine beginning at "label". Every subroutine must end with a RETURN command.
	GOSUB MyRoutine
	...
	...
MyRoutine:
	'do stuff
	RETURN

=======================================================================
GOTO Command
GOTO label

Causes an absolute jump to the program line that follows "label". There is no returning from a GOTO.
	GOTO MyLabel
	...
	...
MyLabel:
	'do stuff

=======================================================================
HYPOT() Function
HYPOT(float#, float#)

Returns the length of the hypotenuse of a right triangle with sides of length x and y.
	float# = HYPOT(x#, y#)

=======================================================================
IF/ELSEIF/ELSE/ENDIF Command
IF expression THEN
	statement
ELSEIF expression THEN
	statement
ELSE 
	default
ENDIF

IF/ELSE is a conditional expression construct, where any number of variables and conditions can be tested for logical and boolean values. A simple expression might be:
	IF x = 0 THEN
		PRINT "x = 0"
	ENDIF

A more complex expression might look like:
	IF x >= 0 AND x <= 10 THEN
            PRINT "x=0 to 10",x
    	ELSEIF x >= 11 AND x <= 20 THEN
            PRINT "x=11 to 20",x
    	ELSEIF x >= 21 AND x <= 30 THEN
            PRINT "x=21 to 30",x
    	ELSE 
		PRINT "x != 0 to 30",x
    	ENDIF

After the initial IF there may be any number of ELSEIF's, but, there may be only one (1) ELSE and there must always be one (1) (and only one) ENDIF. Additionally, each IF and ELSEIF line must be terminated by a THEN. Expressions may be compounded by the use of AND and OR:
	IF a$ = b$ AND b$ <> c$ OR c$ = d$ THEN

Logical operators are:
	=	equal to
	<	less than
	<=	less than or equal to
	>	greater than
	>=	greater than or equal to
	<>	not equal to

=======================================================================
INPUT Command
INPUT variable[,var.]

Accepts keyboard input and puts it into any number of and type of variable. If INPUT is followed by a semi-colon, as shown here:
	INPUT ; a$
the return key will not be echoed to the screen when it is pressed at the of the input'd data. INPUT may also be followed by a 'prompt' string, which will be displayed in front of the input area:
	INPUT ; "Enter your firstname:"; fname$

Multiple prompts and variables may be entered on the same INPUT line:
	INPUT ; "Name"; name$, "Age:"; age%, "ID:"; IDno%

=======================================================================
INPUT# Command
INPUT #buffer, variable[,var.]

Accepts data from a sequential access text file and stores the data in variable(s). Buffer is the file buffer number.
	INPUT #1, string$, integer%, float!, double#

=======================================================================
INKEY$ Function

Returns a single character string without the need to press the enter-key. If no key is pressed, INKEY$ does not wait. The program continues. INKEY$ is best used in a loop:
		PRINT "Press any key to continue_";
	Loop1:
		a$ = INKEY$
		IF a$ = "" THEN
			GOTO Loop1
		ENDIF
		...

=======================================================================
INPUT$() Function
INPUT$(integer)

Inputs a specified number of characters from the keyboard into a string variable.
	a$ = INPUT$(25)

=======================================================================
INT() Function
INT(number)

Converts number into the largest integer value that is less then or equal to number.
	integer% = INT(float#)

=======================================================================
KILL Command
KILL filename

Deletes a disk file.
	KILL "filename.txt"
	KILL path$

=======================================================================
LET Command
LET variable = expression

Assigns the value of expression to variable. The LET keyword is optional. By default, unless indicated otherwise, program lines are assumed to be LET statements. Therefore, the use of LET is optional. Assignments may be of any data type. For this reason, variable names can not be the same as keyword names.
	LET integer% = value
	    integer% = value

Bxbasic is a strongly typed language. With only one exception, all variable names must include a data type specifier, appended to the name. Ordinary integer variables may optionally use the integer data type symbol: %. Any variable name encountered without a data type specifier is assumed to be a simple integer.
	variable  = integerValue
	variable% = integerValue

The data type specifiers are:
	%	integer
	!	float
	#	double float
	@	long integer
	$	string

String assignments can be string to string assignments, string plus string and string to array, array to string assignments.
	A$ = "quoted text string"
	B$ = A$
	C$ = A$ + B$
	array$(1,1,1) = A$
	data$ = array$(1,1,2)

Numeric value assignments may be constants:
	integer = 123456
	double# = 123.456789

or, variable data:
	integer = varname

or, complex algebraic expressions:
	double# = (abc * (xyz + width / 3))

=======================================================================
LINE INPUT Command
LINE INPUT string

Inputs an entire line of text into a single string variable, up to 255 characters. LINE INPUT may also be followed by a 'prompt' string, which will be displayed in front of the input area:
	LINE INPUT ; "Enter your firstname:"; fname$

Input is terminated by pressing the enter key.

=======================================================================
LINE INPUT# Command
LINE INPUT #buffer, variable

Inputs an entire line of text from a file, into a single string variable, up to 255 characters. 
	LINE INPUT #1, A$

Input ends when either 255 characters is read in or a newline character is encountered.

=======================================================================
LOCATE Command
LOCATE row, column

Positions the cursor on the console screen at the coordinates specified by row and column. The upper left-hand corner is position: 0,0.
	LOCATE 5, 10
	LOCATE x, y

=======================================================================
LSET Command
LSET field name = data

Moves data to the random access buffer and places it in the field name in preparationn for a PUT command. Field name is a string variable defined in a FIELD statement. A file buffer must be FIELD'd before using LSET. 
	LSET A$ = "text string"
	LSET B$ = string$
	LSET C$ = array$(a,b,c)

LSET left-adjusted the data to the left side of the field. IF the data that is being LSET is smaller than the data buffer field, then the empty space in the buffer field will be padded with blank spaces. If the data is larger than the buffer field, then the extra characters will be truncated (removed).

=======================================================================
LOOP/ENDLOOP Command
LOOP
ENDLOOP

LOOP/ENDLOOP is a continuous, unconditional loop that is only terminated when the program encounters a BREAK command.
	LOOP
		'...do stuff
		IF expression
			BREAK		' exit out of loop
		ENDIF
		'...do stuff
	ENDLOOP			' jump to the top of loop, again

Every statement within the LOOP and ENDLOOP keyword is repeated. 

=======================================================================
LPRINT Command
LPRINT data

Prints data to the printer connected to LPT1 printer port.
	LPRINT "hello world!", abc$

A single LPRINT that does not print any data will send a newline to the printer.
	LPRINT

A comma after a variable or string will send a TAB character to the printer.
	LPRINT "hello", "world!"

A semi-colon between or after variables or data will keep the printhead at it's current position.
	LPRINT "hello"; world$; string$;
	LPRINT test$

In the above statements, after printing the variable named "string$", the printer will resume printing at that point and print "test$" with the next LPRINT statement.

=======================================================================
LEFT$() Function
LEFT$(string,number)

A string slicing function.
Returns the specified number of characters from the left portion of string. Number must be in the range of: 1 to 255.
	string$ = "hello world!"
	A$ = LEFT$(string$, 5)

=======================================================================
LEN() Function
LEN(string$)

Returns the number of characters in an ascii zero-terminated string.
	integer = LEN(string$)

=======================================================================
LOG() Function
LOG(float#)

Returns the natural logarithm of number. Number must be greater than zero.
	float# = LOG(float#)

=======================================================================
LOG10() Function
LOG10(float#)

Calculates the Base 10 logarithm.
	float# = LOG10(float#)

=======================================================================
LOC Function
LOC(buffer)

Returns the current record position within a random access file. Buffer is the file buffer number assigned to the file when it was opened.
	integer% = LOC(1)
	Integer@ = LOC(1)

=======================================================================
LOF Function
LOF(buffer)

Returns the length of the previously opened file in bytes.
	integer% = LOF(1)
	Integer@ = LOF(1)

=======================================================================
MKDIR Command
MKDIR string

Creates the directory or subdirectory specified by string.
	MKDIR "\Temp"
	MKDIR path$

=======================================================================
MID$() Function
MID$(string,start,length)

A string slicing function.
Returns the specified number of characters from any portion of a character string. Start is the starting point, counting from the left side. Length is the number of characters to copy. Both number must be in the range of: 1 to 255 and less than the total length of string.
	string$ = "hello world!"
	A$ = MID$(string$, 7, 5)

=======================================================================
MKD$() Function
MKD$(double#)

Used in combination with the LSET command, to copy a double precision floating point value into a random access string buffer. The value is stored in it's binary form as an 8-byte string. This is the inverse of the CVD function.
	LSET A$ = MKD$(double#)

=======================================================================
MKS$() Function
MKS$(float!)

Used in combination with the LSET command, to copy a single precision floating point value into a random access string buffer. The value is stored in it's binary form as an 8-byte string. This is the inverse of the CVS function.
	LSET A$ = MKS$(float!)

=======================================================================
MKI$() Function
MKI$(integer%)
MKI$(Integer@)

Used in combination with the LSET command, to copy an integer value into a random access string buffer. The value is stored in it's binary form as a 4-byte string for a regular integer and an 8-byte string for a long integer. This is the inverse of the CVI function.
	LSET A$ = MKI$(integer%)
	LSET A$ = MKI$(integer@)

=======================================================================
NAME/RENAME Command
  NAME string AS string
RENAME string AS string

Renames an old file name AS new file name. Both NAME and RENAME may be used interchangably. Dirctories cannot be renamed using NAME or RENAME.
	RENAME "thisfile.txt" AS "MyFile.txt"
	NAME oldname$ AS newname$

=======================================================================
OPEN Command
OPEN mode, #buffer, path			(sequential access file)
OPEN mode, #buffer, path, record size	(random access)

Creates an input/output path for a disk file or device.
Mode is: 	"O"	output	sequential access	(text)
		"I"	input		sequential access	(text)
		"A"	append	sequential access	(text)
		"R"	random	random access 	(binary)

Buffer is: the I/O buffer number and file identifier (handle) to be used for accessing this file. Buffer numbers may be in the range of 1 to 99. Buffer numbers need not be used in any particular order. On startup, Bxbasic creates 99 I/O buffer pointers. The '#' symbol IS required.

Path is: the logical path or file name to the device or disk file.

Record size is: (random access only) the number of bytes in the I/O buffer to write to, or read from, the disk file. Record size should always be specified. If record size is not specified, the default record size is set at 256 bytes.
Sequential Access:
	OPEN "O", #1, "My.txt"

Creates a new file for output. If My.txt already exists, it will be deleted and overwritten.

	OPEN "I", #99, filename$

Opens an existing file, for input.

	OPEN "A", #3, "existing.fil"

Creates a new file or opens existing file for output. If file exists, new data written to the file will be appended to the end of the file, leaving pre-existing information intact.

	OPEN "O", #1, "LPT1"

Opens an Output channel to the printer port: LPT1:

Random Access:
	OPEN "R", #7, "MyData.fil", 30

Opens and existing or creates a new file, as the case may be, for both read and write access. Each read or write action will I/O 30 bytes.
See: FIELD, LSET, PUT, GET.

=======================================================================
PRINT Command
PRINT data,[data...]

Prints numeric or string data to the console screen. A single PRINT command such as:	PRINT
will print a newline on the screen. 
A delimiter or separator must be used between data items. Delimiters may either be a comma ','or a semi-colon ';'.
Using a comma after a data item will send a TAB character to the screen:		PRINT "hello",

Using a semi-colon after or between items will cause the next item to be printed beside the prior:
		PRINT "hello"; "world!"

Special ascii characters and non-alpha-numeric characters may be printed by using the CHR$() function:
	PRINT CHR$(34); "hello "; world$; CHR$(34)

the resulting display will read: "hello world"
                     ascii 34----^           ^----ascii 34

=======================================================================
PRINT# Command
PRINT #buffer, data

Write unformatted text to a sequential access file. It will appear on disk much as it looks on the screen.
	PRINT #1, FName$, LName$, Age%

=======================================================================
PUT Command
PUT #buffer, record

Writes a record to a random access disk file from the specified buffer. Record is an integer value. The default record if none is specified is the next logical record.
	PUT #1,ndx

=======================================================================
REM/' Command
REM
'

A line comment. An apostrophy(') my be used instead of the keyword REM.
	REM	this is a comment and is ignored by the compiler
	'	this is a comment and is ignored by the compiler

=======================================================================
RSET Command
RSET field name = data

Moves data to the random access buffer and places it in the field name in preparationn for a PUT command. Field name is a string variable defined in a FIELD statement. A file buffer must be FIELD'd before using RSET.
	RSET A$ = "text string"
	RSET B$ = string$
	RSET C$ = array$(a,b,c)

RSET right-adjusts the data to the right side of the field. IF the data that is being RSET is smaller than the data buffer field, then the empty space in the buffer field will be padded with blank spaces. If the data is larger than the buffer field, then the extra characters will be truncated (removed).

=======================================================================
RANDOM Command
RANDOM seed

Reseeds the random number generator. Should always be used before using the RAND function. Seed may be any type of number, integer or floating point.
	seed% = CLOCK()
	RANDOM seed%
	RANDOM 123.4567

=======================================================================
READ# Command
READ #buffer, variable[,var.]

Same as INPUT#.
Accepts data from a sequential access text file and stores the data in variable(s). Buffer is the file buffer number.
	READ #1, string$, integer%, float!, double#

=======================================================================
RMDIR Command
RMDIR string

Removes (deletes) the directory or subdirectory specified by string.
	RMDIR "\Temp"
	RMDIR path$

=======================================================================
RIGHT$() Function
RIGHT$(string, number)

A string slicing function.
Returns the specified number of characters from the right portion of a character string. Beginning at the right side, number is the number of characters to copy. Number must be in the range of: 1 to 255 and less than the total length of string.
	string$ = "hello world!"
	A$ = RIGHT$(string$, 6)

=======================================================================
RAND() Function

Returns a random number, once the random number generator has been seeded.
	seed@ = CLOCK()
	RANDOM seed@
	randomnumber@ = RAND()

=======================================================================
SHELL Command
SHELL string

Console shell (DOS) command. Allows executing any DOS command contained in string.
	SHELL "dir"
	SHELL "type text.txt"
	SHELL cmnd$	

=======================================================================
SIN() Function
SIN(float#)

Returns the sine of a number. Number must be in radians.
	float# = SIN(float#)

=======================================================================
SPACE$() Function
SPACE$(number)

Returns a string containing number of blank spaces. Number must be in the range of 1 to 255.
	A$ = SPACE$(20)

=======================================================================
SQRT() Function
SQRT(float#)

Returns the square root of a number. Number must be greater than zero.
	float# = SQRT(float#)

=======================================================================
STR$() Function
STR$(number)

Converts a numeric value into an ascii character string. Number may be of any numeric data type.
	string$ = STR$(99)
	string$ = STR$(value!)

=======================================================================
STRING$() Function
STRING$(number, character)

Returns a string containing the specified number of character. Number must be in the range of 1 to 255. Character may be any acsii code.
	A$ = STRING$(10, "A")
	A$ = STRING$(10, 65)
	A$ = STRING$(10, char%)

=======================================================================
SINH() Function
SINH(float#)

Returns the hyperbolic sine of number. Number must be in radians.
	float# = SINH(float#)

=======================================================================
TAN() Function
TAN(float#)

Returns the tangent of number. Number must be in radians.
	float# = TAN(float#)

=======================================================================
TANH() Function
TANH(float#)

Returns the hyperbolic tangent of number. Number must be in radians.
	float# = TANH(float#)

=======================================================================
TIME$ Function

Returns a character string containing the current time.
	string$ = TIME$

=======================================================================
VAL() Function
VAL(string)

Returns the numeric value of string.
	 value = VAL(number$)
	float# = VAL(number$)

=======================================================================
WRITE# Command
WRITE #buffer

Writes data to a sequential access file. Buffer is the file buffer number.
	WRITE #1, string$, integer%, float!, double#

=======================================================================
WHILE/WEND Command
WHILE logical expression
WEND

The WHILE/WEND is a loop construct with a logical expression at the start of the loop. The expression is examined at the start of each loop cycle.
	WHILE x < 100
		x = abc + xyz
	WEND

=======================================================================