H8 Emulation Help - Basic Language Documentation

Basic Language Documentation

This page presents a summary of the Benton Harbor Basic programming language dialect. This material is believed to be correct and complete, if somewhat terse, but if you have additional material or notice an error in this material, please forward it to the author for inclusion in the next update.

Programming Table of Contents

Main Table of Contents

Page Index	Commands
	Commands	BYE BUILD FREE CLEAR SCRATCH LIST	DELETE RUN CONTINUE STEP LOCK UNLOCK
	Source File Access	OLD SAVE REPLACE	UNSAVE FREEZE UNFREEZE
	Statements
	Program Statements	REM LET PRINT IF FOR / NEXT GOTO GOSUB / RETURN ON INPUT LINE INPUT	DATA READ RESTORE CHAIN END STOP PAUSE DIM DEF FN
	Operators	+ ' * / ^	< > = <>
	Logical Operators	AND OR NOT
	File Access Statements	OPEN INPUT LINE INPUT	CLOSE CIN()
	Hardware Access	PIN() OUT PEEK() POKE	CNTRL SEG() PAD()
	Functions
	Math Functions	ABS() INT() MAX() MIN() RND() SGN() SQR()	SIN() COS() TAN() ATN() LOG() EXP()
	String Functions	LEFT$() MID$() RIGHT$()	LEN() MATCH()
	Conversion Functions	ASC() CHR$() VAL()	STR$() LNO()
	Print Functions	SPC() TAB() POS()

Commands

The commands in this group are used to control the Basic interpreter itself and are not used as Basic program statements.

BYE

Exit the Basic interpreter. You will have to confirm that you want to leave by answering "y" to the prompt.

BUILD n,n

This is used to auto-number Basic programs when you are first building them. It takes two arguments: the first is the first line number to use, and the second is the line number increment.

Example:

BUILD 20,10

You will be prompted for programs starting at line number 20, followed by 30, 40, 50, .etc. Use Ctl-C to return to a command prompt.

FREE

Displays various categories of memory usage statistics. The most important of these is the free memory byte count at the bottom of the list.

CLEAR [variable]

Throws away all dynamic variables and other work space, freeing memory. All that's left is the program text itself. If the optional variable name is included, only that variable is cleared.

SCRATCH

Resets the workspace to its initial state as if you had just started the Basic interpreter. Use this command before starting a new program. You will need to confirm this command by answering "y" to the prompt.

LIST [n[,n]]

List the program source. If entered without the optional argument, the entire program will be listed. You can enter one line number to list only that line, or two line numbers to list a block of statements.

DELETE n[,n]

Delete one program statement, or a block of program statements.

RUN

Run the program currently in the workspace. The program will continue to run until:

an END statement is executed;
a STOP statement is executed;
an error is detected;
you type Ctl-C.

Stopping via STOP and Ctl-C allow you to continue execution where you left off, using the CONTINUE command.

CONTINUE

If the running program stopped due to execution of a STOP statement, or because you pressed Ctl-C, this command will cause the program to continue operation where it left off. A CONTINUE command following a CLEAR command or an END statement is treated the same as a RUN command; the program is started at the first line.

STEP n

Execute "n" statements of the program and then stop. This is very useful for debugging.

If the program has not been run, step will actually execute "n-1" statements the first time it's used. Each subsequent use will execute "n" statements.

LOCK

Locks the program so that the text cannot be changed or deleted.

UNLOCK

Unlocks the program so that changes can be made.

Source File Access Commands

These commands are used to read Basic programs from disk, save them to disk, and otherwise manage source program files.

In each of these commands, "filename" refers to a file on one of the H-17 disk drives. You may specify the drive ("sy1:myprog") or leave it off to read from sy0: ("myprog"). You may include the .bas file extension, but it is not necessary.

OLD "filename": Opens the program file and reads it into memory. If a program was already in memory when this command was entered, the Basic interpreter will clear the workspace before reading the new program. You do not need to enter SCRATCH first.

go to top
SAVE "filename": Creates a new file and saves the Basic program text in it. If "filename" already exists, an error message will be displayed. The file will not be overwritten. See REPLACE and UNSAVE.

