User Manual 

Statements and Functions


ABS

Function

Syntax:

ABS(nexp)

Example:

ABS(-4)

Returns the absolute value (distance from zero) of the argument. The example returns 4.



ASC

Function

Syntax:

ASC($exp)

Example:

ASC("Hello")

Returns the ASCII code for the first character in the argument. The example returns 72, which is the ASCII code for H.



BIN$

Function

Syntax:

BIN$(nexp)

Example:

BIN$(200)

Returns a string which is the binary (base 2) representation of the argument. The example returns 11001000, which is the binary equivalent of 200.



CHAIN

Runtime Statement

Syntax:

CHAIN "progname"

Example:

CHAIN "results"

Reads the specified program into memory from storage memory. Any program existing in memory before the CHAIN command will be erased (lost). However, variables will NOT be cleared and the new program will be run automatically. This enables the concept of overlapping (chaining) multiple program segments together with the same underlying data. Using this technique, programs can be made to be more modular, and the entire 'chained' application can be as large as storage space allows. The example chains to the program named "results" while maintaining the existing variable values.



CHR$

Function

Syntax:

CHR$(nexp)

Example:

CHR$(65)

Returns the character matching the specified ASCII code in the argument. The example returns the letter A.



CLEAR

Function

Syntax:

CLEAR [nexp]

Example:

CLEAR 400

Clears all numeric and string variables. The optional argument specifies the amount of memory to allocate for strings (including string arrays). If omitted, the default value of 256 bytes will be allocated. The example clears all variables and allocates 400 bytes for strings.



CONT

Direct Statement

Syntax:

CONT

Example:

CONT

Resumes (continues) program execution after a STOP command. Execution will continue from the point where the most recent STOP was encountered. The example resumes program execution at the statement following the STOP that halted program execution.



DATA

Runtime Statement

Syntax:

DATA [ nexp|$exp [, nexp|$exp]... ]

Example:

100 DATA "Horse", -7, dog

Declares a list of literal values (numeric and/or string) as an information base. These values can later be loaded into variables using the READ statement. The enclosing quotes for string values are optional. The example creates a BASIC line that stores the literal values 'Horse', -7, and 'dog' for later retrieval.



DATE$

Function

Syntax:

DATE$

Example:

DATE$

Returns the current date as a string in the form mm-dd-yyyy. The example returns the current date, for example 03-31-2003.



DEC

Statement

Syntax:

DEC nvar

Example:

DEC A

Decrements the specified numeric variable by 1. The example decrements the numeric variable A by 1. This statement is functionally equivalent to A=A-1.



DEL

Direct Statement

Syntax:

DEL [linenum] [-] [linenum]

Example1:

DEL 100-200

Example2:

DEL 200-

Removes (deletes) the specified range of lines from the program in memory. If no line number range is specified, the entire program is deleted. The first example deletes lines 100 to 200 (inclusive). The second example deletes line 200 and all lines following line 200.



DIM

Statement

Syntax:

DIM var(subscript [, subscript])

Example1:

DIM CAVE(5,3)

Example2:

DIM NAME$(10)

Dimensions and reserves memory for an array of variables. Arrays can have one or two dimensions. The first example creates a two-dimensional numeric array with 15 elements, indexed 0,0 - 4,2. The second example creates a one-dimensional string array with 10 elements, indexed 0 - 9.



END

Runtime Statement

Syntax:

END

Example:

END

Unconditionally stops a running program and returns to the direct mode.



ERROR

Runtime Statement

Syntax:

ERROR nexp

Example:

ERROR 6

Triggers the specified error number. The example triggers an "Overflow" error.



FILES

Direct Statement

Syntax:

FILES

Example:

FILES

Lists all picoBASIC programs currently in storage memory.



FOR

Statement

Syntax:

FOR var = nexpr TO nexpr [ STEP nexpr ]

Example:

FOR J = 1 TO 10 STEP 2

