Chapter 11

BASIC09 Command Reference

BASIC09 is made of keywords (functions and statements) that you use, with their parameters, to instruct the computer to perform certain operations.


This chapter is a complete reference for all of BASIC09's keywords.


Keyword Format

 The reference to each keyword is organized in this manner:












This format can vary slightly, depending on the complexity of each keyword. For instance, some keywords require parameters or arguments, and others do not. Some keywords are selfexplanatory and do not require a sample procedure.


The Syntax Line

The second line in each command or keyword reference is the syntax line. This line uses keyword constants and keyword Vari ables to show you how to construct a command line. Constants are words, numbers, or symbols that you type exactly as they appear. Variables are words that only represent the actual words, numbers, or symbols that you must supply for the command.

BASIC09 Reference

All variables are italic. When you see an italicized word, you know that you must supply some other word, name, symbol, or value in place of that word. If a word, symbol, or value is not italicized, type it exactly the way it appears in the syntax line.


The syntax line also uses symbols to help you understand how to construct a command line. These symbols are:


Words, names, value, or symbols contained between right and left brackets are optional. You can use them or not, depending on what you want to accomplish with the command.


Ellipsis indicates that the last parameter can be repeated.


The following syntax line for DELETE requires only one parameter, the variable pathname.




Because pathname is italicized, you know that you must replace it with other text-in this case the pathlist to the file you want to delete. If you wanted to delete a file named Test from the ROOT directory of Drive /D1, this syntax line tells you that you must type:


delete "/d1 /test"

Other syntax lines are more complex, such as the line for CREATE:




This line tells you how to create a path to a file or device. Because the number symbol (#) is not italicized, you type it after the blank space following the keyword. However, path,pathl ist, and access mode are all italicized. You must replace them with other names or values.


The access mode variable is contained within brackets. This tells you that it is optional. You can include an access mode, or not. If you don't, BASIC09 opens the path in the Update Mode.


The second access mode shows that the command allows two access mode parameters, preceded by a plus symbol. The ellipsis show that you can have even more access mode parameters.


11-2

Other syntax lines show that no parameters are required, such as:




This command returns the current date. There is nothing it requires, and you can do nothing else with it.


Sample Programs

The sample programs in this chapter are complete. That is, you can type them, run them, and get a result. The procedures let you see the syntax and form of a command, as well as showing you how it might be used in a program.


Because the programs are executable, the manual shows unformatted listings (without relative address, indented control structures, and so on). This helps. eliminate confusion for you when you type the program. You can type it exactly as it appears, exit the editor, and run the procedure.


11-3
 BASIC09 Reference
ABS Return absolute value

 Syntax: ABS(number)
 Function: Computes the absolute value of number. A number's
 absolute value is its magnitude without regard to its sign.
 Absolute values are always positive or zero.

 Parameters:
 number Any positive or negative number.

 Examples:

 PRINT ABS(-66)

 X=ABS(Y)

 Sample Program:

 The following procedure asks you to type the temperature, and makes an appropriate comment. It uses ABS to get the absolute value of the temperature.

 PROCEDURE temperature ODIM TEMP:INTEGER DINPUT "What's the temperature outside? (Degrees F)...",TEMP OIF TEMP<0 THEN OPRINT "That's "; ABS(TEMP); " below zero !OOOBrrrrrrr REND REND I F OIF TEMP=0 THEN
 OPRINT "Zero degrees? That's mighty cold!" -
 OEND
 REND I F
 OPRINT TEMP; " degrees above zero? That's kind of
 balmy..."
 REND

 11-4

ACS Return arccosine
Syntax: ACS(number)
Function: Calculates the arccosine of number. Use the DEG or RAD commands to tell BASIC09 if number is in degrees or radians. If you do not specify degrees or radians, the default is radians.

 Parameters:
 number The number for which you want to compute
 the arccosine.
 Examples:
PRINT ASCC.6561)

 Sample Program:
The procedure calculates the arccosine of a value you type and expresses the result in degrees.

 PROCEDURE arccosine
 ODEG
 ODIM NUM:REAL
 DINPUT "Enter a number between -1 and 1",NUM
 OPRINT "The arccorsine of "; NUM; " 15 ---'x;
 ACSCNUM)
 OEND

 r
BASIC09 Reference
ADDRReturn the location of a variable
Syntax: ADDR(name)

Function: Returns the absolute location in a process's address space of the variable, array, or data structure assigned to name. The address returned is that of the first character in the variable. If the variable is numeric, one or more of the locations might contain zero.


For instance, if you use ADDR to obtain the address of an integer variable that contains the value 44, the first address location (byte) contains 0, and the second location contains 44.


Parameters:


Examples:

This procedure displays the memory address where a variable named X resides:


PRINT ADDRCX)

 11-6
 BASIC09 Command Reference / 11
Sample Program:
This procedure uses ADDR to tell you the memory location of the variable that stores your keyboard entry.

 PROCEDURE address
 pDIM A: INTEGER
 ODIM TEST:STRING
 pINPUT "Type a String of characters...",TEST
 DA=ADDRCTEST)
 OPRINT "The String you typed i5 Stored at addre55
 A
 OPRINT "This i5 what it contains:..."
 OFOR TzA TO A+LENCTEST)
 OPRINT CHR$CPEEKCT));
 ONEXT T
 OPRINT
 REND

 11-7
 BASIC09 Reference
AND Performs a logical AND operation
Syntax: operandl AND operand2
Function: Performs the logical AND operation on two or more values, returning a value of either TRUE or FALSE.

 Parameters:
operandl Can be either numeric or string values.
 opera
Examples:
PRINT A>3 AND B>3

 PRINT A$="YES" AND H$="YES"

 Sample Program:
The following program calculates an insurance premium rate that is based on the answers to some lifestyle questions. Every time you press E, the premium rate goes up. The procedure uses AND to increase the rate by two percent if you both smoke and drink.

 PROCEDURE policy
 pDIM POLICY-VALUE, RATE: REAL
 ODIM SMOKE,DRINK:STRINGL1J
 OPOL I CY-VALUE=1 000000 .
 ORATE=.001
 OINPUT "Do you smoke? CY/N)...",SMOKE
 OINPUT "Do you drink? CY/N)...",DRINK
 OIF SMOKE="Y" AND DRINK="Y" THEN RATE=RATE+.02
 DELSE -
 OIF SMOKE="Y" THEN RATE=RATE+.01
 OENDIF
 DIF DRINK="Y" THEN RATE=RATE+.01
 ®END I F
 SEND I F
 OPRINT "Your premium i5 "; RATE* POLICY-VALUE
 []END

 11-8

ASC Returns ASCII code

 Syntax: ASC (string) Function: Returns the ASCII code for the first character of string.
ASC returns the value as a decimal number. If string is null (contains no characters) BASIC09 returns Error 67 (Illegal Argument).

 Parameters:
 string Any string type variable or constant.

 Examples:

 PRINT ASC("Hello")










DA=ASC(HEXNUM) \ (* GET THE ASCII CODE *)
 EEXITIF A<48 OR A>57 AND A<65 OR A>70 THEN
 OPRINT "Not a hex number."
 REND
 r OENDEXIT
 SPRINT "Ok."
 OENDLOOP
 CI E N D

 11-9
 BASIC09 Reference
ASNReturns arcsine
Syntax: ASN(number)
Function: Calculates the arcsine of number. ASN expresses its result in radians unless you specify otherwise (see DEG).

 Parameters:


Examples:
PRINT ASC(. 6561

 Sample Program:
The following program calculates the arcsine of a number you enter and expresses the result in degrees.

 PROCEDURE arcsine pDIM NUM:REAL ODEG DINPUT "Enter a number (-1 to 1) ",NUM OPRINT "The arcsine of a "; NUM; " i5 ---"; ASN(NUM) REND

 11-10

ATN Returns arctangent

 Syntax: ATN(number)
Function: Calculates the arctangent of number.
Parameters:
 number The number for which you want to find the
 arctangent.

 Examples:

 PRINT ASC(. 6561

 Sample Program:

 This procedure calculates arcsine, arccosine, and arctangent for a value you enter.

 PROCEDURE anglecalc
 pDIM NUM:REAL
 ODEG
 pINPUT "Enter a number ",NUM
 OPRINT
 pPRINT " ","Arc5ine","Arcco5ine","Arctangent"
 OPRINT "Number","Degree5","Degree5","Degree5"
 OPRINT ··_-----------_-----------------_-----------

 OIF NUM>1 OR NUM<-1 THEN
 OPRINT NUM,"UNDEF","UNDEF",ATN(NUM)
 OPR I NT
 REND
 pENDI F
 OPRINT NUM,ASN(NUM),ACS(NUM),ATN(NUM)
 OPRINT
 REND

 11-11
 BASIC09 Reference
BASE Set array base

 Syntax: BASE 0
 BASE 1

Function: Sets a procedure's lowest array or data structure index to either 0 or 1. If you want to have the first elements in arrays set to 0, you must include B A S E 0 at the beginning of the procedure.


The BASE statement does not affect string operations such as MID$, RIGHTS, and LEFTS. BASIC09 always indexes the first character of a string as 1.


Parameters:

 0 or 1 If you do not indicate a BASE setting in a pro
 cedure, BASIC09 uses a default of 1.

 Examples:
 BASE 0

 Sample Program:

This procedure determines how many times RND selects each number between 0 and 11 out of 1000 selections. It stores the results in an array of 12 elements. Because it specifies BASE 0, one of the elements in the array is 0. Whenever the procedure picks a random number, it increments the value in the corresponding array number by one.


PROCEDURE randomtest
 OHASE 0 ( set the array base at 0.
 pDIM RND-ARRAY(12),X,R:INTEGER ( dimension array to hold results. -

 OFOR X=0 TO 11
 ORND-ARRAY(X)=8 ( initialize array elements at zero.
 pNEXT X
 OSHELL "TMODE -PAUSE" ( turn off screen pause.
 OFOR X=1 TO 1000
 OR=RND(11) ( select random number 1000 times.

 11-12

ORND-ARRAY(R)=RND-ARRAY(R)+1
 0 add 1 to appropriate element,

 OPRINT 1001-X 0 count down from 1000 to 1,

 ONEXT X

 OFOR X=0 TO 11 OPRINT "RND selected "; X; " "; RND-ARRAY(X); "
 times," (display array
 ONEXT X
 OSHELL "TMODE PAUSE" 0 turn scroll lock back on,
 REND

 11-13
 BASIC09 Reference
BYE End procedure, terminate BASIC09

 Syntax: BYE

 Function: Ends execution of a procedure and terminates BASIC09. The statement closes any open files, but you lose any unsaved procedures or data.

 Use BYE to exit packed programs that you call from OS-9 and especially programs that you call from procedure files.

 Parameters: None

 Examples:

 INPUT "Pre55 ENTER to return to the system.";Z$
 BYE

 Sample Program:

 This procedure calculates the payments and interest of a loan.
 When it is through, it exits the procedure and BASIC09 with a
 BYE statement.
 PROCEDURE loan
 pDIM PRIN,LENG.,RATE,MONPAY:REAL
 ODIM RESPONSE:STRINGf11
 OREPEAT
 OPRINT "Amortization Program"
 DINPUT "How much do you want to borrow?...",PRIN
 OINPUT "For how many months?...",LENG
 OINPUT "At what interest rate? ...",RATE
 DAmRATE/1288 .
 OH=1-1/(1+A)"LENG
 OMONPAY=PRIN*A/H
 OMONPAY=INT(MONPAY*188+.S)/108
 OPRINT "Monthly payments are...";
 OPRINT USING "R12.2c",MONPAY
 OPRINT "The total interest to pay is ...S";
 OPRINT USING "r12.2c",MONPAY*LENG-PRIN
 OPRINT
 OINPUT "Do another calculation?...",RESPONSE
 OPRINT
 OPRINT
 OUNTIL RESPONSE<>"Y"
 OHYE
 REND

 11-14

CHAIN Execute another module
Syntax: CHAIN "module [parameters] [... ]"

Function: CHAIN performs an OS-9 chain operation, passing module as the name of a program to execute. If you include other parameters, CHAIN passes them to the executing module. The module must be programmed to expect parameters of the type you provide.


CHAIN exits BASIC09, unlinks BASIC09, and returns the freed memory to OS-9.


CHAIN can begin execution of any module, not only BASIC09 modules. It executes the module indirectly through the shell in order to take advantage of the shell's parameter processing. This has the side effect of leaving the initiated shells active. Programs that repeatedly chain to each other eventually fill memory with waiting shells. To prevent this, use the EX option to initialize a shell.


BASIC09 does not close files that are open when you execute CHAIN. However, the OS-9 FORK call passes only the standard I/O paths (0, 1, and 2) to a child process. Therefore, if you need to pass an open path to another program segment, use the EX shell option.


Parameters:
 module The name of the procedure module you want
 BASIC09 to execute.
 parameters String data passed to the chained module.

 11-15
 BASIC09 Reference
Examples:

 CHAIN "ex BASIC09 menu"

 CHAIN "HASIC09 #10k sort (""datafile"",
 ""tempfile"")"

 CHAIN "DIR /D0"

 CHAIN "Dir; Echo *** Copying Directory ***; ex
 basic09 copydir"

 Sample Program:

 This procedure chains to two others to display a directory or a file. It uses CHAIN to call the procedures.

 PROCEDURE chaining
 pDIM RESPONSE:HYTE
 OPRINT USING "S26","- MENU -" (* print menu title.
 OPRINT
 OPRINT "1. List current data directory" (* print menu.
 OPRINT "2. Display a file"
 OPRINT "3. Exit to system"
 OPRINT
 DINPUT "Select a function (1-3) ",RESPONSE (* function you want.
 DON RESPONSE GOTO 100,200,300 (* select appropriate function.
 1000CHAIN "EX BASIC09 dirlook" (* chain to list directory.
 2000CHAIN "EX BASIC09 display" (* chain to list file.
 300OHYE

 PROCEDURE dirlook
 OREM Lists the specified directory

 OSHELL "DIR" (* execute dir command.
 OCHAIN "EX BASIC09 chaining" (* chain back to calling proc.
 REND

 PROCEDURE display
 OREM Lists the specified file. -

 ODIM FILE,JOH:STRING
 DINPUT "Path of file to display...",FILE
 OJOH="LIST "+FILE
 OSHELL JOB (* list specified file.
 OCHAIN "EX BASIC09 chaining" (* chain back to calling proc.
 REND

 11-16















''~ CHD " "




















I1-17
 BASIC09 Reference
CHR$ Return ASCII character
Syntax: CHR$(code) Function: Returns the ASCII character for the value of code. CHR$ is the inverse of the ASC function, which returns the ASCII code for a given character. For a complete listing of ASCII codes, see Chapter 9.

 Parameters:


Examples:
PRINT CHR$(88)
Sample Program:
By increasing by one the ASCII values of characters you type, the following program creates a secret code. It uses CHR$ to display the secret code.

 PROCEDURE secret
 ODIM TEXT,SECRETLINE;STRINGf88J
 ODIM T,CODECHAR:INTEGER
 OTEXT=1111
 0SECRETLINE=""

 OPRINT "Type a line to code in capital letters..."
 OINPUT TEXT ( you type a line,
 OFOR T=1 TO LEN(TEXT)
 OCODECHAR=ASC(MIDS(TEXT,T,1)) ( look at each character in line.
 OF CODECHAR=90 THEN ( is it "Z"? If yes then
 OCODECHAR=64 ( make it one less than "A".
 OENDIF
 OF CODECHAR=32 THEN t is character a space? If yes then
 OCODECHAR=31 t decrease its value by one.
 DENDIF

 OSECRETLINE=SECRETLINE+CHRS(CODECHAR+1) (* add 1 to characters.
 ONEXT T
 OPRINT SECRETLINE (* print the secret code.
 REND

 11-18

CHX Change execution directory CHD Change data directory

 Syntax: CHX dirpath
 C HD dirpa th
Function: Changes the current execution or data directory.

 Parameters:

 dirpath An existing execution or data directory.

 Examples:
CHX "/D1 /CMDS"

 CHD "/D1/ACCOUNTS/RECEIVABLE" CHD 11..11
11-19
 BASIC09 Reference
CLOSE Deallocate file or device path
Syntax: CLOSE #pathnum

Function: Deallocates the file or device path specified by pathnum.


When you OPEN or CREATE a file, BASIC09 allocates a path number to the variable you supply in the OPEN or CREATE command. The system then knows the path by that number. If the path you CLOSE is to a non-shareable device (such as a printer), the system releases the device for other use. Do not close paths 0, 1, and 2 (the standard I/O paths) unless you immediately open a new path to take over the standard path number.


Parameters:
pathnum The name of variable containing the path
 number or the actual number of the path to a
 file or device.
 Examples:
CLOSE #FILEPATH, #PRINTERPATH, #TERMPATH

 CLOSE #5, x6, #7

 CLOSE x1 \ (* closes the standard output path *)
 OPEN #PATH,"/T1" \ (* redirects standard output *)

 Sample Program:

This procedure creates a directory named TEST and changes it to the data directory. It then creates a file named Samplefile and writes data to the file. Finally it changes back to the parent directory and deletes Samplefile and TEST.


11-20

PROCEDURE close
 ODIM PATH;HYTE
 OSHELL "MAKDIR TEST"
 OCHD "TEST"
 OCREATE #PATH,"samplefile";WRITE (* create a new file.
 OWRITE #PATH,"This file is for testing only."
 OWRITE #PATH,"It will be destroyed when this procedure ends."
 OCLOSE #PATH (* close the file.
 OSHELL "LIST samplefile"
 OCHD ".."
 OSHELL "DELDIR TEST"
 FIEND

 11-21
 BASIC09 Reference
COS Return cosine

 Syntax: COS(number)
Function: Calculates the cosine of number. Unless you specify DEG, COS interprets the value of number in radians.

 Parameters:

Examples:
PRINT COSC45)

 Sample Program:

 This procedure calculates sine, cosine, and tangent of a value you enter.

 PROCEDURE ratiocalc
 ODIM NUM:REAL
 pDEG
 INPUT "Enter a number...",NUM SPRINT pPRINT "Number", "SINE","COSINE","TAN"

 OPRINT '

 pPRINT ANGLE,SINCNUM),COSCNUM),TANCNUM) SPRINT pEND

 11-22

CREATE Establish a disk file.

 Syntax: CREATE # pa th, "pa thlist" [access mode] [ + access mode] [ + ... ]
Function: Creates a file on a disk. When you create a file, you can select one or more of the following access modes for the file:

 Mode Function
 READ Lets you read (receive) data from a file but
 does not let you write (send) data to the file.
 WRITE Lets you write data to a file but does not let
 you read data from a file.
 UPDATE Lets you both read from and write to a file.

 Parameters:

 path The name of the variable in which BASIC09
 stores the number of the opened path.
 pathlist The route to the file or device to be opened,
 including the filename, if appropriate.
 access mode The type of access to be allowed for the file or
 device. Use plus symbols to allow more than
 one type of access with a single file.
 Notes:




BASIC09 Reference
    e A new file has a size of zero. OS-9 then expands the file automatically when PRINT, WRITE, or PUT statements write beyond the current end-of-file.


Examples:
 CREATE #TRANS,"transportation":UPDATE
 CREATE #SPOOL,"/user4/report":WRITE
 CREATE *OUTPATH,name$:UPDATE+EXEC

 Sample Program:

 This procedure CREATES a directory named TEST and makes it the data directory. It creates a file in TEST named Samplefile, writes data to the file, then resets the parent directory as the data directory. Finally, it deletes Samplefile and TEST.

 PROCEDURE close
 ODIM PATH:BYTE
 OSHELL "MAKDIR TEST"
 OCHD "TEST"
 OCREATE #PATH,"5amplefile":WRITE (* create a file.
 OWRITE #PATH,"This file is for testing purposes only."
 OWRITE #PATH,"It will be destroyed when this procedure ends."
 OCLOSE #PATH (* close the file.
 OSHELL "LIST samplefile"
 OCHD ",."
 OSHELL "DELDIR TEST"
 REND

 11-24
 BASIC09 Command Reference l 11
DATA Store numeric and string information

 Syntax: DATA "item" [,"item",... ]

Function: Stores numeric and string constants to be accessed by a READ statement. A DATA line can contain up to 254 characters. Each item in the list must be separated by commas.


You can place DATA statements anywhere in a procedure that is convenient. BASIC09 reads sequentially, starting with the first item in the first DATA statement, and ending with the last item in the last DATA statement.


The following rules apply to data items:

      You must place all string data between quotation marks.


0 To include quotes

 .n string-type data, use consecutive

quotation marks, like this: DATA " H e 5 a i d , " " g o home"" to me".


You can use RESTORE to reset the data pointer. Using RESTORE without an argument resets the pointer to the beginning of the data items. Using RESTORE with a line number, resets the pointer to the first item in the specified line.


· The READ statement can support a list of one or more variable names of various types. The data types in DATA statements must match the variable types used in the corresponding READ statements.


· You can include arithmetic expressions in data items. READ causes the expressions to be evaluated and returns the result of the expression as the data item.


Parameters:

 item Numeric or string characters. Enclose string
 characters in quotation marks.
 BASIC09 Reference
Examples:
DATA 1.1,1.5,9999,"CAT","DOG" DATA SINCTEMP/25), COSCTEMP*PI) DATA TRUE,FALSE,TRUE,TRUE,FALSE DATA "The rain in Spain","falls mainly on the plain"

 Sample Program:
 This procedure calculates the day of the week for a date you enter. A data statement contains the names of the weekdays.

 PROCEDURE weekday ODIM X,DAY,MONTH,YEAR,CALC:INTEGER pDIM ANUM,HNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM,INUM: INTEGER ODIM WEEKDAYC7):STRINGL9J OPRINT USING "S60^","Day of the Week Program" pPRINT USING "S60^","For any year after 1752" pPRINT OINPUT "Enter day of the month as two digits, such as 08...",DAY pINPUT "Enter month as two digits, such as 12...",MONTH pINPUT "Enter year as four digits, such as 1986...",YEAR OFOR X=1 TO 7 DREAD WEEKDAYCX) ONEXT X OANUM=INTC.6+1/MONTH) OHNUM=YEAR-ANUM OCNUM=MONTH+ 1 2 * ANUM ODNUM=HNUM/ 1 0 0 pENUM=INTCDNUM/4) OFNUM=INTCDNUM) OGNUM=INTCS*HNUM/4) OHNUM= I NTC 1 3* C CNUM+ 1) / 5 ) pINUM=HNUM+GNUM-FNUM+ENUM+DAY-1 OINUM=INUM-7*INTCINUM/7)+1 OPRINT pPRINT "The day of the week on "; DAY; "/"; MONTH; OPRINT "/"; YEAR; " is..."; WEEKDAYCINUM) ODATA "Sunday","Monday","Tuesday","Wednesday", "Thursday" ODATA "Friday","Saturday" REND
11-26