go to top
REPLACE "filename": Overwrites "filename" with the Basic program currently in memory.

go to top
UNSAVE "filename": Deletes "filename" from disk. You will not be prompted to confirm the delete, so use care.

go to top
FREEZE "filename": This command saves the entire Basic interpreter and its workspace, including variables, arrays, etc., to disk as filename.baf. This file can be unfrozen (see UNFREEZE below) to continue work.

This command allows you to stop the execution of a long-running program and resume execution at another date. It also allows you to stop a long debugging session and resume it at a later date.

go to top
UNFREEZE "filename": Read in a frozen "filename.baf" file, including source code, variables, etc., and prepare to continue running the program.

(Note that the "filename.baf" file is in ABS file format. Instead of running Basic then using the UNFREEZE command, you can simply run "filename.baf" from an HDOS command prompt.)

go to top

Program Statements

Basic language statements start with a line number and contain one or more program statements.

You may place more than one statement on a line by separating them with a colon (":"). Example:

00010 PRINT "There is one statement on this line."
00020 PRINT:PRINT:PRINT "But there are three on this line."

Be aware that you can only GOTO or GOSUB to the beginning of a numbered line, so if a given statement is to be the target of a GOTO or GOSUB, it must be at the beginning of a line of code.

Variables are dynamically created when a value is first assigned to them. Variable names consist of a single letter or a letter and number. String variables add a "$" to the end of the name. Letter case is ignored.

These are all valid variable names:

a, a1, d7, b$, b9$

See the DIM statement below for information on array variables.

REM: This is a source comment. The remark continues to the end of the line. Examples:
00010 REM This is a comment
00020 a=10 : REM it works here, too

go to top
LET: This optional keyword begins an assignment statement of the form "LET variable = expression". LET is assumed if it is omitted; the following two statements are equivalent:
00010 LET a = b * 10
00010 a = b * 10

go to top
PRINT: Prints output to the console. (See also File Access Statements below for the form of PRINT to write to files.)

One PRINT statement can print a number of variables, literals, expressions or strings. If the arguments are separated by commas, they will be printed in zones that are 14 print positions wide by default (see CNTRL 3 in Hardware Access Statements). If the arguments are separated by semicolons, they will be printed one after the other. Examples:
00010 PRINT "This is a string"
00020 PRINT "Sum:";a+b;"and Product:";a*b
00030 PRINT "zones",a,b,c,d

go to top
IF (expression) THEN (statement): Evaluate the expression and execute the statement if the condition is true. Examples:
00010 a=10
00020 b=20
00030 IF a < b THEN a = a * 23
00040 IF a = b THEN GOTO 100
If the conditional statement is a GOTO, as in line #40 above, you can omit the GOTO keyword:
00040 IF a = b THEN 100

go to top
FOR / NEXT: These statements provide a looping mechanism in Basic. The statements between FOR and NEXT are executed repeatedly while varying the value of a variable. Examples:
00010 FOR i=1 TO 10
00020 PRINT i
00030 NEXT i
...will print a list of the integers 1 through 10. The variable is incremented by one on each pass through the loop.

If you want to increment by a value other than 1, or use a decrement instead of an increment, then add the STEP keyword:
00010 FOR i=100 TO 0 STEP -10
00020 PRINT i
00030 NEXT i
...will print the numbers 100, 90, 80, etc. through 0 on the console.

FOR/NEXT loops can be nested. Make sure that you close the inner loop before closing the outer loop.
00010 FOR i=1 TO 5
00020 FOR j=1 TO 5
00030 PRINT i*j
00040 NEXT j
00050 FOR k=10 to 15
00060 PRINT i+k
00070 NEXT k
00080 NEXT i

go to top
GOTO: Use the GOTO statement to branch to a different line in the program. Example:
00010 PRINT "Infinite Loop!"
00020 PRINT "Type Ctl-C to stop this program!"
00030 GOTO 10

go to top
GOSUB / RETURN: Branch to a different line in the program and run that section of code as a subroutine. When a RETURN statement is executed, execution will continue at the statement following the GOSUB command. Example:
00010 a=1
00020 GOSUB 100 : REM Print a
00030 a=a+10
00040 GOSUB 100
00050 END
00100 REM This is a subroutine
00110 PRINT "The value of 'a' is";a
00120 RETURN