Begins a counted loop, the end of which is defined by a corresponding NEXT statement. Specifies the index variable, beginning and ending values and optionally, the increment (step) value for each iteration. The example begins a loop in which J will begin at 1, and increment by 2's ( 3, 5, 7,...) until it reaches 9, which is the last value less than or equal to the end value of 10.



FRE

Function

Syntax:

FRE(nexp)

Example1:

FRE(0)

Example2:

FRE("")

Returns the current amount of unused memory for the specified type of variable (numeric or string). Only the supplied argument's type is significant, not its value. The first example returns the amount of numeric space available. The second example returns the amount of string space available. Note that, since they share the same block of memory, the amount of program space available is the same as the amout of numeric space available.



GOSUB

Statement

Syntax:

GOSUB linenum

Example:

GOSUB 100

Branches to a subroutine beginning at the specified line number. The example will execute a subroutine starting at line 100.



GOTO

Statement

Syntax:

GOTO linenum

Example:

GOTO 100

Branches to the specified line number. The example will jump to line 100.



HEX$

Function

Syntax:

HEX$(nexp)

Example:

HEX$(200)

Returns a string which is the hexadecimal (base 16) representation of the argument. The example returns C8, which is the hexadecimal equivalent of 200.



HIMEM

Function

Syntax:

HIMEM

Example:

HIMEM + 1

Returns the highest address of memory available to BASIC. The example returns the first memory address beyond BASIC.



IF...THEN...ELSE

Statement

Syntax:

IF expr THEN statement | linenum [ ELSE statement | linenum ]

Example1:

IF MONTH > 3 THEN PRINT "SPRING"

Example2:

IF PLAYERS = 4 THEN 600 ELSE GOSUB 240

Conditionally executes or skips statements, based on the outcome of a test expression. The test expression must evaluate to a simple true or false result, such as A=4 or LEN(B$)<3. If the test expression is true, then the statement or line number after THEN is executed. If the test expression is false, then the statement or line number after ELSE is executed. The first example compares the variable MONTH with the number 3. If it is greater than 3, the program prints "SPRING". The second example compares the variable PLAYERS with the number 4. If it is equal to 4, then the program will jump to line 600. If PLAYERS is not equal to 4, then the program will jump to a subroutine beginning at line 240.



INC

Statement

Syntax:

INC nvar

Example:

INC A

Increments the specified numeric variable by 1. The example increments the numeric variable A by 1. This statement is functionally equivalent to A=A+1.



INPUT

Statement

Syntax:

INPUT ["prompt";] var

Example:

INPUT "Last Name"; LAST$

Pauses program execution to take string or numeric input from the user. Only one value may be input at a time. A question mark prompt will be displayed, preceded by an optional prompt string to give guidance to the user. For string input, leading spaces, trailing spaces, and enclosing quotes will be ignored. If the user inputs a string when prompted for a numeric value, the string will automatically be converted to a number (0 unless the first character is a digit). The example prompts the user for a string, then stores the user's response in the string variable LAST$.



INSTR

Function

Syntax:

INSTR(nexp, $exp, $exp)

Example:

INSTR( 1, "silicon oxide", "oxide" )

Returns the position of the first match of the second specified (target) string within the first specified (search) string, or 0 if no match is found. The position within the search string to begin looking for a match is specified by the numeric expression (start). The example returns the first position of "oxide" within "silicon oxide", which is 9.



KILL

Direct Statement

Syntax:

KILL "progname"

Example:

KILL "hearts"

Deletes the specified program permanently from storage memory. The example deletes the program named "hearts" from storage memory.



LCASE$

Function

Syntax:

LCASE$($exp)

Example:

LCASE$("HELLO")

Returns the lower case representation of the specified string. This is often useful during string comparisons, which are case-sensitive. The example returns the string "hello".



LEFT$

Function

Syntax:

LEFT$($exp, nexp)

Example:

LEFT$("PICODOC", 4)

Returns the specified number of characters from the beginning of the specified string. If nexp is 0, an empty string is returned. If nexp is greater than the length of $exp, then $exp is returned. The example returns the string "PICO".



LEN

Function

Syntax:

LEN($exp)

Example:

LEN(A$)