go to top
ON: The ON command is a simple "computed GOTO/GOSUB" which will branch to one of a list of program statements depending on the value of a variable. (See also the LNO() function in Data Conversion Functions.) Example program fragment:
00110 GOSUB 1000 : REM print the menu on the console
00120 INPUT "What is your choice? ";c
00130 IF c<1 OR c>5 THEN 160
00140 ON c GOSUB 200, 250, 300, 350, 400
00150 GOTO 110
00160 PRINT "Incorrect selection!" : GOTO 110
If the user enters 4 at statement 120, the program will execute the subroutine starting at line 350, the fourth line number in the list.

go to top
INPUT ["prompt";]variable: Request input from the console. If the optional prompt is included, it will be printed on the console before waiting for input. If not, a "?" is used as a prompt.

The variable may be a numeric or string variable. If a string is entered into a numeric variable, an error message will be printed and the program will stop.

go to top
LINE INPUT "prompt";variable$: This statement is equivalent to 'INPUT "prompt";variable$' with one exception: LINE INPUT will accept a null entry and return a zero-length string, while INPUT will not..

go to top
DATA: This statement defines data to be stored as part of the program text. The data is read using the READ statement (below). This is typically used to initialize arrays.

go to top
READ: Read data from the data table. Example:
00010 REM sum a list of numbers
00020 REM -1 ends the list
00030 READ a
00040 IF a=-1 THEN END
00050 t=t+a
00060 GOTO 30
00100 DATA 1,2,4,5,6,7,9,10,14,23
00110 DATA 27,14,3,-1
DATA can be numbers, strings, or a mix. Your program must be aware of the order of mixed data so that you don't try to read a string into a numeric variable.

go to top
RESTORE: If you need to read a list of data more than once, you use the RESTORE statement to reset the DATA pointer to the first DATA item.

go to top
CHAIN "filename": Use CHAIN to read a new program off the disk and begin execution of that program. Any open files are still open; all defined variables are still defined. You can use CHAIN as a command; it's the same as using OLD followed by RUN.

go to top
END: Use END to end execution of a program.

go to top
STOP: Use STOP to stop execution of a program.

The only difference between STOP and END involves the CONTINUE statement. If you enter CONTINUE after a STOP, the program will continue operation with the statement following the STOP statement. If you enter CONTINUE after an END, the program will start at the top as if you had entered a RUN command.

go to top
PAUSE [ticks]: Use PAUSE to pause execution. If you include the optional integer argument, the program will pause for "ticks" clock ticks (or ticks * 2 milliseconds). If this is omitted, the program will pause until the user presses the enter key.

go to top
DIM: DIM is used to define and dimension an array. Example:
00010 DIM m$(5)
00020 FOR i=0 TO 5
00030 READ m$(i)
00040 NEXT i
00050 REM now print them back
00060 FOR i=0 TO 5
00070 PRINT m$(i)
00080 NEXT i
00090 END
00100 DATA "zero","one","two","three"
00110 DATA "four","five"
The value in parenthesis gives the highest valid index that can be used to access the array. The lowest valid index is zero, as shown in the example.

Arrays can be dimensioned with any reasonable number of indices. These are two and three dimensional tables:
00010 DIM a(5,5)
00020 DIM b(10,2,80)

Array b in the example above consists of 1,600 floating point numbers and uses 10,704 bytes of storage. Be careful with multidimensional arrays.

go to top
DEF FN: DEF FN is used to create user-defined functions. These functions can accept one or more arguments of either numeric or string type and can return a numeric or string value. The following program uses a function to convert degrees to radians for use with the SIN() function:
00010 DEF FN r(d) = d / 57.29578
00020 FOR i=30 TO 45
00030 PRINT "Sine of";i;"degrees is";SIN(FN r(i))
00040 NEXT i
00050 END
Here is an example using a mix of strings and numbers. A function is used to convert a number to a string exactly 6 characters long (including the trailing space).
00010 DEF FN s$(n) = right$(" "+str$(n),6)
00020 PRINT "'";FN s$(10);"'"

go to top

Operators

+ (add, concat.)

Add two numbers, or concatenate strings:

the result of 2+2 is 4;
the result of "abc"+"xyz" is "abcxyz".

- (subtract)

Subtract two numbers. 4-2 is 2.

* (multiply)

Multiply two numbers. 2*3 is 6.

/ (divide)

Divide two numbers 5/3 is 1.66667.

^ (exponent)

Raise a number to a power. 2^3 is 8. 2^.333333 is 1.25992 (the cube root of 2).

< (less than)

Used in IF statements to compare two values:

00120 IF a<b THEN GOTO 90

> (greater than)

Used in IF statements to compare two values:

00120 IF a$>b$ THEN GOTO 90

= (equal to)

Used in IF statements to compare two values:

00120 IF a=b THEN GOTO 90

<> (not equal to)

Used in IF statements to compare two values:

00120 IF a<>b THEN GOTO 90

Note on operator precedence

The standard rules of algebra apply: multiply and divide operations are done before add and subtract. The expression 1+2*3 will evaluate to 7.

Parenthesis can be used to change the order of evaluation. (1+2)*3 will evaluate to 9. Parenthesis can be nested to any reasonable level. (If you think that 15 levels is "reasonable," the author suggests that you forget about Basic and switch to Lisp!)

Logical Operators

These operators can be used to combine comparison operators in an IF statement, and to perform boolean operations on numeric values.

AND: Perform a binary AND operation on two values, or combine comparison operators in an IF statement.
15 AND 19 evaluates to 3

( 15 = 0000 1111 )
( 19 = 0001 0011 )
(AND = 0000 0011 )
When used with an IF statement, both conditions must be true for the conditional statement to be executed:
00110 IF a<b AND $b="abc" THEN GOSUB 1200

go to top
OR: Perform a binary OR operation on two values, or combine comparison operators in an IF statement.
15 OR 19 evaluates to 31

( 15 = 0000 1111 )
( 19 = 0001 0011 )
( OR = 0001 1111 )
When used with an IF statement, if either condition is true the conditional statement will be executed:
00110 IF a<b OR $b="abc" THEN GOSUB 1200

go to top
NOT: Perform a binary NOT operation on a single variable; flip the '1' bits to '0' and the '0' bits to '1'.
NOT 2 evaluates to 65533

(NOT 0000 0010 evaluates to 1111 1101)

go to top

File Access Statements

These statements allow a Basic program to open data files on the H-17 disk system and read and write the files.

OPEN: Opens a file for read or write access, and assigns a channel number to the file:
00010 OPEN "input.dat" FOR READ AS FILE #1
00020 OPEN "sy1:output.dat" FOR WRITE AS FILE #2

go to top
INPUT: This is the same input statement documented above. The channel number parameter is added to allow the data to be read from an open input file:
00010 OPEN "errormsg.sys" FOR READ AS FILE #1
00020 INPUT #1,"";a$
00030 PRINT a$
00040 GOTO 20

There is no end-of-file indication available; if you read past the end of the file, the next INPUT statement will cause an error and the program will end. You should include an end-of-data marker in the data, or see the CIN() function below for another approach.

go to top
LINE INPUT: This exactly duplicates the INPUT statement and has the same format. But LINE INPUT will accept null input and return a zero-length string, so LINE INPUT may be preferred, depending on what you are reading from the file.

go to top
CLOSE: Closes a file and frees the channel number. Output files must be closed for the output to be saved.
01230 CLOSE #1
01240 CLOSE #2

go to top
CIN(channel): This function reads a single character from a file open for read access, and returns the ordinal value of the ASCII character. CIN returns the value -1 at end of file. This example reads and prints "errormsg.sys" one character at a time... slowly:
00010 OPEN "errormsg.sys" FOR READ AS FILE #1
00020 a=CIN(1)
00030 IF a=-1 THEN 60
00040 PRINT CHR$(a);
00050 GOTO 20
00060 CLOSE #1
00070 END

CIN can be used to solve the INPUT statement end-of-file problem discussed with the INPUT statement. Let's rewrite that program to eliminate the read error.
00010 OPEN "errormsg.sys" FOR READ AS FILE #1
00020 a=CIN(1)            : REM read first char in line
00030 IF a=0 THEN 20      : REM strip nulls
00040 IF a=-1 THEN 90     : REM EOF
00050 LINE INPUT #1,"";a$ : REM read rest of line
00060 a$=CHR$(a)+a$       : REM reassemble entire line
00070 PRINT a$
00080 GOTO 20
00090 CLOSE #1
00100 PRINT :PRINT "we're at end of file":PRINT
00110 END

go to top

Hardware Access Statements

These statements and functions allow direct access to H8 hardware: I/O ports, memory, and the front panel.

PIN(port)

Read a byte from the specified port. Example:

PRINT PIN(237)

This reads the console UART's Line Status Register. The response should be 96 decimal (140 octal), which indicates that the transmitter holding register and the transmitter shift register are empty.

OUT port,value

Write a byte to the named port. Example:

OUT 232,7

This will write an ASCII BEL character to the console port (232 decimal = 350 octal), sounding the bell.

PEEK(address)

Read a byte from a memory address, expressed in decimal. See the RND() function below for an example.

POKE address,value

Write a byte to memory address, both expressed in decimal. See the SEG() function below for an example.

CNTRL

This command has five options that allow you to access certain hardware functions and change certain options in the Basic interpreter itself.

All of these can be used as commands. All but CNTRL 4 can be used as program statements.

CNTRL 0,line

This specifies a line to go to when the user presses Ctl-B. Example:

00010 CNTRL 0,40
00020 PRINT "Endless loop! Press Ctl-B!"
00030 GOTO 20
00040 PRINT "Whew! Thanks."
00050 END

While you can use it as in the preceding example, the function actually executes a GOSUB to the target line. Compare the program above with this one:

00010 CNTRL 0,40
00020 PRINT "Endless loop! Press Ctl-B!"
00030 GOTO 20
00040 PRINT:PRINT "That was a nice break":PRINT
00050 RETURN

You might use this function to, say, report progress on demand in a long-running program.... "We are on loop 345 of 10,000. Be patient!" You can see an example of this in the RND() function example in Mathmatical Functions.

CNTRL 1,value

This sets the number of digits (1 to 6) to print to the left of the E in scientific format. If a number is too big to print in this many digits, it will be changed to scientific format. Example:

*PRINT 12345
12345
*CNTRL 1,3
*PRINT 12345
1.23E+04

CNTRL 2,value

This controls the front panel LED display. A value of zero turns the display off (default condition after loading the Basic interpeter; the LEDs are normally off becaise updating the display takes up to 15% of the processor and you need all you can get to run Basic at a 2 mhz clock rate.)

A value of one turns the display on, but with update disabled. This allows you to write to the display yourself. See examples with the SEG() function below.

A value of two turns the display on with updates enabled, as it normally is when HDOS is running.

CNTRL 3,value

This command sets the width of the print zones. By default, the print zones are 14 columns wide, but they can be made larger or smaller with this command. Example:

*PRINT 1,2,3
1 2 3
*CNTRL 3,4
*PRINT 1,2,3
1 2 3

CNTRL 4,value

This command is used to load and unload the main HDOS overlay, HDOSOVL0. This is a command only; this cannot be used as a program statement. It should be used before a program is loaded into memory.

Normally, Basic allocates the maximum amount of available memory for your program, leaving the overlay on disk. This slows the execution of statements like OPEN and CLOSE, and slows the delivery of error messages, which are read from errormsg.sys. Loading the overlay into memory will reduce available memory by about 2.9 K/bytes, but will greatly speed the execution of your programs.

*CNTRL 4,1 - load the overlay
*CNTRL 4,0 - unload the overlay

This command has no effect if you are running HDOS in stand-alone mode.

SEG(value)

This function will take a decimal value from zero through nine and convert it to the binary pattern needed to display that value in the front-panel LEDs. The following example will put the digits 9 through 1 into the front panel LEDs:

00010 CNTRL 2,1 : REM turn on LEDs without update
00020 a=9
00030 FOR i=8203 TO 8211 : REM ref. memory map
00040 POKE i,SEG(a)
00050 a=a-1
00060 NEXT i

PAD(0)

Read a value from the H8 front panel keypad. Example:

00010 a=PAD(0)
00020 PRINT a
00030 IF a<>15 THEN 10
00040 STOP

Click the keys to see what decimal value is assigned to each key. Click the "." key to quit. ("." gives the value 15 decimal.) Here's another example:

00005 PRINT "Click on the keypad; click '.' key to quit"
00010 CNTRL 2,1
00020 i=8203
00030 s=PAD(0)
00040 IF s=15 THEN END
00050 POKE i,SEG(s)
00060 i=i+1
00070 IF i>8211 THEN i=8203
00080 GOTO 30

Mathmatical Functions

ABS(value)

Returns the absolute value (e.g., positive value) of the argument.

INT(value)

Returns the integer portion of the argument. INT(123.456) will return 123.

MAX(value,value,...)

Returns the largest of a list of values or numeric variables.

MIN(value,value,...)

Returns the smallest of a list of values or numeric variables.

RND(arg)

This is the pseudo-random number function. "arg" has three possible value ranges:

< 0: sets the random number "seed";
> 0: returns the next random number in the sequence;
= 0: returns the same random number as the last one.

If you start with the same seed value, you will get the same sequence of random numbers out of the generator. This can be good for testing but terrible for any real use, so the seed should be different from run to run. PAM/8's 16-bit .TICCNT is a reasonable source for a different number every time, as shown in this sample, which shows the average value of 10,000 random numbers. (The closer to .5, the better.)

00010 REM Randomize using .ticcnt
00020 r=PEEK(8219)+PEEK(8220)*256
00040 r=RND(-r)
00045 CNTRL 0,150 : REM on demand report
00050 FOR i=1 TO 10
00060 FOR j=1 TO 1000
00070 t=t+RND(1)
00080 NEXT j
00090 PRINT ".";
00100 NEXT i
00110 PRINT :PRINT "Total is";t
00120 PRINT "Average is";t/10000
00130 END
00150 REM on demand progress report
00160 PRINT
00170 PRINT "We are on number";(i-1)*1000+j;"of 10,000"
00180 RETURN

This program will run quite a long time, so we included a line-of-dots progress indicator (one dot per 1000 generated numbers) and an on-demand progress report accessed by typing Ctl-B. (Refer to CNTRL 0 in Hardware Access Statements.)

SGN(value)

Get the sign of the value. Returns 1 if the value is positive, and -1 if the value is negative.

SQR(value)

Returns the square root of the value.

SIN(radians)

Returns the sine of the angle, which must be expressed in radians (degrees divided by 57.29578).

COS(radians)

Returns the cosine of the angle, which must be expressed in radians.

TAN(radians)

Returns the tangent of the angle, which must be expressed in radians.

ATN(radians)

Returns the arctangent of the angle, which must be expressed in radians.

LOG(value)

Returns the natural logarithm of the value.

EXP(value)

Returns e raised to value power. EXP(LOG(10)) = 10.

String Functions

LEFT$(str$,len): Returns the left-most 'len' characters of the passed string.

LEFT$("Hello there, Bob!",5) returns "Hello"

go to top
MID$(str$,start,len): Returns a substring from the center of a string, starting at 'start' offset from the left and running for 'len' characters.

MID$("Hello there, Bob!",7,5) returns "there"

go to top
RIGHT$(str$,len): Returns the right-most 'len' characters of the passed string.

RIGHT$("Hello there, Bob!",4) returns "Bob!"

go to top
LEN(str$): Returns the length of the string.

LEN("Hello there, Bob!") returns 17

go to top
MATCH(stringa$,stringb$,start): This function searches 'stringa' for an occurrence of 'stringb', starting at 'start' offset into 'stringa'.