Returns the length (number of characters) of the specified string. The example returns the length of string variable A$. If A$="Hello", then 5 will be returned.



LET

Statement

Syntax:

[LET] var = exp

Example1:

LET A = 17

Example2:

A$ = "EAGLE"

Sets the value of the specified variable to the expression following the = operator. The data type of the variable must match the data type of the result of the expression. The keyword LET is optional. The first example sets variable A to 17. The second example sets variable A$ to "EAGLE".



LINE INPUT

Statement

Syntax:

LINE INPUT ["prompt";] var

Example:

LINE INPUT "Description"; D$

Pauses program execution to take string input from the user. Only one value may be input at a time. No question mark prompt will be displayed, and an optional prompt string provides guidance to the user. Leading spaces, trailing spaces, and enclosing quotes will be included. The example prompts the user for a string, then stores the user's response in the string variable D$.



LIST

Direct Statement

Syntax:

LIST [linenum] [-] [linenum]

Example1:

LIST

Example2:

LIST 100-180

Example3:

LIST 100-

Displays part or all of the current program. A start and/or end line number can be specified to display part of the program. Program listings are paginated. The page down button will show the next page of the listing. Tapping the screen once will show the next line of the listing. The first example lists the entire program. The second example lists only those lines between 100 and 180 inclusive. The third example lists all lines between 100 and the end of the program.



LOAD

Direct Statement

Syntax:

LOAD "progname" [ ,R ]

Example:

LOAD "hearts"

Reads the specified program into memory from storage memory. Note that program names are case sensitive.The program can be run automatically after loading by appending the ,R option. Any program existing in memory before the LOAD command will be erased (lost), so be sure to SAVE the current program if any changes have been made since it was last LOADed. The example loads the program named "hearts" into memory but does not run it.



LOCATE

Statement

Syntax:

LOCATE row, column

Example:

LOCATE 5,20

Moves the current cursor position to the specified row and column in characters. Note that columns may not exactly match in successive rows due to variable character width. The example sets the current cursor position to row 5, column 20.



LTRIM$

Function

Syntax:

LTRIM$($exp)

Example:

LTRIM$(A$)

Returns the specified string with all leading spaces removed. The example returns the string contained in A$, with all leading spaces removed.



MAX

Function

Syntax:

MAX(nexp, nexp [, nexp... ])

Example1:

MAX(1,2)

Example2:

MAX(0,A+1,B)

Returns the maximum of two or more values in a list. The first example returns 2. The second example returns 0, A+1, or B, whichever is the maximum value.



MERGE

Statement

Syntax:

MERGE "progname"

Example:

MERGE "chessboard"

Reads the specified program into memory from storage memory. Any program existing in memory before the MERGE command will be combined with the new program being read in. This enables the concept of library code, which can be re-used in multiple applications. New lines read in will replace those in the currently existing program if they share the same line number. The example merges (adds) the "chessboard" program to the program currently in memory.



MID$

Function

Syntax:

MID$($exp, nexpr [, nexpr]))

Example1:

MID$("The quick brown fox", 5, 5)

Example2:

MID$("The quick brown fox", 5)

Returns the specified number of characters beginning at the specified location in the specified string. If the third parameter (length) is omitted, the remainder of the string beginning at the value of the second parameter (start) is returned. The first example returns the string "quick". The second example returns the string "quick brown fox".



MID$

Statement

Syntax:

MID$($exp, nexpr [, nexpr])) = $exp

Example1:

MID$("The quick brown fox", 5, 5) = "rapid"

Example2:

MID$("The quick brown fox", 11) = "red dog"

Replaces the specified number of characters beginning at the specified location in the specified string. If the third parameter (length) is omitted, the remainder of the string beginning at the value of the second parameter (start) is replaced. Replacement occurs only for the length of the string expression on the right side. The first example replaces the word 'quick' with the word 'rapid' in the specified string. The second example results in the string "The quick red dogox".



MIN

Function

Syntax:

MIN(nexp, nexp [, nexp... ])

Example1:

MIN(1,2)

Example2:

MIN(0,A+1,B)