The following example looks for every occurrence of a given substring in a string, and prints the location where it is found, as well as the breakdown of the string to the left and right of the substring. This is a comprehensive example showing the use of MATCH, GOSUB, LEFT$(), MID$(), RIGHT$() and LEN().
*list
00010 a$="the cat in the hat hit the mat"
00020 b$="the"
00030 PRINT "Looking for '";b$;"' in '";a$;"'."
00040 s=1
00050 PRINT "starting at";s;"..."
00060 m=MATCH(a$,b$,s)
00070 IF m=0 THEN 120
00080 GOSUB 150
00090 s=m+1
00100 GOTO 50
00120 PRINT "no more matches"
00130 END
00150 PRINT "match at";m
00160 PRINT TAB(5);"left  ='";LEFT$(a$,m-1);"'"
00170 PRINT TAB(5);"mid   ='";MID$(a$,m,LEN(b$));"'"
00180 PRINT TAB(5);"right ='";
00190 PRINT RIGHT$(a$,LEN(a$)-m-LEN(b$)+1);"'"
00200 RETURN
*run
Looking for 'the' in 'the cat in the hat hit the mat'.
starting at 1 ...
match at 1
    left  = ''
    mid   = 'the'
    right = ' cat in the hat hit the mat'
starting at 2 ...
match at 12
    left  = 'the cat in '
    mid   = 'the'
    right = ' hat hit the mat'
starting at 13 ...
match at 24
    left  = 'the cat in the hat hit '
    mid   = 'the'
    right = ' mat'
starting at 25 ...
no more matches
End At Line  130
*

go to top

Data Conversion Functions

These functions all convert data from one form to another in interesting ways.

ASC(str$): The ASCII function returns the ordinal value of the first character in the passed string. ASC("ABC") will return 65; upper-case 'A' is the 65th ASCII character.

go to top
CHR$(value): This function returns the character that corresponds to the ordinal 'value' in the ASCII character set. CHR$(65) will return "A".

CHR$(ASC("A")) will return "A".

go to top
VAL(str$): The value function will return the numeric value of the first numeric substring in the passed string. Evaluation starts with the first non-blank character in the string and ends with the first non-numeric character.
VAL("123.45")             - returns the number 123.45
VAL("123   456  876")     - returns the number 123
VAL(" 123 is my address") - returns the number 123
VAL("12digits long")      - returns the number 12
VAL("my name is Dave")    - returns the number 0

go to top
STR$(value): This function returns a string containing the value of the passed expression, padded with spaces. STR$(123.45) returns " 123.45 " (note the leading and trailing spaces).

go to top
LNO(expression): This is a different kind of conversion altogether: LNO() converts the passed expression into a Basic line number.

It's illegal to use a numeric variable as a GOTO or GOSUB target:
00010 REM This is not legal
00020 a=50
00030 GOTO a
But this can be made legal by using the LNO() function:
00010 REM LNO() function to the rescue
00020 a=50
00030 GOTO LNO(a)
LNO() gives us a very powerful computed-GOTO/GOSUB capability. To rewrite the ON ... GOSUB example from above:
00110 GOSUB 1000 : REM print the menu on the console
00120 INPUT "What is your choice? ";c
00130 IF c<1 OR c>5 THEN 160
00135 REM compute line 200, 250, 300, 350, 400
00140 GOSUB LNO((c - 1) * 50 + 200)
00150 GOTO 110
00160 PRINT "Incorrect selection!" : GOTO 110
go to top

Printing Functions

The first two functions in this group are only valid in a PRINT statement. The last one, POS(0), is related to print output.

SPC(count): Print 'count' spaces on the console. Rather than trying to count the blanks you are typing between quotes, you can use this function to output a precise number of spaces.
PRINT "Ten";SPC(10);"spaces"

go to top
TAB(column): TAB moves the print cursor ahead to 'column'. Note the difference between TAB() and SPC(): the following example prints two identical lines of output.
00010 PRINT TAB(10);"a";TAB(20);"b";TAB(30);"c"
00020 PRINT SPC(9); "a";SPC(9); "b";SPC(9); "c"

go to top
POS(0): POS(0) returns the postion of the cursor on the console, based on the number of characters printed with PRINT statements. If you move the cursor to the right by hand using the cursor keys or the space bar, POS() will not register the move. Example:
00010 INPUT "enter a number from 1 to 50: ";n
00020 IF n<1 or n>50 THEN 10
00030 FOR i=1 TO n
00040 PRINT ".";
00050 NEXT i
00060 p=POS(0)
00070 PRINT "x"
00080 PRINT "that 'x' is in column";p;"of the screen"
00090 END
Only pass the value zero to the function, as shown. Other positive values will return a nonsense result.

go to top

Programming Table of Contents

Main Table of Contents