Returns the maximum of two or more values in a list. The first example returns 1. The second example returns 0, A+1, or B, whichever is the minimum value.



NEW

Direct Statement

Syntax:

NEW

Example:

NEW

Erases the current program from memory, resets all variables to 0 (numeric) or "" (string), and resets internal program status to its initial state. NEW does not change the string space allocation, which remains either at the value last set by CLEAR or the default value of 256 bytes. Be sure to SAVE the current program before executing a NEW command if any changes have been made since it was last LOADed.



NEXT

Statement

Syntax:

NEXT [ var [ ,var]... ]

Example1:

NEXT

Example2:

NEXT ITEM

Example3:

NEXT J, I

Defines the end of a counted loop, the beginning of which is defined by a corresponding FOR statement. The index variable specified in that FOR statement will be adjusted by the STEP value, if any, or by +1 by default. If another iteration of the loop is required, control is transferred to the statement following the corresponding FOR statement. If the loop terminates, then control is transferred to the statement following this NEXT statement. The first example ends the most recently started loop. The second example ends the loop whose index variable is ITEM. The third example ends the loop whose index variable is J, then ends the loop whose index variable is I.



OCT$

Function

Syntax:

OCT$(nexp)

Example:

OCT$(200)

Returns a string which is the octal (base 8) representation of the argument. The example returns 310, which is the octal equivalent of 200.



PEEK

Function

Syntax:

PEEK(nexpr)

Example:

PEEK(35)

Returns the contents of the specified memory location. The example returns the contents of memory location 35.



POS

Function

Syntax:

POS(nexp)

Example:

POS(0)

Returns the current cursor position in pixels. Only the supplied argument's type is significant, not its value. The example returns the current cursor position (where the next PRINT output will start) in pixels (0-159).



PRINT or ?

Statement

Syntax:

PRINT [ expr [,|; expr]...]

Example:

PRINT A$, LEN(A$), "TOTAL = "; X

Writes a line of output to the screen. Any valid expression can be included in the specified list of output values. A comma will separate items on the line, a semicolon will place them together without spaces. PRINT with no parameters following it will print a blank line. A ? (question mark) serves as a short form of PRINT. The example prints the value of string variable A$, some space, the length of A$, then the text string "TOTAL = " immediately followed by the value of the integer variable X.



RAND

Statement

Syntax:

RAND

Example:

RAND

Re-seeds the random number generator. This statement begins a new sequence of random numbers generated by the RND function. The example begins a new random number sequence.



READ

Runtime Statement

Syntax:

READ var [,var]...

Example:

100 DATA "Horse", -7, dog

    

110 READ A$, N, B$

Loads values in sequence from DATA statements, and stores these values into the specified variables in sequence. The data type of the value must match the data type of the variable. The example loads the values 'Horse' into A$, -7 into N, and 'dog' into B$.



REM or '

Statement

Syntax:

REM [ text ]

Example:

REM *** Summation Subroutine ***

Specifies that the remainder of the line is a remark (comment) only. This allows programs to be documented directly in the code. It's always a good idea to comment sections of code such as initialization, subroutines, and complex operations. A apostrophe (') serves as a short form of REM. The example denotes the start of a subroutine.



RENAME

Statement

Syntax:

RENAME "old progname", "new progname"

Example:

RENAME "hearts", "bridge"

Renames the program file in storage memory. The example renames the program named "hearts" to "bridge".



RESTORE

Statement

Syntax:

RESTORE

Example:

RESTORE

Resets the DATA pointer to the first value on the first DATA statement in the program. This allows a data set to be read more than once. The example resets the DATA pointer.



RETURN

Runtime Statement

Syntax:

RETURN

Example:

RETURN

Marks the end of a subroutine. When executed, the program will continue execution at the statement following the GOSUB that called this subroutine.



RIGHT$

Function

Syntax:

RIGHT$($exp, nexp)

Example:

RIGHT$("PICODOC", 3)

Returns the specified number of characters from the end of the specified string. If nexp is 0, an empty string is returned. If nexp is greater than the length of $exp, then $exp is returned. The example returns the string "DOC".



RND

Function

Syntax:

RND(nexp)

Example1:

RND(1000)

Example2:

RND(6)+1

Generates a pseudo-random integer between 0 and the specified value - 1. The first example provides a number in the range 0-999. The second example provides a number in the range 1-6, simulating the roll of a die.



RTRIM$

Function

Syntax:

RTRIM$($exp)

Example:

RTRIM$(A$)

Returns the specified string with all trailing spaces removed. The example returns the string contained in A$, with all trailing spaces removed.



RUN

Direct Statement

Syntax:

RUN

Example:

RUN

Clears all variables, then executes a program. The example executes the program currently in memory, beginning with the first statement in the program.



SAVE

Direct Statement

Syntax:

SAVE "progname" [ ,A ]

Example:

SAVE "hearts", A

Writes the specified program to storage memory. Any program existing in storage with the same name will be overwritten (lost). A program can be saved in ASCII (non-tokenized) form by appending the ,A option. The example saves the program named "hearts" to storage memory in ASCII form.



SGN

Function

Syntax:

SGN(nexp)

Example:

SGN(-234)

Returns a value of -1, 0, or +1, depending on the sign of the specified argument (negative, zero, or positive). The example returns -1.



SPACE$

Function

Syntax:

SPACE$(nexp)

Example:

SPACE$(5)

Returns a string of spaces of the specified length. The example returns "     ".



STOP

Runtime Statement

Syntax:

STOP

Example:

STOP

Temporarily halts program execution. Provided that the program state is not altered while in direct mode, execution can be resumed with a CONT statement. STOP is useful for debugging since it allows variables to be examined while within a running program. The example halts program execution at the current line.



STR$

Function

Syntax:

STR$(nexp)

Example:

STR$(378)

Returns a string representation of the specified numeric value. The example returns the string "378".



STRING$

Function

Syntax:

STRING$(nexp, string | char )

Example1:

STRING$(4, "abc")

Example2:

STRING$(3, 67)

Returns a string of the specified length and character. If the second argument (char) is a number, the duplicated character will be the ASCII character for that code. If the second argument is a string, only the first character of the supplied string is duplicated. The first example returns the string "aaaa". The second examle returns the string "CCC".



TAB

Function

Syntax:

TAB(nexp)

Example:

TAB(20)

Moves the horizontal cursor to the specified pixel position. This is useful when formatting output into columns. The example moves the horizontal cursor position to 20 pixels from the left edge of the screen, where subsequent printing will continue.



TIME$

Function

Syntax:

TIME$

Example:

TIME$

Returns the current time as a string in the form hh-mm-ss. The example returns the current date, for example 17-11-30 for 5:11:30pm.



TRACE

Statement

Syntax:

TRACE ON | OFF

Example:

TRACE ON

Sets program trace on or off. When trace is on, the line number of each statement is displayed as it is executed to aid in debugging. The example sets program trace on.



TRIM$

Function

Syntax:

TRIM$($exp)

Example:

TRIM$(A$)

Returns the specified string with all leading and trailing spaces removed. The example returns the string contained in A$, with all leading and trailing spaces removed.



UCASE$

Function

Syntax:

UCASE$($exp)

Example:

UCASE$("hello")

Returns the upper case representation of the specified string. This is often useful during string comparisons, which are case-sensitive. The example returns the string "HELLO".



VAL

Function

Syntax:

VAL($exp)

Example:

VAL("123ABC")

Returns the numeric value represented by the specified string. The conversion from string to number stops at the first non-numeric character encountered. The example returns the value 123.



WRAP

Statement

Syntax:

WRAP ON | OFF

Example:

WRAP ON

Sets display line wrap on or off. When wrap is on, output lines will be displayed in their entirety, in as many display lines as required. This applies to the LIST statement's output as well. When wrap is off, only the first display line of each output line will be displayed. This mode can be useful in long program listings or when the organization of formatted output is being checked. WRAP has no effect on the program in memory. The example sets line wrap on.






©2002 Picodoc, Inc.  All rights reserved.