.PS 60,79
.LS 1
.LM 10;.RM 75
.TS 15,25
.FG 18
.DT 03/06/81
.WC
^^BASIC DOCUMENTATION\\
.WC
03/06/81
.TITLE ^^BASIC DOCUMENTATION\\
@BASIC.TOC
.CHAPTER ^^INTRODUCTION\\
.SKIP
.X ^INTRODUCTION
^THIS ^^BASIC\\ FOLLOWS ^^DEC\\'S ^^BASIC-11\\ IN ITS BASIC ORIENTATION.
^ADVANCED FEATURES TEND TO FOLLOW <RSTS <BASIC-PLUS (E.G. VIRTUAL ARRAYS).
^PRIMARY DIFFERENCES ARE IN THE FILE ^I/^O.
^THE ^^OPEN, PRINT\\ AND ^^INPUT\\ STATEMENTS HAVE BEEN MODIFIED
TO PROVIDE FULL ^^FILES-11\\ CAPABILITY FOR ^^ASCII\\ FILES BOTH
FIXED AND VARIABLE LENGTH AND SEQUENTIAL AND RANDOM ACCESS.
^THE STATEMENT CONCATENATION CHARACTER IS THE COLON (:).
.S
.X <IMMEDIATE MODE
<BASIC CAN BE USED IN AN <IMMEDIATE MODE. ^ANY LEGAL COMMAND ENTERED
WITHOUT A LINE NUMBER (OR LEADING "TAB") WILL BE PERFORMED IMMEDIATELY.
^NEARLY ALL THE <BASIC CODES PRESENTED IN THIS DOCUMENT CAN BE USED IN
THE <IMMEDIATE MODE AND A FEW CAN BE USED
ONLY IN THE <IMMEDIATE MODE. 
.FG 1
^THE OTHER <BASIC MODE IS THE <PROGRAM MODE.
^ANY LEGAL COMMAND FOLLOWING A LINE NUMBER OR WITH A LEADING "TAB",
(EFFECTIVELY A CONTINUATION LINE,) WILL BE STORED WITH THE CURRENT
PROGRAM AND EXECUTED IN NORMAL PROGRAM FLOW.
.S
<BASIC COMES IN SEVERAL 'SIZES'. ^WHEN A USER
INVOKES <BASIC BY CALLING FOR <BAS, THE
SPACE RESERVED FOR THE PROGRAM AND DATA IN MAIN MEMORY
CONTAINS 2570 BYTES. ^THE NEXT
'SIZE' IS <BA2, 4618 BYTES. ^THE LARGEST IS <B11, 23050 BYTES.
.S
^IF A USER'S  PROGRAM CALLS FOR MORE THAN THE
SPACE ALLOTED TO IT, THE COMPUTER STOPS EXECUTION
AND PRINTS OUT A ^^USERS OVERFLOW\\ ERROR MESSAGE.
^EXIT AND RE-ENTER THE <BASIC MODE AT A HIGHER
VERSION.
.FG 1
^ALL NUMERIC CALCULATION IS DONE IN FLOATING POINT (^^REAL*4\\ FOR YOU
^^FORTRAN\\ BUFFS) REGARDLESS OF THE VARIABLE TYPES IN THE EXPRESSION.
.S
.HEADERLEVEL 1 ^STATEMENT AND LINE FORMAT
.X ^STATEMENT AND LINE FORMAT
.BR
^MULTIPLE STATEMENTS MAY BE CONCATENATED ON A SINGLE LINE BY USE OF
THE COLON (:) CHARACTER.
^A BACKSLASH (_\) IS ALSO ALLOWED FOR <BASIC-<PLUS COMPATIBILITY.
^A LINE MAY BE CONTINUED ON THE NEXT LINE WITHOUT USING A NEW LINE
NUMBER BY STARTING THE CONTINUED LINE WITH A TAB OR TWO SPACES.
^CONTINUED LINES ARE TREATED THE SAME WAY AS IN <BASIC-PLUS: THE
END OF A PHYSICAL LINE IS IGNORED DURING EXECUTION SO LONG AS AN
INDIVIDUAL <BASIC ELEMENT IS NOT BROKEN ACROSS LINE BOUNDARIES.
^THE END OF LINE DOES NOT SERVE TO END A STATEMENT EXCEPT WHEN
THERE IS NO CONTINUED LINE FOLLOWING IT. ^THUS A STATEMENT WHICH
BEGINS ON A CONTINUED LINE MUST EITHER HAVE A CONCATENATION
CHARACTER AT THE START OF ITS LINE OR THE END OF THE PREVIOUS
LINE. ^THERE IS AN EXCEPTION IN THE CASE OF A COMMENT (! ONLY)
TERMINATING THE PREVIOUS LINE, IN WHICH CASE NO CONCATENATION
CHARACTER IS USED.
^CARE SHOULD BE TAKEN NOT TO START AN IMMEDIATE MODE
COMMAND WITH A TAB OR DOUBLE SPACE AS IT WILL NOT BE EXECUTED BUT
ADDED TO THE EXISTING PROGRAM AS A CONTINUATION OF THE LAST ENTERED
PROGRAM LINE.
.S
^NOTE THAT CHECKING OF PROGRAM STATEMENTS FOR VERB LEGALITY AS THEY
ARE READ IN BY THE INTERPRETER IS NO LONGER DONE AS IT WAS IN
EARLIER VERSIONS. ^ALL CHECKING IS NOW DONE AT RUN TIME.
.S
.HEADERLEVEL 1 ^VARIABLE NAMES
.X ^VARIABLES
.BR
^VARIABLE NAMES MAY BE ONE OR TWO CHARACTERS OF WHICH THE FIRST IS ALPHA
AND THE SECOND (IF USED) IS ALPHANUMERIC, FOLLOWED BY AN OPTIONAL TYPE
CHARACTER. ^IF NO TYPE CHARACTER IS USED, THE TYPE IS <REAL*4. ^A $ DENOTES
A STRING VARIABLE, % IS AN INTEGER VARIABLE (16 BITS) AND _& IS A BYTE
VARIABLE (8 BITS). ^NOTE THAT UNLIKE STANDARD <BASIC, THE SECOND CHARACTER
OF THE VARIABLE NAME IS ALLOWED TO BE ALPHABETIC. ^IN ORDER TO GAIN THIS
FLEXIBILITY IN NAMING VARIABLES, SOME RESTRICTIONS HAD TO BE MADE IN THE
ALLOWED FORMAT OF THE PROGRAM TEXT: SPACES ARE NOT ALLOWED WITHIN A
VARIABLE NAME; VARIABLE NAMES MUST NOT BE THE SAME AS <BASIC KEY WORDS
(E.G. <TO AND <IF).
^ALSO, AMBIGUITIES MAY SOMETIMES ARISE WHEN A VARIABLE  IS NEXT TO A
KEYWORD IN THE PROGRAM TEXT. ^THIS CAN USUALLY BE RESOLVED BY RE-WRITING
THE TEXT. ^ALTHOUGH IT IS THEORETICALLY POSSIBLE TO RESOLVE THESE CASES IN
THE INTERPRETER, THE EXPENSE IN TERMS OF INTERPRETER CODE LENGTH AND
EXECUTION TIME DOES NOT SEEM TO WARRANT IT. ^CONSIDER THE FOLLOWING EXAMPLE:
.NF
^^
	100 IF A _< MT OR B=5. THEN 500
\\
.F
^THE ^T OF <MT AND THE ^O OF <OR ARE MISINTERPRETED BY <BASIC TO FORM
THE KEYWORD <TO.
^THE STATEMENT CAN BE REWRITTEN UNAMBIGUOUSLY AS FOLLOWS:
.NF
^^
	100 IF (A _< MT) OR (B=5.) THEN 500
\\
.F
.S
.HEADERLEVEL 1 ^VIRTUAL ARRAYS
.BR
.X ^VIRTUAL ARRAYS
^VIRTAUL ARRAYS ARE USED TO STORE EXTENSIVE NUMBERS OF VARIABLE VALUES,
USUALLY MORE THAN IS PRACTICAL TO STORE IN AN IN-MEMORY ARRAY.
^THE USE OF VIRTUAL ARRAYS INVOLVES A SPECIAL FORM OF THE <DIM STATEMENT
AND THE FILE <OPEN STATEMENT WITH THE BLOCK MODE SWITCH </BL.
^SEE THE <DIM STATEMENT DOCUMENTATION FOR DETAILS OF VARIABLE MAPPING
INTO VIRTUAL ARRAY FILES.
.S
^MECHANICS OF VIRTUAL ARRAY FILES: ^VIRTUAL ARRAY FILES ARE OPENED IN BLOCK
MODE USING THE </BL SWITCH.
^THERE IS NO RECORD STRUCTURE SUPERIMPOSED OVER THE BASIC BLOCK STRUCTURE.
^THEREFORE ONLY THE FILE ACCESS MODE SWITCHES CAN BE USED IN CONJUNCTION
WITH </BL. ^THIS ALSO IMPLIES THAT A VIRTUAL ARRAY FILE DOES NOT SUBTRACT
FROM THE TOTAL NUMBER OF FILES (RECORD TYPE) WHICH MAY BE OPEN SIMULTANEOUSLY
(CURRENTLY 6).
.S
^VIRTUAL ARRAYS ARE MAINTAINED IN MEMORY ONE BLOCK AT A TIME (512 BYTES).
^WHEN A VARIABLE IS ACCESSED, THE APPROPRIATE BLOCK IS CALCULATED AND,
IF NECESSARY, READ INTO MEMORY. ^IF ANY WRITING TO THAT BLOCK IS DONE,
A FLAG IS SET AND WHEN A DIFFERENT BLOCK NEEDS TO BE READ IN, THAT ONE
IS WRITTEN OUT. ^THIS HAS SEVERAL IMPLICATIONS: ^FIRST, ON A VIRTUAL FILE
OPENED FOR READ ONLY ACCESS, AN ILLEGAL WRITE WILL NOT BE DETECTED UNTIL
THE BLOCK AS A WHOLE ATTEMPTS TO BE WRITTEN OUT. ^ALSO, IN THE CASE THAT
THE INTERPRETER ABORTS OR THE SYSTEM CRASHES, NEW OR CHANGED DATA MAY BE
LOST FOR THAT BLOCK WHICH IS THEN IN MEMORY.
.SKIP
.HEADERLEVEL 1 ^STRING CONSTANTS
.BR
.X ^STRINGS
^STRING CONSTANTS ARE SPECIFIED WITH DOUBLE QUOTES.
^AT THIS POINT IT IS NOT POSSIBLE TO REPRESENT A DOUBLE QUOTE
IN A STRING CONSTANT, I.E. A STRING DELIMITED BY DOUBLE QUOTES.
^HOWEVER, THIS LIMITATION MAY BE GOTTEN AROUND BY USING ^^INPUT\\
OR ^^READ\\ OR THE ^^CHR$\\ FUNCTION.
.SKIP
.HEADERLEVEL 1 ^DATA AND FILE PRESERVATION
.BR
.X ^^CLEAR\\
.X ^^RUN\\
.X ^FILE CLOSE
^USER DATA IS NOW KEPT INTACT EXCEPT FOR ^^CLEAR\\ AND ^^RUN\\ COMMANDS.
^USER FILES ARE AUTOMATICALLY CLOSED ON EXECUTION OF THE ^^RUN\\
OR ^^CLEAR\\ COMMANDS AND ON EXIT FROM ^^BASIC\\.
^THEY REMAIN OPEN (UNLESS EXPLICITLY CLOSED BY A ^^CLOSE\\ COMMAND)
ON PROGRAM STOP FOR DEBUGGING PURPOSES.
.SL
.HEADERLEVEL 1 ^STRING VARIABLES
.BR
^STRING VARIABLES ARE DECLARED IN A ^^DIM\\ STATEMENT AND CAN BE EITHER
FIXED OR VARIABLE LENGTH.
^SEE ^^DIM\\ STATEMENT FOR THE SPECIFICS.
.SL
.HEADERLEVEL 1 ^EXPONENTIATION
.X ^EXPONENTIATION
.X ^POWERS OF NUMBERS
.BREAK
^EXPONENTIATION (_^) IS DONE IN TWO WAYS.
^IF THE EXPONENT IS AN INTEGER, THE BASE IS MULTIPLIED (OR DIVIDED)
BY ITSELF THE APPROPRIATE NUMBER OF TIMES.
^IF THE EXPONENT CONTAINS A FRACTIONAL PART, A LOG - ANTILOG CALCULATION
SEQUENCE IS USED.
.SL
.HEADERLEVEL 1 ^^MCR COMMAND LINE\\
.X ^^MCR COMMAND LINE\\
.BREAK
^^BASIC\\ IS CALLED FROM THE ^^MCR\\ BY TYPING ^^BASIC\\ (OR ^^BAS\\)
IN RESPONSE TO THE ^^MCR\\ PROMPT.
^A _<^C^R> MAY FOLLOW FOR NORMAL INTERACTIVE USE OR ONE OF TWO OTHER
OPTIONS MAY FOLLOW BEFORE _<^C^R> FOR SPECIAL USES.
.FG 1
^IF A SPACE AND A ? FOLLOWED BY AN ARITHMETIC EXPRESSION FOLLOWS ^^BAS\\,
THE VALUE OF THE EXPRESSION WILL BE PRINTED ON THE NEXT LINE FOLLOWED
BY A RETURN TO THE ^^MCR\\.
^THIS IS USEFUL FOR QUICK DESK CALCULATOR TYPE CALCULATIONS.
.FG 1
^IF A SPACE (OR TAB) AND A FILE NAME WITH AN OPTIONAL SWITCH FOLLOW,
THEN THAT FILE WILL BE READ IN AS A USER PROGRAM JUST AS IN THE ^^OLD\\
COMMAND.
.FG 1
^IF THE SWITCH (/^R^N) IS SPECIFIED, THE PROGRAM WILL ALSO BE RUN AS
THOUGH THE ^^RUN\\ COMMAND HAD BEEN TYPED.
^A SWITCH OF THE FORM "</RN:NNN" WILL CAUSE THE PROGRAM TO START
EXECUTION AT LINE _# <NNN.
.FG 1
^IF THE SWITCH (/^C^O) IS ADDED, THEN THE FILE RETRIEVED WILL BE
ASSUMED TO BE PREVIOUSLY COMPILED AND A DEFAULT EXTENSION OF <BAC
WILL BE USED.
.NOTE
^NOTE THAT NO QUOTES ARE USED HERE AS OPPOSED TO THE ^^OLD\\ AND
^^RUN\\ COMMANDS.
.ENDNOTE
^EXAMPLES:
.NOFILL
^^
	MCR>{BAS}
	MCR>{BASIC PROG.BAS/RN}
	MCR>{BAS PROG/RN:150}
	MCR>{BAS ? 4*3+2}
\\
.FILL
.SL
.HEADERLEVEL 1 ^CONTROL ^C
.BR
.X _^^C
.X ^CONTROL ^C
^THE BREAK KEY FOR ^^BASIC\\ IS THE ^CONTROL-^C (_^^C).
^A _^^C TYPED AT THE KEYBOARD WHEN RUNNING WILL CAUSE THE PROGRAM
TO STOP AT THE NEXT SEQUENTIAL LINE (NOT AT A LINE ENTERED VIA
<GOTO, <GOSUB, <IF ETC.).
^WHEN IN IMMEDIATE MODE, _^^C WILL BRING UP <MCR IF THE TERMINAL HAS
NOT BEEN SET HOSTILE.
_^^C TYPED DURING A LIST COMMAND WILL TERMINATE THE LISTING PROCESS
AFTER THE CURRENT LINE IS FINISHED PRINTING OUT.
^IT CAUSES AN IMMEDIATE RETURN TO THE INTERPRETER AS OPPOSED TO
_^^O WHICH ONLY SUPPRESSES PRINTING WHILE THE <BASIC INTERPRETER
STILL GOES THROUGH THE MOTIONS OF COMPLETING THE LISTING.
.TP 6
.SL
.HEADERLEVEL 1 ^CONTROL ^O
.BR
.X ^CONTROL ^O
.X _^^O
^CONTROL-^O (_^^O) WILL STOP ALL OUTPUT FROM A ^^LIST\\ COMMAND
AND RESUME PRINTING WITH ^^READY\\.
^IT ALSO STOPS ALL PRINTING FOLLOWING A ^^RUN\\ COMMAND INCLUDING
NON-FATAL ERRORS.
^PRINTING RESUMES WITH A ^^STOP\\ OR _^^C OR A FATAL ERROR (ONE
WHICH STOPS PROGRAM EXECUTION).
.SKIP
.X ^LOGICAL ^EXPRESSIONS
.HEADERLEVEL 1 ^LOGICAL ^EXPRESSIONS
.BR
^LOGICAL EXPRESSIONS ARE OF THE FORM:
.BR
	^^_<EXP>_<REL-OP>_<EXP>[_<LOGICAL-OP>_<EXP>_<REL-OP>...]
\\
.BR
^WHERE EXPRESSIONS ARE EITHER ARITHMETIC OR STRING AND RELATIONAL OPERATORS
CAN BE FORMED BY ANY COMBINATION OF _<, > AND =.
^THE TWO EXPRESSIONS WHICH ARE RELATED BY THE RELATIONAL OPERATOR MUST BE
OF THE SAME TYPE: I.E. STRING OR ARITHMETIC.
^THE RESULT OF EVALUATING THE RELATIONSHIP (TERMED HERE A LOGICAL
SUBEXPRESSION) IS EITHER TRUE OR FALSE.
.FG 1
^STRINGS ARE COMPARED CHARACTER BY CHARACTER ON THE BASIS OF THEIR <ASCII
CODES. ^WHEN TWO STRINGS OF UNEQUAL LENGTH MATCH AT ALL COMMON CHARACTER
POSITIONS, THE SHORTER ONE IS CONSIDERED LESS THAN THE LONGER ONE.
.FG 1
^LOGICAL SUBEXPRESSIONS CAN IN TURN BE RELATED BY THE LOGICAL (^BOOLEAN)
OPERATORS: <AND, <OR, <XOR AND <NOT.
^THE ORDER OF EVALUATION IS FROM LEFT TO RIGHT, BUT LOGICAL SUBEXPRESSIONS
MAY BE NESTED WITH PARENTHESES TO ANY DEPTH DESIRED.
.FG 1
^ONE RESTRICTION EXISTS WITH RESPECT TO PARENTHESES: NO LEADING ARITHMETIC
EXPRESSION IN A LOGICAL SUBEXPRESSION SHOULD BEGIN WITH AN OPEN PARENTHESIS,
OTHERWISE THE INTERPRETER WILL ATTEMPT TO EVALUATE IT AS A NESTED
SUBEXPRESSION. ^THIS CAN EASILY BE GOTTEN AROUND BY REARRANGING THE
ARITHMETIC EXPRESSION OR ADDING IT TO 0.
.BR
^EXAMPLES:
^^
.NF
	{A _< B OR B = .5}
	{NOT (X1 _< 1 AND A >= 5)}
\\
.F
.CHAPTER ^^LOADING/RUNNING/SAVING PROGRAMS\\
^THE SUBSET OF COMMANDS LISTED IN THIS CHAPTER IS PRIMARILY USED TO CONTROL
EXECUTION OF <BASIC PROGRAMS. ^THEIR PURPOSE IS TO LET ONE LOAD
SAVED PROGRAMS, INTERACTIVELY MODIFY/DEBUG THEM WHILE RUNNING, AND
POSSIBLY SAVE MODIFIED VERSIONS FOR LATER USE.
^AS SUCH, THE EQUIVALENT COMMANDS NORMALLY DO NOT EXIST FOR COMPILED
LANGUAGES SUCH AS <FORTRAN.
.SKIP
.X ^^STOP\\
.X ^^END\\
.HEADERLEVEL 1 ^^STOP . . END\\
.BREAK
^^STOP\\ AND ^^END\\ STATEMENTS.
^STOP USER PROGRAM EXECUTION AND TELL USER WHERE PROGRAM HAS STOPPED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 STOP}
	{20 END}
\\
.FILL
.SKIP
.X ^^RUN\\
.HEADERLEVEL 1 ^^RUN\\
.BREAK
^MAY BE USED IN IMMEDIATE MODE TO START THE PROGRAM IN MEMORY OR BY
SPECIFYING A FILE IN QUOTES TO RUN ANOTHER ^^BASIC\\ PROGRAM
STORED ON DISK.
.FG 1
^IN PROGRAM MODE, IT MAY BE USED WITH A FILE SPECIFIER TO CHAIN
TO ANOTHER PROGRAM.
^THE ASSUMED FILE EXTENSION IS ^^.BAS\\.
^NOTE THAT NO DATA IS SAVED ACROSS A ^^"RUN"\\ TYPE CHAIN.
^USER LOADED SUBROUTINES ARE ALSO UNLOADED.
^TO PRESERVE DATA AND USER FILES, USE ^^"CHAIN"\\ COMMAND.
.FG 1
^A PREVIOUS RESTRICTION AGAINST USING A VARIABLE IN THE
STRING EXPRESSION FOLLOWING THE <RUN COMMAND HAS BEEN REMOVED.
^THE OPTIONAL SWITCH /^R^T MAY BE USED AS WITH ^^OLD\\ TO TRIM
^^REM\\ AND ! STATEMENTS WHEN THE FILE FORM OF THE COMMAND IS USED.
^THE SWITCHES /<LI AND /<CO MAY BE USED AS IN THE <CHAIN STATEMENT.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{RUN}
	{RUN "PROGRAM"}
	{10 RUN "PROG1"}
\\
.FILL
.SKIP
.X ^^CLEAR\\
.X ^FILE CLOSE
.HEADERLEVEL 1 <CLEAR
.BREAK
^THIS COMMAND CLEARS THE USER DATA AREA.
^IT CLOSES ALL USER FILES BEFORE DOING THE CLEAR OPERATION.
.SKIP
.X ^^SAVE\\
.X ^PROGRAM SAVE
.HEADERLEVEL 1 ^^SAVE _<STRING FILESPEC[/CO]> [N1][-N2][,N3...]\\
.BREAK
^PRIMARILY AN IMMEDIATE MODE COMMAND.
^IT MAKES A COPY OF THE PRESENT PROGRAM ON THE FILE NAMED IN
THE STRING FILESPEC (STRING VARIABLE OR STRING IN QUOTES).
^OPTIONAL LINE NUMBERS OR LINE NUMBER RANGES CAN BE INCLUDED.
.FG 1
^THE OPTIONAL SWITCH WILL PRODUCE A PSUEDO-COMPILED VERSION
WHICH CAN BE READ BACK WITH THE SAME SWITCH WITHOUT
RE-INTERPRETING THE CODE THUS SAVING A CONSIDERABLE AMOUNT
OF TIME FOR LONG PROGRAMS.
^THE DEFAULT EXTENSION WILL BE <BAC IF THE SWITCH IS INCLUDED.
.FG 1
^THE DEFAULT FILE SPECIFIER IS: ^^SY:PROGRAM.BAS\\
OR THE NAME, EXTENSION AND DEVICE IN THE LAST <OLD, <RUN,
<CHAIN OR <OVERLAY COMMAND.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{SAVE "PROGRAM"}
	{SAVE "LP:"}
	{SAVE "DK2:PROG.BAS"}
	{SAVE}
\\
.FILL
.SKIP
.X ^^OLD\\
.X ^PROGRAM RETRIEVE
.HEADERLEVEL 1 ^^OLD _<STRING FILESPEC[/RT][/CO]>\\
.BREAK
^THE ^^OLD\\ COMMAND READS IN A PREVIOUSLY SAVED OR EDITED PROGRAM
FROM THE FILE NAMED IN THE STRING FILESPEC (AS IN ^^SAVE\\).
^THE OPTIONAL SWITCH, WHEN SPECIFIED, CAUSES TRUNCATION OF
^^REM\\ AND ! STATEMENTS.
^THE DEFAULT FILE SPECIFIER IS: ^^SY:PROGRAM.BAS\\
^THE <CO SWITCH INDICATES THAT A COMPILED BASIC FILE IS TO BE
USED (DEFAULT EXTENSION <BAC).
.BREAK
^EXAMPLE:
.NOFILL
^^
	{OLD "PROG1"}
	{OLD "DK3:PROGRAM.BAS"}
\\
.FILL
.SKIP
.X ^^CHAIN\\
.X ^PROGRAM CHAIN
.HEADERLEVEL 1 ^^CHAIN _<STRING FILESPEC[/LI:VAL][/RT][/CO]>\\
.BREAK
^THE ^^CHAIN\\ COMMAND READS IN ANOTHER ^^BASIC\\ PROGRAM WHILE
PRESERVING VARIABLES AND OPEN FILES' ^^FCB\\'S.
^^GOSUB/RETURN\\ POINTERS, ^^FOR\\ LOOP CONTROL TABLES, USER ^^DEF\\INED
FUNCTIONS AND SCRATCH ITEMS ARE ALL DELETED FROM THE USER DATA AREA.
^THUS USER FUNCTIONS MUST BE REDEFINED IN ANY NEW PROGRAM MODULE.
.FG 1
^THE DEFAULT FILE SPECIFIER AND SWITCHES ARE THE SAME AS FOR THE 
^^OVERLAY\\ COMMAND WITH THE ADDITION OF THE /<LI SWITCH WHICH CAN SPECIFY
AN OPTIONAL LINE NUMBER TO CONTINUE EXECUTION.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{20 CHAIN "PROG2"}
\\
.FILL
.SKIP
.X ^^OVERLAY\\
.X ^PROGRAM OVERLAY
.HEADERLEVEL 1 ^^OVERLAY _<STRING FILESPEC [/LI:VAL][/RT][/CO]>\\
.BREAK
^THE ^^OVERLAY\\ COMMAND READS IN ADDITIONAL PROGRAM TEXT FROM THE SPECIFIED
FILE AND ADDS THEM TO THE EXISTING PROGRAM JUST AS THOUGH THEY WERE TYPED
FROM THE KEYBOARD: I.E. NEW STATEMENTS WITH THE SAME LINE NUMBER AS AN
EXISTING STATEMENT REPLACE THE EXISTING STATEMENT.
^THE SAME PRECAUTIONS REGARDING FUNCTION DEFINITIONS AND ^^DATA\\ STATEMENTS
DURING DEBUGGING SHOULD ALSO BE OBSERVED WHEN USING THE ^^OVERLAY\\
STATEMENT IN PROGRAM MODE.
.FG 1
^THE OPTIONAL SWITCH (/^L^I) IS SIGNIFICANT IN PROGRAM MODE ONLY AND CAN BE
USED TO SPECIFY THE LINE AT WHICH EXECUTION SHOULD RESUME.
^THE /<RT AND /<CO SWITCHES ARE THE SAME AS FOR THE ^^OLD\\ COMMAND.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{OVERLAY "PATCH1"}
	{100 OVERLAY "PATCH2.BAS/LI:500"}
\\
.FILL
.SKIP
.X ^^LIST\\
.X ^PROGRAM LIST
.HEADERLEVEL 1 ^^LIST [N1][-N2][,N3...]\\
.BREAK
^THIS IS PRIMARILY AN IMMEDIATE MODE COMMAND.
^WITH NO ARGUMENTS, THE WHOLE PROGRAM IS LISTED AT THE USER'S
TERMINAL.
^SINGLE ARGUMENTS SEPARATED BY COMMAS WILL LIST ONLY THE
LINE NUMBERS REQUESTED.
^TWO ARGUMENTS SEPARATED BY A DASH (MINUS) WILL LIST AN INCLUSIVE
LINE NUMBER RANGE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{LIST}
	{LIST 20}
	{LIST 50,100}
	{LIST 50-80,135,710-750}
\\
.FILL
.SKIP
.X ^^DELETE\\
.X ^PROGRAM LINE DELETE
.HEADERLEVEL 1 ^^DELETE N1[-N2][,N3...]\\
.BREAK
^THIS ALSO IS PRIMARILY AN IMMEDIATE MODE COMMAND.
^IT WILL DELETE INDIVIDUAL LINES WITH SINGLE PARAMETERS OR INCLUSIVE
RANGES WITH NUMBERS SEPARATED BY A DASH (MINUS).
^IF NO NUMBERS ARE SPECIFIED, THE WHOLE PROGRAM TEXT IS DELETED (BUT NOT
PROGRAM DATA - THIS MUST BE DONE WITH THE ^^CLEAR\\ COMMAND).
^IT CAN BE USED IN PROGRAM MODE ALSO, USUALLY TO DELETE A RANGE OF
LINE NUMBERS IN PREPARING TO <OVERLAY ANOTHER ROUTINE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{DELETE 30}
	{DELETE 50-70}
	{DELETE 10-40,60-80}
\\
.FILL
.S
.X <EXIT
.HEADERLEVEL 1 <EXIT
.BR
^THIS STATEMENT STOPS PROGRAM EXECUTION AND EXITS FROM <BASIC
TO THE <MCR.
^ALL FILES ARE CLOSED BEFORE EXIT.
^IT IS EQUIVALENT TO A <STOP FOLLOWED BY A _^^Z FROM THE KEYBOARD.
.BR
^EXAMPLE:
.NF
^^
	{1000 EXIT}
\\
.F
.SL
.X ^^STEP\\
.X ^SINGLE LINE EXECUTE
.HEADERLEVEL 1 ^^STEP [LINE _#]\\
.BR
^THIS STATEMENT ALLOWS ONE TO STEP THROUGH A PROGRAM ONE LINE AT
A TIME.
^THE OPTIONAL LINE NUMBER MAY BE USED TO START AT A DIFFERENT LINE.
^IF NO LINE NUMBER IS SPECIFIED, EXECUTION RESUMES AT THE LINE
FOLLOWING THE LAST STOP.
^NOTE THAT IF A BRANCH IS TAKEN THE LINE BEING EXECUTED,
THE PROGRAM WILL NOT STOP UNTIL THE NEXT LINE AFTER THE BRANCH.
^THE STOP USES THE SAME INTERNAL FACILITIES AS THE
_^^B BREAK FEATURE.
.BR
^EXAMPLE:
.NF
^^
	{STEP}
	{STEP 510}
\\
.F
.SL
.X ^^CON\\
.X ^PROGRAM CONTINUE
.HEADERLEVEL 1 ^^CON [LINE _#]\\
.BR
^THIS COMMAND ALLOWS ONE TO RESUME EXECUTION OF A PROGRAM
AFTER STOPPING IT FOR INTERACTIVE DE-BUGGING.
^WHEN USED WITH THE OPTIONAL LINE NUMBER, IT FUNCTIONS
JUST LIKE ^^GOTO\\
WITH THE EXCEPTION THAT THE NEXT AVAILABLE LINE AFTER THE ONE SPECIFIED
IS USED IF THERE IS NO EXACT MATCH.
^IF NO LINE NUMBER IS SPECIFIED, EXECUTION IS RESUMED AT THE LINE FOLLOWING
THE LAST STOP.
.BR
^EXAMPLE:
^^
.NF
	{CON}
	{CON 100}
\\
.F
.CHAPTER ^^PROGRAM STATEMENTS\\
^THE SUBSET OF COMMANDS LISTED IN THIS CHAPTER IS PRIMARILY USED TO
CONTROL THE FLOW OF PROGRAM EXECUTION, RESERVE
STORAGE AREA FOR VARIABLES, PERFORM ARITHMETIC CALCULATIONS, ETC.
.SKIP
.X ^^GOSUB\\
.X ^^GOTO\\
.HEADERLEVEL 1 <GOSUB N . . <GOTO N
.BREAK
^TRANSFERS PROGRAM CONTROL TO STATEMENT ^N, WHERE ^N CAN BE A
POSITIVE INTEGER CONSTANT OR AN EXPRESSION WHICH WILL BE TRUNCATED
TO AN INTEGER.
^NOTE THAT AN EXPRESSION WILL NOT PRODUCE CORRECT RESULTS IN THE
EVENT OF A RESEQUENCE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 GOTO 50}
	{20 GOSUB A(I)}
\\
.FILL
.SKIP
.X ^^ON _<EXP> GOTO _<LINE _# LIST>\\
.X ^^ON _<EXP> GOSUB _<LINE _# LIST>\\
.HEADERLEVEL 1 ^^ON _<EXP> GOTO _<GOSUB> _<LINE _# LIST>\\
.BR
^THIS STATEMENT TRANSFERS CONTROL TO THE ^NTH LINE NUMBER IN THE LIST.
^THE EXPRESSION IS EVALUATED AS A NORMAL <BASIC EXPRESSION (FLOATING
POINT) AND THEN TRUNCATED TO GET AN INTEGER VALUE.
^IF THIS VALUE DOES NOT CORRESPOND TO A LINE NUMBER IN THE LIST, A
<GOTO ERROR HAPPENS.
^THE TRANSFER IS HANDLED JUST AS IN THE STANDARD <GOTO AND <GOSUB
STATEMENTS.
.BR
^EXAMPLE:
.NF
^^
	{100 ON I GOTO 1000,1200,1400}
	{210 ON X-A(C1) GOSUB 2000,2100,3000}
\\
.F
.SKIP
.X ^^RETURN\\
.HEADERLEVEL 1 <RETURN
.BREAK
^RETURNS TO STATEMENT FOLLOWING ^^GOSUB\\ WHICH GOT YOU HERE.
^OTHER STATEMENTS MAY FOLLOW A GOSUB ON A LINE.
^IF THE LINE CONTAINING A <GOSUB IS INTERACTIVELY MODIFIED WHILE
THE SUBROUTINE IS IN THE MIDDLE OF EXECUTING, THE <GOSUB MUST
OCCUPY THE SAME RELATIVE STATEMENT POSITION IN THE LINE BEFORE
AND AFTER THE MODIFICATION: I.E. IT MUST BE THE FIRST OR THIRD
ETC. STATEMENT IN THE LINE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 RETURN}
\\
.FILL
.SKIP
.X ^^DIM\\
.X ^STRING VARIABLES
.HEADERLEVEL 1 <DIM
.BREAK
^DECLARES SIZE OF ARRAYS AND STRINGS.
^ALSO SPECIFIES STRINGS AS EITHER FIXED OR VARIABLE LENGTH.
^ARRAYS MAY HAVE ONE OR TWO SUBSCRIPTS.
.FG 1
^STRING LENGTHS ARE INDICATED IN SQUARE BRACKETS [#] WHICH ARE
FOLLOWED BY A '^V' IF THE STRING IS TO HAVE VARIABLE LENGTH.
^IN THE CASE OF A VARIABLE LENGTH STRING, THE LENGTH IS THE
MAXIMUM LENGTH WHICH THE STRING MAY ASSUME.
^A STRING UNDECLARED IN A <DIM STATEMENT IS ASSUMED TO BE
VARIBLE LENGTH WITH A MAX OF 15 CHARACTERS.
^FOR STRINGS DECLARED IN A <DIM STATEMENT, THE DEFAULTS ARE
15 CHARACTER LENGTH (OR MAX LENGTH) AND FIXED TYPE.
.FG 1
^ARRAYS HAVE A ZEROTH ELEMENT WHICH IS THE SAME AS THE UNSUBSCRIPTED
VARIABLE NAME: I.E. ^B(0) OR ^B(0,0) IS THE SAME AS ^B.
^UNLIKE OTHER VERSIONS OF ^^BASIC\\, ARRAYS DO NOT HAVE ANY
ASSUMED DIMENSIONS; THEY MUST BE DECLARED IF THEY ARE TO BE USED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 DIM A(5,5),B$[10]}
	{20 DIM C$[20]V(10,10),D$(5)}
\\
.FILL
.S
.X ^^DIM#_#\\
.X ^VIRTUAL ARRAYS
.HEADERLEVEL 1 ^^DIM#_#N,_<EXP>\\
^THIS STATEMENT DECLARES CERTAIN VARIABLES AS "VIRTUAL ARRAYS" AND DEFINES
THEIR ALLOCATION ON THE FILE WHOSE <LUN IS THE VALUE OF "EXP".
^A VIRTUAL ARRAY HAS ITS VALUES STORED ON A FILE AND MAINTAINS ONLY
A SMALL PART OF THE ARRAY IN MEMORY AT ANY ONE TIME (CURRENTLY 512 BYTES - 
1 DISK BLOCK).
^THE <DIM#_# STATEMENT ONLY DEFINES THE MAPPING OF THE ARRAY ONTO THE FILE.
^THE FILE ITSELF MUST BE OPENED VIA AN <OPEN STATEMENT USING THE </BL SWITCH.
^CONSEQUENTLY, SEVERAL <DIM#_# STATEMENTS MAY DEFINE SEVERAL MAPPINGS
OF DIFFERENT VARIABLES ONTO THE SAME FILE WITH AN EFFECT SIMILAR TO A
<FORTRAN <EQUIVALENCE STATEMENT.
.FG 1
^THE RULES FOR MAPPING FOLLOW <RSTS <BASIC-PLUS.
^ESSENTIALLY, NO ARRAY ELEMENT MAY CROSS BLOCK BOUNDARIES.
^THIS IMPLIES THAT VARIABLE SIZES MUST BE POWERS OF TWO.
^NUMERIC VARIABLES AUTOMATICALLY FULFILL THIS CONDITION.
^STRINGS ARE ALLOCATED THEIR SPECIFIED SIZE WHETHER FIXED OR VARIABLE.
^VARIABLE LENGTH STRINGS ARE NULL PADDED ON DISK, AND WHEN USED IN A
PROGRAM CONTEXT ARE AUTOMATICALLY TRIMMED TO THEIR SIZE WITHOUT
THE NULL PADDING.
^FIXED LENGTH VIRTUAL STRINGS, AS WITH STANDARD FIXED LENGTH STRINGS,
ARE BLANK PADDED.
^IF THE ALLOCATION OF A VARIABLE IN A <DIM#_# LIST WOULD CAUSE IT TO
CROSS BLOCK BOUNDARIES BECAUSE OF PREVIOUS ALLOCATIONS IN THE LIST,
IT IS STARTED AT THE NEXT DISK BOUNDARY.
^SUBSCRIPTS MAY RANGE UP TO 32767 AND STRING ELEMENTS UP TO 512
CHARACTERS (IN POWERS OF 2).
.BREAK
^EXAMPLE:
.NF
^^
	{20 DIM _#3,A(20,100),A$[256]V(5000)}
	{30 DIM _#3,B(20000),B$[128]V(10000)}
	{40 DIM _#7,X(100),Y(100),Z(200)}
\\
.F
.SKIP
.X ^^DEF\\
.X ^FUNCTION - USER
.X ^USER DEFINED FUNCTIONS
.HEADERLEVEL 1 <DEF
.BREAK
^ONE LINE FUNCTION DEFINITION.
^THE FUNCTION NAME IS FORMED WITH THE LETTERS ^F^N FOLLOWED BY ANY
LEGAL VARIABLE NAME.
E.G.: ^^FNA, FNX1, FNM$\\ ETC.
^DUMMY ARGUMENTS MAY BE ANY NUMERIC OR STRING VARIABLE WITH ANY
NUMBER OF ARGUMENTS SUBJECT TO FITTING ON ONE LINE.
^THE DEFINITION ITSELF MAY BE ANY LEGAL NUMERIC OR STRING EXPRESSION
INCLUDING SYSTEM AND OTHER USER FUNCTIONS.
.FG 1
^FUNCTION NAMES RETURNING STRING VALUES MUST END IN '$', THOSE
RETURNING NUMERIC VALUES MUST NOT.
^FUNCTIONS ARE RECURSIVE, I.E. THEY MAY USE THEMSELVES AS ARGUMENTS
IN THE FUNCTION CALL.
.SKIP
^FUNCTION DEFINITIONS CREATE AN INTERNAL POINTER TO THE ^^ASCII\\
TEXT TO THE RIGHT OF THE EQUAL SIGN.
^FOR THIS REASON THEY SHOULD BE PLACED NEAR THE BEGINNING OF THE
PROGRAM TO AVOID BEING MOVED DURING DEBUGGING RUNS BY INSERTIONS,
DELETIONS OR CHANGES TO LINES PRECEDING THE FUNCTION DEFINITION.
.SKIP
^FUNCTION DEFINITIONS ARE DELETED BY THE ^^CHAIN\\ STATEMENT.
.SKIP
^EXAMPLE:
.NOFILL
^^
	{30 DEF FNA1(A)=A^2}
	{40 DEF FNC$(X$)=X$+"ABC"}
	{50 DEF FNZ3$(X$,I)=SEG$(X$,I,LEN(X$))}
\\
.FILL
.SKIP
.X ^^LET\\
.X ^ARITHMETIC ASSIGNMENT
.HEADERLEVEL 1 <LET
.BREAK
^THIS IS THE NUMERIC ASSIGNMENT STATEMENT.
^IT IS ALSO ALLOWABLE FOR STRING ASSIGNMENT.
^THE WORD ITSELF IS OPTIONAL IN THIS VERSION OF ^^BASIC\\.
^A SINGLE VARIABLE NAME TO THE LEFT OF THE '=' IS GIVEN
THE VALUE OF THE NUMERIC OR STRING EXPRESSION TO THE RIGHT
OF THE EQUAL SIGN.
^VARIABLE AND EXPRESSION TYPES MUST MATCH.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{20 LET A=EXP(10.34)}
	{30 A$="ABC"+B$}
\\
.FILL
.SKIP
.X ^^IF\\
.X ^STRING COMPARISON
.HEADERLEVEL 1 <IF
.BREAK
.NOFILL
^FORMAT:
	^^IF _<LOGICAL EXPRESSION> THEN _<STMT>[ELSE _<LINE _#>][ELSE _<STMT>]
	IF _<LOGICAL EXPRESSION> THEN _<LINE _#> "   "
	IF _<LOGICAL EXPRESSION> GOTO _<LINE _#>\\ "  "
.FILL
^IF THE LOGICAL EXPRESSION IS TRUE (SEE ^LOGICAL ^EXPRESSIONS), THEN
THE LINE NUMBER FOLLOWING THE <THEN OR <GOTO IS BRANCHED TO OR ALL STATEMENTS
FOLLOWING <THEN UP TO THE END OF THE LINE OR AN <ELSE ARE EXECUTED.
.FG 1
^IF THE CONDITION IS FALSE, A MATCHING <ELSE IS SEARCHED FOR.
^IF FOUND, THE LINE NUMBER FOLLOWING THE <ELSE IS BRANCHED TO OR ALL
STATEMENTS FOLLOWING THE <ELSE TO THE END OF THE LINE OR THE NEXT
<ELSE ARE EXECUTED. ^IF NO MATCHING <ELSE IS FOUND, EXECUTION CONTINUES
ON THE FOLLOWING LINE.
.S
<IF\S AND <ELSE\S ARE PAIRED LIKE MATCHING PARENTHESES FROM THE INSIDE
OUT. ^THAT IS, AN <ELSE IS MATCHED WITH THE <IF MOST IMMEDIATELY
PRECEDING IT IN THE LINE WHICH DOES NOT ALREADY HAVE A MATCHING <ELSE.
^THIS IMPLEMENTATION OF <IF-<THEN-<ELSE IS INTENDED TO MATCH
<BASIC-<PLUS.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 IF A > B THEN STOP}
	{20 IF A$ _<> B$ GOTO 110 ELSE 500}
	{30 IF A >= 12.5 THEN 160 ELSE PRINT "A _< 12.5" : GOTO 300}
\\
.FILL
.SL
.X ^^REM\\
.X !
.SL
.HEADERLEVEL 1 <REM . . !
.BR
^THE ^^REM\\ARK STATEMENT IS USED TO INSERT COMMENTS INTO THE TEXT
OF THE ^^BASIC\\ PROGRAM.
^IT HAS TWO FORMS: ^^REM\\ AND !.
^ALL TEXT FOLLOWING THE ^^REM\\ OR ! WILL BE IGNORED BY THE
^^BASIC\\ INTERPRETER UP TO THE END OF A PHYSICAL LINE.
^NO OTHER STATEMENTS MAY FOLLOW ON THE SAME LINE AS THEY ARE TREATED
AS PART OF THE COMMENT.
.BR
^EXAMPLE:
.NF
^^
	{10 REM PROGRAM TO ADD ALL NUMBERS FROM 1 TO 10}
	{20 ! AND DEMONSTRATE USE OF REM AND !}
\\
.FILL
.SKIP
.X ^^READ\\
.X ^^DATA\\
.HEADERLEVEL 1 <READ . . <DATA
.BREAK
^THE ^^READ\\ STATEMENT INPUTS DATA FROM THE ^^DATA\\ STATEMENT.
^THE RULES FOR ^^INPUT\\ APPLY TO ^^READ\\, BUT ^^DATA\\ LISTS ARE
USED AS NEEDED WHEREAS ^^INPUT\\ INPUTS AN ENTIRE LINE FROM A FILE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 DATA 10.5,-76,1E7,FRANK}
	{50 READ A,B,C,D$}
\\
.FILL
.SKIP
.X ^^FOR\\
.HEADERLEVEL 1 <FOR
.BREAK
.NOFILL
^FORMAT:
	^^FOR _<VARIABLE> = _<EXP1> TO _<EXP2> [STEP _<EXP3>]\\
.FILL
^THIS STATEMENT SETS UP AND CONTROLS EXECUTION OF A ^^FOR-NEXT\\ LOOP.
^ANY NUMERIC EXPRESSIONS MAY BE USED.
^THE VARIABLE MUST BE, HOWEVER, A SIMPLE FLOATING VARIABLE
(NO SUBSCRIPT).
.FG 1
^THE STATEMENTS FOLLOWING THE ^^FOR\\ STATEMENT UNTIL THE ASSOCIATED
^^NEXT\\ STATEMENT COMPRISE THE LOOP.
^THE LOOP BEGINS WITH THE VARIABLE SET EQUAL TO ^^EXP1\\ AND
CONTINUES BY INCREMENTING THE VARIABLE BY ^^EXP3\\ (DEFAULTED TO ONE)
UNTIL IT REACHES OR PASSES THE VALUE OF ^^EXP2\\ (THEREFORE THE LOOP
MAY NOT BE EXECUTED AT ALL).
^FINAL VALUE OF THE VARIABLE IS ITS VALUE THE LAST TIME THROUGH THE
LOOP.
.NOTE
^CHANGING THE VALUE OF THE VARIABLE WITHIN THE LOOP WILL
AFFECT THE NUMBER OF TIMES THE LOOP IS EXECUTED.
.ENDNOTE
^EXAMPLE:
.NOFILL
^^
	{40 FOR I=1 TO 5.5 STEP .5}
	{100 FOR J1=-.1 TO -1.5 STEP -.1}
\\
.FILL
.SKIP
.X ^^NEXT\\
.HEADERLEVEL 1 <NEXT
.BREAK
.NOFILL
^FORMAT:
	^^NEXT _<VARIABLE>\\
.FILL
^THIS STATEMENT TERMINATES THE LOOP BEGUN BY THE 
IMMEDIATELY PRECEDING ^^FOR\\ STATEMENT
WITH THE SAME VARIABLE NAME.
^A CONCATENATED FORM OF TWO <NEXT STATEMENTS IS SHOWN IN THE SECOND
EXAMPLE. ^NOTE, HOWEVER THAT IT IS NOT POSSIBLE TO BRANCH TO THE
SECOND (IMPLIED) <NEXT (<NEXT#^J) WITHOUT ENCOUNTERING <NEXT#^I.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{70 NEXT I}
	{100 NEXT I,J}
\\
.FILL
.S
.X <BREAK
.HEADERLEVEL 1 <BREAK
.BR
^THIS COMMAND CAUSES ALL OUTPUT ACCUMULATED IN THE TERMINAL BUFFER TO
BE PRINTED IN WRITE-PASS-ALL MODE AND WITH NULL CARRIAGE CONTROL.
^ALL CARRIAGE CONTROL MUST BE SUPPLIED IN THE BUFFER BY THE PROGRAM.
^IN ORDER TO ACCUMULATE TEXT IN THE TERMINAL'S BUFFER, <PRINT
STATEMENTS WITH TRAILING COMMAS OR SEMICOLONS MUST BE USED.
^NOTE: ^EXECUTION OF THE <BREAK COMMAND DOES NOT AFFECT THE STATUS
OF FLAGS WHICH ARE SET OR CLEARED BY THE <SET COMMAND.
.BR
^EXAMPLE:
.NF
^^
	{110 PRINT "START TAPE INPUT";CHR$(17);}
	{120 BREAK}
\\
.F
.S
.X <SET <PROMPT
.X <SET <TRACE
.X <SET <READ-PASS-ALL
.X ^SET SYSTEM CONDITIONS
.X <PROMPT
.X <TRACE
.X <READ-PASS-ALL
.HEADERLEVEL 1 ^^SET PROMPT/TRACE/READ-PASS-ALL ON/OFF\\
.BR
^THIS STATEMENT IS USED TO SET OR CLEAR A NUMBER OF SYSTEM CONDITIONS.
^THE NUMBER OF CONDITIONS IS LIKELY TO INCREASE IN THE FUTURE AS
FUNCTIONALITY IS ADDED. ^CONDITIONS NOW SERVICED INCLUDE: <TRACE,
<PROMPT AND ^^READ-PASS-ALL\\. ^^SET TRACE\\ IS EQUIVALENT TO THE
<TRACE VERB AND SHOULD BE USED IN PREFERENCE TO IT BECAUSE THE <TRACE
VERB IS EXPECTED TO DISAPPEAR IN FUTURE RELEASES OF THIS INTERPRETER.
^THE <PROMPT CONDITION IS USED TO TURN THE <INPUT AND <INPUT <LINE
QUESTION MARK PROMPT ON OR OFF. ^THE NORMAL MODE OF PROCESSING IS <ON.
^THE <OFF MODE IS DESIGNED FOR SPECIAL SCREEN OR PAGE FORMATTING AND
MAY BE USED IN CONJUNCTION WITH THE <BREAK COMMAND.
.BR
^EXAMPLE:
.NF
^^
	{210 SET PROMPT OFF}
	{220 SET TRACE ON}
\\
.F
.SL
.X ^^ON ERROR GOTO\\
.HEADERLEVEL 1 ^^ON ERROR GOTO\\
.BR
^THIS STATEMENT SETS THE LINE NUMBER FOR A TRANSFER ON ANY TYPE
OF ERROR.
^IT DOES NOT CAUSE ANY BRANCHING WHEN IT ITSELF IS EXECUTED,
RATHER IT CHANGES THE PROCESSING OF ERRORS IN THE <BASIC INTERPRETER.
^IF THIS STATEMENT HAS BEEN PREVIOUSLY EXECUTED WITH A NON-ZERO
LINE NUMBER SPECIFIED, NO ERROR MESSAGE WILL BE PRINTED AND A
BRANCH TO THE SPECIFIED STATEMENT WILL BE MADE.
.FG 1
^NORMAL ERROR PROCESSING WILL BE RESTORED AFTER THE BRANCH IS MADE
OR BY EXECUTING THE STATEMENT WITH A ZERO LINE NUMBER.
^THUS AT LEAST ONE ^^ON ERROR GOTO\\ MUST FOLLOW THE LAST ERROR
AND PRECEDE THE NEXT ONE FOR USER ERROR HANDLING TO OCCUR.
.FG 1
^THIS PROCESSING IS DESIGNED TO MINIMIZE THE CHANCE OF AN
ENDLESS LOOP OCCURRING BECAUSE OF AN ERROR IN THE ERROR
HANDLING ROUTINE.
^PRECISE INFORMATION AS TO THE CAUSE OF THE ERROR CAN BE HAD
FROM THE FUNCTIONS <ERR, <ERL, <FCS DETAILED ELSEWHERE.
.BR
^EXAMPLES:
.NF
^^
	{100 ON ERROR GOTO 1500}
	{510 ON ERROR GOTO 0	! THIS RESTORES NORMAL ERROR HANDLING}
\\
.F
.SL
.X <SLEEP
.HEADERLEVEL 1 ^^SLEEP _<EXPRESSION>_<UNIT>\\
.BR
^THE <SLEEP COMMAND CAUSES THE EXECUTING PROGRAM TO PAUSE FOR
THE SPECIFIED AMOUNT OF TIME.
ANY VALID ARITHMETIC EXPRESSION MAY BE USED TO SPECIFY THE TIME
MAGNITUDE.
^HOWEVER, A NEGATIVE RESULT WILL GIVE AN ERROR AND ZERO WILL
BE TREATED AS A NO-OP.
^TRUNCATION OF THE FLOATING EXPRESSION VALUE WILL BE USED.
.FG 1
^THE UNIT OF TIME MAY BE SPECIFIED AS <TICKS, <SECONDS, <MINUTES,
<HOURS OR ANY ABBREVIATION OF THOSE WORDS WITH THE SAME FIRST LETTER.
^NO UNITS SPECIFICATION WILL DEFAULT TO <SECONDS.
.BR
^EXAMPLES:
.NF
^^
	{510 SLEEP 10 SECONDS}
	{105 SLEEP 2 M}
	{632 SLEEP 25}
\\
.F
.SL
.X <WAIT
.HEADERLEVEL 1 ^^WAIT _<EXPRESSION>_<UNIT>\\
^THE <WAIT COMMAND SETS PARAMETERS FOR THE TIMEOUT OF TERMINAL INPUT.
^THE FORMAT IS SIMILAR TO THE <SLEEP COMMAND.
^NOTE THAT NO EXPLICIT ACTION IS TAKEN ON EXECUTION OF THE <WAIT
COMMAND.
^IT IS USED ONLY TO SET THE LENGTH OF TIME TO WAIT FOR TERMINAL INPUT
BEFORE CAUSING A TIMEOUT ERROR TRAP.
.FG 1
^THE USER MAY CHECK FOR THE OCCURENCE OF A TIMEOUT ERROR BY USE OF THE
<ON <ERROR <GOTO
COMMAND AND THEN CHECK THE ERROR CODE, CURRENTLY 44. (DECIMAL.)
^APPROPRIATE ACTION MAY BE TAKEN AT THIS POINT (<EXIT FOR EXAMPLE).
.FG 1
^THE NO TIMEOUT CONDITION MAY BE RESTORED BY USING A 0 MAGNITUDE.
.BR
^EXAMPLES:
.NF
^^
	{400 WAIT 40 S :! ALL TERMINAL INPUT TO TIME OUT AFTER 40 S}
	{500 WAIT 0    :! RESTORE TO NO TIMEOUT CONDITION}
\\
.F
.SL
.X <PRIORITY
.HEADERLEVEL 1 <PRIORITY _<EXPRESSION>\\
.BR
^THE <PRIORITY COMMAND CAUSES THE INTERPRETER TO CHANGE ITS PRIORITY
TO THAT SPECIFIED IN THE FOLLOWING EXPRESSION.
^PRIORITIES UP TO 100 ARE ALLOWED.
.BR
^EXAMPLE
.NF
^^
	{500 PRIORITY 30}
\\
.F
.SKIP
.X <TRACE <ON AND <OFF
.HEADERLEVEL 1 ^^TRACE ON AND OFF\\
.BR
^THIS STATEMENT TURNS THE TRACE FEATURE ON AND OFF.
^WHEN THE TRACE IS ON, ALL TRANSFERS OUT OF THE NORMAL FLOW
OF NORMAL PROGRAM EXECUTION ARE PRINTED ON THE USER'S TERMINAL.
^THIS CAN BE USED IN EITHER IMMEDIATE MODE OR PROGRAM MODE
(FOR SELECTIVE TRACING).
.BR
^EXAMPLE:
.NF
^^
	{TRACE ON}
	READY
	{RUN}
OR
	{100 TRACE ON}
	{...}
	{200 TRACE OFF}
\\
.F
.CHAPTER ^^ARITHMETIC FUNCTIONS\\
^THE FUNCTIONS LISTED IN THIS CHAPTER ARE PRIMARILY ARITHMETIC IN NATURE.
^THEY RETURN ARITHMETIC VALUES OR CERTAIN SYSTEM VALUES SUCH AS THE
^DATE OR THE ^TIME.
.SL
.X <RND
.HEADERLEVEL 1 <RND
.BR
^THIS FUNCTION RETURNS A RANDOM NUMBER EVENLY DISTRIBUTED BETWEEN
0 AND 1.
^THE DUMMY ARGUMENT HAS NO EFFECT ON THE VALUE RETURNED.
^THE SEQUENCE OF NUMBERS RETURNED MAY BE CHANGED BY USING THE
<RANDOMIZE STATEMENT.
.BR
^EXAMPLE:
.NF
^^
	{120 X=RND(0)}
\\
.F
.SKIP
.X ^^RANDOMIZE\\
.HEADERLEVEL 1 <RANDOMIZE
.BREAK
^THIS STATEMENT RESETS THE RANDOM NUMBER GENERATOR TO A NEW STARTING
POINT.
^THE EFFECT OF THIS IS TO MAKE SUCCESSIVE RUNS OF THE SAME PROGRAM
RETURN DIFFERENT VALUES FOR THE ^^RND\\ FUNCTION.
^A PROGRAM SHOULD FIRST BE DEBUGGED WITHOUT THE ^^RANDOMIZE\\
STATEMENT AND THEN ADD IT FOR PRODUCTION USE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{50 RANDOMIZE}
\\
.FILL
.SKIP
.X ^^ABS\\
.X ^ABSOLUTE VALUE FUNCTION
.HEADERLEVEL 1 <ABS
.BREAK
^THIS FUNCTION RETURNS THE ABSOLUTE VALUE OF THE NUMERIC
EXPRESSION ARGUMENT.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=ABS(A1+5)}
\\
.FILL
.SKIP
.X ^^SGN\\
.X ^SIGN FUNCTION
.HEADERLEVEL 1 <SGN
.BREAK
+1 RETURNED IF ARGUMENT > 0; -1 IF ARGUMENT < 0;
0 RETURNED IF ARGUMENT = 0.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=SGN(A1)}
\\
.FILL
.SKIP
.X ^^INT\\
.X ^INTEGER FUNCTION
.HEADERLEVEL 1 <INT
.BREAK
^RETURNS GREATEST INTEGER IN THE ARGUMENT.
^NOTE: ^^INT(-1.5)=-2\\ ETC.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=INT(X)}
\\
.FILL
.SKIP
.X ^^LOG\\
.X ^LOGARITHM - NATURAL
.HEADERLEVEL 1 <LOG (NATURAL _& BASE 10)
<LOG
.BREAK
^RETURNS THE NATURAL LOG OF THE VALUE OF THE ARGUMENT EXPRESSION.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 A=LOG(X)}
\\
.FILL
.S
.X <LOG10
.X ^LOGARITHM - BASE TEN
<LOG10
.BREAK
^RETURNS THE BASE TEN (COMMON) LOG OF THE VALUE OF THE ARGUMENT
EXPRESSION
.BREAK
^EXAMPLE:
.NF
^^
	{50 B=LOG10(X)}
\\
.F
.SKIP
.X ^^EXP\\
.X ^EXPONENTIAL FUNCTION
.HEADERLEVEL 1 <EXP
.BREAK
^RETURNS THE BASE E EXPONENTIAL OF THE ARGUMENT VALUE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=EXP(X)}
\\
.FILL
.SKIP
.X ^^SIN\\
.X ^^COS\\
.X ^SINE FUNCTION
.X ^COSINE FUNCTION
.HEADERLEVEL 1 <SIN <COS
.BREAK
^THESE FUNCTIONS RETURN THE SINE AND COSINE FUNCTIONS OF THE
ARGUMENT VALUES.
^THE INPUT ARGUMENT IS IN RADIANS.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{20 S=SIN(X)}
	{30 C=COS(Y)}
\\
.FILL
.SKIP
.X ^^ATN\\
.X ^ARCTANGENT FUNCTION
.HEADERLEVEL 1 <ATN
.BREAK
^RETURNS THE ARCTANGENT FUNCTION OF THE ARGUMENT VALUE.
^THE RETURNED VALUE IS IN RADIANS.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=ATN(X)}
\\
.FILL
.SKIP
.X ^^SQR\\
.X ^SQUARE ROOT FUNCTION
.HEADERLEVEL 1 <SQR
.BREAK
^RETURNS THE SQUARE ROOT OF THE ARGUMENT VALUE.
^IF THE ARGUMENT VALUE IS NEGATIVE, AN ERROR IS GIVEN.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{20 S=SQR(X)}
\\
.FILL
.SKIP
.X ^^NRC\\
.X ^RECORD COUNT FUNCTION
.X ^NUMBER OF RECORDS FUNCTION
.HEADERLEVEL 1 <NRC
.BREAK
^THIS FUNCTION CALCULATES THE NUMBER OF RECORDS IN THE
FILE NUMBER WHICH IS SPECIFIED IN THE ARGUMENT.
^THE FILE MUST BE A FIXED LENGTH RECORD TYPE.
^A -1 RETURNED INDICATES A NON-EXISTENT ^^FDB\\.
^A -2 RETURNED INDICATES VARIABLE LENGTH RECORDS.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=NRC(4)}
\\
.FILL
.SL
.X <ERR
.X <ERL
.X <FCS
.X ^ERROR CODE FUNCTIONS
.HEADERLEVEL 1 <ERR . . <ERL . . <FCS
.BR
^THESE FUNCTIONS RETURN RESPECTIVELY: THE NUMBER OF THE LAST ERROR,
THE LINE NUMBER OF THE LAST ERROR, AND THE <FCS ERROR CODE (NEGATIVE)
FOR THE LAST <FILES-11 RELATED ERROR.
^AN ARGUMENT FOR THE FUNCTION MUST BE INCLUDED ATLHOUGH IT WILL
USUALLY BE ZERO.
^IF A NON-ZERO ARGUMENT IS USED, IT WILL BE TREATED AS A WORD
OFFSET FROM THE INTERPRETER LOCATION CONTAINING THE NORMAL
INFORMATION FOR THAT FUNCTION.
^THUS A NON-ZERO OFFSET SHOULD ONLY BE USED IN CONJUNCTION WITH
A MAP AND ASSEMBLER LISTING.
.BR
^EXAMPLE:
.NF
^^
	{100 A=ERR(0)}
	{110 B=FCS(0)}
	{120 CON ERL(1)}
\\
.F
.SL
.X <COR
.X ^FREE CORE FUNCTION
.HEADERLEVEL 1 <COR
.BR
^THIS FUNCTION RETURNS THE FREE CORE (IN BYTES) MINUS THE VALUE
OF THE ARGUMENT.
.BR
^EXAMPLE:
.NF
^^
	{100 A=COR(255)}
\\
.F
.SKIP
.X ^^DAT$\\
.X ^DATE FUNCTION
.HEADERLEVEL 1 <DAT$
.BREAK
^AN 8 CHARACTER STRING IS RETURNED CONTAINING THE DATE
IN THE FORM ^^MO/DA/YR\\.
IF THE ARGUMENT IS ABSENT OR A SINGLE CHARACTER ZERO, THE SYSTEM DATE (TODAY'S
DATE HOPEFULLY!) IS RETURNED. ^IF THE ARGUMENT IS A POSITIVE VALUE,
THE NUMBER IS INTERPRETED AS THE DAY OF THE CENTURY, AND A
CORRESPONDING DATE STRING IS RETURNED. ^THE POSITIVE ARGUMENT
IS INTERPRETED MODULO 36524 (THE NUMBER OF DAYS IN A CENTURY).
^IF THE ARGUMENT IS A ZERO OR NEGATIVE VALUE (OTHER THAN A SINGLE
CHARACTER '0'), THEN A NULL STRING IS RETURNED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{50 A$=DAT$(0) : ! RETURN SYSTEM DATE}
	{60 PRINT DAT$(12752)}
	{70 A$=DAT$()  : ! RETURN SYSTEM DATE}
\\
.FILL
.SKIP
.X ^^DDAT$\\
.X <DEC STANDARD DATE FUNCTION
.HEADERLEVEL 1 <DDAT$
.BREAK
^THIS FUNCTION RETURNS A STRING CONTAINING THE <DEC
STANDARD DATE IN THE FORM: <DD-MMM-YY.
^THE STRING MAY BE EITHER 8 OR 9 CHARS DEPENDING ON THE
NUMBER OF DIGITS IN THE DAY.
^THE ARGUMENT IS INTERPRETED IN THE SAME WAY AS IN THE
<DAT$ FUNCTION.
.BREAK
^EXAMPLE:
.NF
^^
	{40 A$=DDAT$(0)}
\\
.F
.SKIP
.X ^^TIM$\\
.X ^TIME FUNCTION
.HEADERLEVEL 1 <TIM$
.BREAK
^RETURNS TIME IN AN 8 CHARACTER STRING IN THE FORM ^^HR:MN:SC\\.
^IF THE ARGUMENT IS ABSENT OR A SINGLE CHARACTER ZERO, THE SYSTEM
TIME IS RETURNED.
^OTHERWISE, THE ARGUMENT IS EVALUATED. ^IF NEGATIVE, A NULL
STRING IS RETURNED; IF ZERO OR POSITIVE, THE NUMBER IS INTERPRETED
AS THE NUMBER OF SECONDS SINCE MIDNIGHT AND THE CORRESPONDING
TIME IS RETURNED AS A STRING. ^THE NUMBER IS INTERPRETED MODULO
ONE DAY WORTH OF SECONDS.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 A$=TIM$(0)}
	{40 A$=TIM$()  : !RETURN SYSTEM TIME}
	{50 A$=TIM$(A-B) : ! RETURN TIME OF DAY CORRESPONDING TO}
			  ! A-B SECONDS SINCE MIDNIGHT
\\
.FILL
.S
.X <DCEN
.X ^DAY OF CENTURY FUNCTION
.X ^DATE VALIDITY CHECK
.HEADERLEVEL 1 <DCEN
.BR
^THIS FUNCTION ACCEPTS A SINGLE STRING DATE ARGUMENT AND RETURNS A
NUMBER WHICH IS THE DAY OF THE CENTURY. ^THE DATE ARGUMENT MAY BE
THE COMMON SLASH NOTATION OF <MM/DD/YY, THE <DEC STANDARD NOTATION
OF <DD-MMM-YY OR THE UNDELIMITED FORM OF <MMDDYY. ^THE RESULTING
NUMBER IS THE NUMBER OF THE DAY IN THE CENTURY WITH 1 CORRESPONDING
TO 1-^JAN-00, AND 36524 CORRESPONDING TO 31-^DEC-99. ^THIS NUMBER
IS THUS SUITABLE FOR CALCULATING DIFFERENCES BETWEEN TWO DATES. ^A
THOROUGH CHECK IS MADE OF THE DATE STRING BEFORE THE CONVERSION AND
AN ERROR CODE WILL BE RETURNED INSTEAD OF THE DAY OF THE CENTURY IN
CASE OF AN ERROR. ^THEREFORE THIS FUNCTION MAY BE USED TO VERIFY DATES
WHICH ARE INPUT FROM A USER PROGRAM. ^THIS ROUTINE IS PROGRAMMED TO
ACCOUNT FOR 24 LEAP YEARS PER CENTURY, OMITTING A LEAP YEAR DURING
THE '00' YEAR. ^THE ERROR CODES RETURNED ARE AS FOLLOWS:
.NF
	 0 = ^NULL STRING SUPPLIED
	-1 = ^BAD DATE FORMAT
	-2 = ^BAD DAY OF MONTH
	-3 = ^BAD MONTH (NOT IN RANGE 1-12)
	-4 = ^BAD YEAR  (NOT IN RANGE 0-99)
^EXAMPLES:
^^
	{150 A=DCEN("12/15/46")}
	{160 B=DCEN("5-AUG-72")}
	{170 C=DCEN(DDAT$(0))}
	{180 D=DCEN("121546")}
\\
.F
.S
.X <SEC
.X ^NUMBER OF SECONDS FROM TIME
.X ^TIME STRING VALIDITY CHECK
.HEADERLEVEL 1 <SEC
.BR
^THIS FUNCTION ACCEPTS A SINGLE STRING TIME ARGUMENT AND RETURNS
A NUMBER WHICH IS THE NUMBER OF SECONDS SINCE MIDNIGHT. ^THE TIME
STRING MUST BE IN THE FORM <HH:MM:SS IN 24 HOUR NOTATION. ^THE
STRING IS CHECKED FOR VALIDITY AND IF VALID, A POSITIVE (OR ZERO)
NUMERIC VALUE IS RETURNED. ^IF AN ERROR IS DETECTED, A NEGATIVE
OR ZERO VALUE IS RETURNED AS FOLLOWS:
.NF
	 0 = ^NULL STRING ARGUMENT (OR 00:00:00)
	-1 = ^BAD TIME FORMAT
	-2 = ^BAD SECONDS
	-3 = ^BAD MINUTES
	-4 = ^BAD HOURS
^EXAMPLES:
^^
	{210 A=SEC("12:05:31")}
	{220 B=SEC(A$)}
\\
.F
.CHAPTER ^^STRING FUNCTIONS\\
^THE FUNCTIONS LISTED IN THIS CHAPTER ARE PRIMARILY CHARACTER STRING
ORIENTED. ^THEY PROVIDE WIDE CAPABILITY FOR EXAMINING AND ALTERING
VARIABLES WHICH CONTAIN CHARACTER STRINGS, AND FOR CONVERSION FROM/TO
OTHER DATA FORMATS.
.SKIP
.X ^^INX\\
.X ^^POS\\
.X ^INDEX STRING FUNCTION
.X ^POSITION STRING FUNCTION
.HEADERLEVEL 1 <INX . . <POS
.BREAK
.NOFILL
^FORMAT:
	^^POS(STRING1,STRING2 [,P1] [,P2])\\
.FILL
^THIS FUNCTION COMPUTES THE POSITION OF ^^STRING2\\ IN ^^STRING1\\ STARTING
AT OPTIONAL POSITION ^P1 (^P1 ASSUMED TO BE 1 IF NOT SPECIFIED).
^A SECOND OPTIONAL PARAMETER ^P2 SPECIFIES THE FINAL CHARACTER POSITION.
^IF IT IS NOT SPECIFIED, IT IS ASSUMED TO BE THE END OF THE FIRST STRING.
^^INX\\ AND ^^POS\\ ARE IDENTICAL.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=POS("ABC","B")}
	{20 X=POS(A1$,A2$,5,7)}
\\
.FILL
.SKIP
.X ^^LEN\\
.X ^LENGTH OF STRING FUNCTION
.HEADERLEVEL 1 <LEN
.BREAK
^THIS FUNCTION COMPUTES THE LENGTH OF A SINGLE STRING EXPRESSION
ARGUMENT.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 X=LEN(A$)}
\\
.FILL
.SKIP
.X ^^VAL\\
.X ^VALUE OF STRING FUNCTION
.X ^NUMERIC VALUE OF STRING
.HEADERLEVEL 1 <VAL
.BREAK
^THIS FUNCTION TAKES AN ^^ASCII\\ STRING CONTAINING A LEGAL 
NUMERIC EXPRESSION AND RETURNS A FLOATING POINT VALUE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=VAL(A$)}
\\
.FILL
.SKIP
.X ^^OCT\\
.X ^OCTAL VALUE OF STRING
.HEADERLEVEL 1 <OCT
.BREAK
^THIS FUNCTION TAKES AN ^^ASCII\\ STRING CONTAINING A LEGAL
OCTAL INTEGER REPRESENTATION AND RETURNS A FLOATING POINT VALUE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A=OCT("1777")}
\\
.FILL
.SKIP
.X ^^AR5\\
.X ^ASCII TO <RAD50 CONVERSION FUNCTION
.HEADERLEVEL 1 <AR5
.BREAK
^THIS FUNCTION RETURNS A NUMERIC VALUE CORRESPONDING TO THE
<DEC <RAD50 CONVERSION OF THE FIRST THREE CHARACTERS OF THE
ARGUMENT STRING. ^IF LESS THAN THREE CHARACTERS ARE SUPPLIED,
THE RESULT IS AS IF THE INPUT WERE BLANK PADDED AT THE END.
^ALL LEGAL <RAD50 CHARACTERS INCLUDING BLANK AND PERIOD ARE
CONVERTED.
.BREAK
^EXAMPLE:
.NF
^^
	{100 A%=AR5("ABC")}
	{110 B1=AR5(A$+B$)}
\\
.F
.SKIP
.X ^^ASC\\
.X ^ASCII VALUE OF CHARACTER
.HEADERLEVEL 1 <ASC
.BREAK
^THIS FUNCTION RETURNS THE NUMERIC VALUE OF THE FIRST ^^ASCII\\ CHARACTER
IN THE STRING ARGUMENT.
^FOR A NULL STRING, 0 IS RETURNED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 I=ASC("A")}
\\
.FILL
.SKIP
.X ^^CHR$\\
.X ^CHARACTER FROM ^ASCII VALUE FUNCTION
.HEADERLEVEL 1 <CHR$
.BREAK
^ROUTINE TO RETURN A ONE CHARACTER STRING CORRESPONDING TO A NUMERIC
^^ASCII\\ VALUE.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 LET A$=CHR$(65)}
\\
.FILL
.SKIP
.X ^^SEG$\\
.X ^^SBS$\\
.X ^^RIGHT\\
.X ^^LEFT\\
.X <MID
.X ^SUBSTRING FUNCTIONS
.HEADERLEVEL 1 <SEG$ <SBS$ <RIGHT <LEFT <MID
.BREAK
.NOFILL
^FORMAT:
	^^SEG$(STRING,A[,B])
	SBS$(STRING,A[,B])
	MID(STRING,A,[B])
	RIGHT(STRING,N)
	LEFT(STRING,N)\\
.FILL
^WHERE '^^STRING\\' IS A LEGAL STRING EXPRESSION AND ^A IS THE FIRST
CHARACTER IN THE STRING TO BE SELECTED. ^IN ^^SEG$\\, ^B IS THE LAST
CHARACTER TO BE INCLUDED IN THE OUTPUT STRING; IN ^^SBS$\\, IT IS THE
NUMBER OF CHARACTERS TO INCLUDE. ^IF NOT SPECIFIED IN EITHER CASE
ALL CHARACTERS TO THE END OF THE STRING ARE INCLUDED.
^A NULL STRING IS RETURNED WHEN THE FIRST CHARACTER POSITION IS
NOT WITHIN THE SOURCE STRING.
^WHEN THE ENDING POSITION OR LENGTH PLACES ONE BEYOND THE END OF
THE SOURCE STRING, ALL CHARACTERS TO THE END ARE INCLUDED WITH NO
BLANK FILL.
^IF THE FIRST POSITION IS AFTER THE FINAL, A NULL STRING IS RETURNED.
^IF ^A IS LESS THAN 1 A NULL STRING IS RETURNED.
^IF ^B PLACES THE FINAL CHARACTER POSITION PAST THE END OF THE STRING,
IT IS AS THOUGH THE ENDING POSITION WAS SPECIFIED.
.SKIP
<RIGHT <LEFT AND <MID ARE PROVIDED FOR COMPATIBILITY WITH OTHER VERSIONS
OF <BASIC (IN PARTICULAR <RSTS <BASIC-PLUS).
^NOTE THAT THE NAMES ARE NOT FOLLOWED BY '$' EVEN THOUGH THE RESULTS
ARE STRING VALUES.
^THESE FUNCTIONS RETURN THE RIGHT-MOST OR LEFT MOST <N CHARACTERS
OF THE STRING RESPECTIVELY. <MID RETURNS <B CHARACTERS, STARTING AT
POSITION <A, AND IS THUS A SYNONYM FOR <SBS$. ^NOTE THAT SOME <BASIC
<RIGHT FUNCTIONS RETURN THE <N THRU END CHARACTERS OF THE STRING. ^IF
PROGRAMS EXPECT THIS ACTION, THE <RIGHT(N) FUNCTION SHOULD BE REPLACED
BY A <SBS$(N) FUNCTION.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 A$=SEG$(B$,1,5)}
	{30 X$=SBS$(Y$,6)}
\\
.FILL
.SKIP
.X ^^PIECE$\\
.X ^PIECE OF STRING BY DELIMITER
.HEADERLEVEL 1 <PIECE$
.BREAK
.NF
^FORMAT:
	^^PIECE$(STRING1,STRING2,N1 [,N2])\\
.F
<PIECE$ INSPECTS A SPECIFIED STRING (<STRING1) AND TAKES
FROM IT THAT SUBSTRING WHICH LIES BETWEEN TWO SPECIFIED
OCCURRENCES OF A PARTICULAR DIVIDING STRING (<STRING2).
^THE RESULTING SUBSTRING BEGINS IMMEDIATELY AFTER THE <N1
MINUS ONE OCCURRENCE OF THE DIVIDING STRING AND ENDS
IMMEDIATELY BEFORE THE ^N2ND OCCURRENCE (OR ^N1ST IF ^N2
IS UNSPECIFIED).
.BREAK
^EXAMPLE:
.NF
^^
	{110 M$=PIECE$("12/1/77","/",1) :! EXTRACT MONTH FROM STRING}
	{120 A$=PIECE$("12/1/77","/",1,2) :! EXTRACT MONTH AND DAY}
\\
.F
.SKIP
.X ^^STR$\\
.X ^NUMERIC TO CHARACTER STRING
.HEADERLEVEL 1 <STR$
.BREAK
^NUMERIC TO CHARACTER STRING CONVERSION. (^NO LEADING OR TRAILING BLANKS.)
^THE ^ASCII STRING REPRESENTS THE VALUE OF THE ARGUMENT.
.NOFILL
^FORMAT:
	^^STR$(X)\\
.FILL
^WHERE '^X' IS ANY LEGAL NUMERIC EXPRESSION.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 A$=STR$(EXP(X)+1.4)}
\\
.FILL
.SKIP
.X ^^TRM$\\
.X ^^LTR$\\
.X ^BLANK TRIM FUNCTIONS
.HEADERLEVEL 1 <LTR$ <TRM$
.BREAK
^LEADING AND TRAILING BLANK TRIM FUNCTIONS.
^THE RESULTING STRING IS THE ARGUMENT STRING WITHOUT LEADING BLANKS
FOR ^^LTR$\\ OR WITHOUT TRAILING BLANKS FOR ^^TRM$\\.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 A$=LTR$(A$)}
	{40 B$=TRM$(C$)}
\\
.FILL
.SKIP
.X ^^OCT$\\
.X ^^OCS$\\
.X ^OCTAL TO STRING FUNCTIONS
.HEADERLEVEL 1 <OCT$ <OCS$
.BREAK
^A SINGLE NUMERIC ARGUMENT IS CONVERTED TO ^^ASCII\\ REPRESENTATION
OF AN OCTAL INTEGER.
^THE NUMERIC EXPRESSION IS EVALUATED AND TRUNCATED TO AN INTEGER
PRIOR TO CONVERSION.
^^OCT$\\ PRODUCES AN UNSIGNED STRING, WHILE ^^OCS$\\ PRODUCES A
SIGNED STRING.
^MAGNITUDES ARE LIMITED TO THOSE REPRESENTABLE IN ONE ^^PDP-11\\ WORD.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{40 PRINT OCS$(-53)}
	{50 PRINT OCT$(I*16)}
\\
.FILL
.SKIP
.X <R5A$
.X <RAD50 TO <ASCII CONVERSION FUNCTION
.HEADERLEVEL 1 <R5A$
.B
^THE <RAD50 SOURCE VALUE (VALUE RANGE OF ONE INTEGER WORD) IS
CONVERTED TO A 3 CHARACTER STRING.
.B
^EXAMPLE:
.NF
^^
	{110 A$=R5A$(A)}
	{120 B$=R5A$(X%)}
\\
.F
.S
.X <FRMT$
.X ^NUMERIC TO STRING FORMAT FUNCTION
.HEADERLEVEL 1 <FRMT$(X,W[,D])
.BR
^THIS FUNCTION CREATES A STRING FROM A NUMBER ALLOWING CONTROL OVER THE
TOTAL NUMBER OF DIGITS AND THE
NUMBER OF DIGITS TO THE RIGHT OF THE DECIMAL POINT. ^THE VALUE TO BE
CONVERTED IS ^X, THE NUMBER OF TOTAL DIGITS (INCLUDING SIGN AND DECIMAL POINT)
IS ^W AND THE NUMBER OF DIGITS TO THE RIGHT OF THE DECIMAL
POINT IS ^D. ^IF ^D IS UNSPECIFIED, THEN THE NUMBER PRODUCED IS AN
INTEGER WITH NO DECIMAL POINT. ^IF ^D IS ZERO, THEN THE NUMBER PRODUCED
WILL HAVE A DECIMAL POINT BUT NO NUMBERS TO THE RIGHT. ^IF A NEGATIVE
NUMBER IS GIVEN FOR ^D, THEN THE OUTPUT WILL BE FILLED WITH ^W ASTERISKS
UNLESS ^W IS ZERO OR LESS. ^IF ^W IS LESS THAN OR EQUAL ZERO, IN ANY CASE
THEN A NULL STRING WILL BE RETURNED.
^IF ^W IS POSITIVE NON-ZERO AND UNABLE TO FIT THE NUMBER,
A STRING OF ^W ASTERISKS WILL BE RETURNED.
^NOTE THAT
MEANINGLESS DIGITS WILL BE PRODUCED IF MORE THAN 6 OR 7 ARE ASKED FOR.
^IF ONLY SIGNIFICANT DIGITS ARE WANTED, USE <STR$.
^NUMBERS ARE ROUNDED FOR PRINTOUT.
.BR
^EXAMPLE:
.NF
^^
	{130 A$=FRMT$(A+6,5,2)}
	{140 B$=FRMT$(12.75+Z1,7)}
\\
.F
.SKIP
.X ^^RJS$\\
.X ^^LJS$\\
.X ^RIGHT JUSTIFY FUNCTION
.HEADERLEVEL 1 <RJS$ . . <LJS$
.BREAK
.NOFILL
^FORMAT:
	^^RJS$(B$,I)\\
	^^LJS$(B$,I)\\
.FILL
^WHERE ^I IS THE LENGTH OF THE RETURNED STRING WITH ^B$ RIGHT
OR LEFT
JUSTIFIED IN IT AND WITH LEADING OR TRAILING BLANK FILL 
IF NECESSARY.
^IF ^B$ IS LONGER THAN ^I CHARACTERS, THEN THE RIGHTMOST
OR LEFTMOST ^I
CHARACTERS WILL BE RETURNED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{40 A$=RJS$(B$,9)}
	{70 A$=LJS$(B$,5)}
\\
.FILL
.SKIP
.X <SPACE$
.X <STRING$
.HEADERLEVEL 1 <SPACE$ . . <STRING$
.BREAK
.NF
^FORMAT
	^^SPACE$(I)\\
	^^STRING$(C$,I)\\
.F
^WHERE ^I IS THE LENGTH OF THE STRING TO BE CREATED.
^IN THE CASE OF <SPACE$, A STRING OF BLANKS IS CREATED.
^FOR <STRING$, A STRING OF CHARACTERS MATCHING THE FIRST
CHARACTER OF ^C$ IS CREATED.
^IF ^I IS ZERO OR NEGATIVE, A NULL STRING IS RETURNED.
.BREAK
^EXAMPLES:
.NF
^^
	{120 A$=SPACE$(40)}
	{130 B$=STRING$("-",40)}
\\
.F
.SKIP
.X ^^TAB\\
.X ^PRINT TAB FUNCTION
.HEADERLEVEL 1 <TAB
.BREAK
^THE ^^TAB\\ FUNCTION IS USED ONLY IN THE PRINT STATEMENT TO SPACE
TO A GIVEN COLUMN (THE VALUE OF THE NUMERIC ARGUMENT).
^THE COLUMN SPECIFIED IS THE ONE IN WHICH SUBSEQUENT PRINTING WILL
BEGIN.
^COLUMNS ARE NUMBERED STARTING WITH 1.
^IF THE SPECIFIED COLUMN IS GREATER THAN THE WIDTH OF THE DEVICE BEING
PRINTED ON, THE TAB IS CALCULATED MODULO THE DEVICE WIDTH.
^IF THE SPECIFIED COLUMN IS LESS THAN THE CURRENT PRINT POSITION, THE
FUNCTION IS IGNORED.
^^TAB\\ IS IGNORED ON BINARY OUTPUT FILES.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 PRINT A;TAB(20);A$}
\\
.FILL
.CHAPTER ^^I/O _& FILE MANIPULATION\\
^THE COMMANDS LISTED IN THIS CHAPTER ARE PRIMARILY CONCERNED WITH
^INPUT AND ^OUTPUT. ^THEY PROVIDE THE CAPABILITY OF OPENING FILES,
READING/WRITING DATA IN VARIOUS FORMATS, AND CLOSING THE FILES WHEN DONE.
.SKIP
.X ^^RESTORE\\
.X ^FILE RESTORE
.HEADERLEVEL 1 <RESTORE
.BREAK
^RESETS DATA POINTER TO START OF DATA STATEMENTS.
^FOR FILES, THE ^^RESTORE\\ STATEMENT MAY BE FOLLOWED BY A _#
SIGN AND AN ARITHMETIC EXPRESSION GIVING THE FILE NUMBER.
^A SEQUENTIAL FILE OPEN FOR READ ONLY WILL BE RESET TO THE
START.
^TO READ A SEQUENTIAL FILE CURRENTLY BEING WRITTEN, IT IS NECESSARY
TO CLOSE AND THEN RE-OPEN FOR READ.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{10 RESTORE}
\\
.FILL
.SKIP
.X ^^PRINT\\
.X ^BINARY OUTPUT
.X ^RANDOM ACCESS ^I/^O
.HEADERLEVEL 1 <PRINT
.BREAK
^PRINT STATEMENT.
.NOFILL
^FORMAT:
	^^PRINT [_#N,]V1,V2,V3\\ ETC.
OR
	^^PRINT _#N@R,V1,V2,V3\\ ETC.
.FILL
^WHERE ^N IS AN OPTIONAL FILE NUMBER AND ^V1, ^V2, ^V3, ETC.
ARE ANY LEGAL NUMERIC OR STRING EXPRESSION.
^IN THE SECOND FORM ^R IS A RANDOM ACCESS RECORD NUMBER EXPRESSION.
^IT MAY HAVE ANY VALUE UP TO THE MAXIMUM ALLOWED IN A DOUBLE
PRECISION SIGNED INTEGER.
^FLOATING POINT VALUES ARE TRUNCATED BEFORE USE.
^THE FILE ^N MUST HAVE BEEN OPENED FOR RANDOM ACCESS VIA THE
^^/RN\\ SWITCH IN THE ^^OPEN\\ STATEMENT.
.SL
^WHEN EXPRESSIONS ARE SEPARATED BY COMMAS, RESULTS ARE PRINTED
IN FIELDS OF 14 CHARACTERS EACH.
^WHEN EXPRESSIONS ARE SEPARATED BY SEMICOLONS, RESULTS ARE PRINTED
NEXT TO EACH OTHER WITHOUT ANY SPACES ADDED.
^A TRAILING SEMICOLON WILL SUPPRESS ^^_<CR>_<LF>\\.
^WHEN PRINTING WITH COMMA SEPARATION, AS MANY FIELDS ARE ALLOWED AS
CAN FIT ON THE PRINTING DEVICE.
^NOTE THAT NUMERIC VALUES, WHEN CONVERTED IN A ^^PRINT\\ STATEMENT
NORMALLY HAVE A SPACE AT EACH END.
^TO AVOID THIS, USE THE ^^STR$\\ FUNCTION.
.SKIP
^ON BINARY FILES, THE FOLLOWING CONDITIONS HOLD: ^^TAB\\ IS IGNORED,
NO "FIELD" JUSTIFICATION IS PERFORMED AND ALL DATA LIST ITEMS MUST FIT
INTO THE EXISTING BUFFER.
^FLOATING VALUES ARE STORED AS FOUR CONSECUTIVE BYTES WHICH ARE NOT
WORD ALIGNED.
^STRINGS AND NUMERIC VALUES ARE PACKED TOGETHER AND MAY BE COMBINED IN
ANY ORDER.
^IT IS UP TO THE USER TO KEEP TRACK OF THE INTERNAL STORAGE ARRANGEMENT
FOR FUTURE USE WITH ^^INPUT\\ OR OTHER NON-^^BASIC\\ PROGRAMS.
.SL
^A SYNONYM FOR ^^PRINT\\ IS "?" PRIMARILY FOR CONVENIENCE IN IMMEDIATE
MODE USE.
.SL
^EXAMPLE:
.NOFILL
^^
	{50 PRINT A,3.5,"HELLO";A$}
	{60 PRINT _#3,EXP(.5);X^Y;}
\\
.FILL
.TP 6
.SKIP
.X ^^INPUT\\
.X ^BINARY INPUT
.X ^RANDOM ACCESS ^I/^O
.HEADERLEVEL 1 <INPUT
.BREAK
.NOFILL
^FORMAT:
	^^INPUT [_#N,] V1,V2,V3\\ ETC.
OR
	^^INPUT _#N@R,V1,V2,V3\\ ETC.
.FILL
^WHERE ^N IS AN OPTIONAL FILE NUMBER AND ^V1, ^V2, ^V3 ETC. ARE
LEGAL STRING OR NUMERIC VARIABLE NAMES.
^THE SECOND FORM FOLLOWS THE RULES FOR RANDOM ACCESS DESCRIBED
FOR THE ^^PRINT\\ STATEMENT.
^NUMERIC DATA MUST BE SEPARATED BY COMMAS OR SPACES, SUCCESSIVE
STRING VARIABLES MUST BE SEPARATED BY A COMMA AFTER THE REQUIRED NUMBER
OF CHARACTERS HAVE BEEN TYPED IN.
^A CHARACTER LEGALITY CHECK IS PERFORMED TO ENSURE THAT ALL CHARACTERS
ARE BETWEEN OCTAL ^^ASCII\\ CODES 40 AND 137 INCLUSIVE AND 11 (TAB).
.SKIP
^FOR INPUT FROM THE TERMINAL (NO FILE NUMBER), A PROMPT STRING
(ONLY STRING DEFINED IN QUOTES ALLOWED) MAY BE SPECIFIED BEFORE
THE VARIABLE LIST.
^THIS IS EQUIVALENT TO A <PRINT FOLLOWED BY AN <INPUT.
^SEE THIRD EXAMPLE BELOW.
.SKIP
^FOR BINARY FILES THE FOLLOWING CONDITIONS HOLD: FOUR BYTES ARE USED
FOR EACH NUMERIC (FLOATING) VARIABLE, STRINGS USE AS MANY BYTES AS
THEY HAVE BEEN DIMENSIONED FOR.
^MORE DATA THAN VARIABLES IS NOT CONSIDERED AN ERROR.
^INSUFFICIENT DATA IS AN ERROR WITH THE FOLLOWING EXCEPTION:
A VARIABLE LENGTH STRING WILL HAVE ITS LENGTH SHORTENED TO THE
AVAILABLE DATA IF DATA RUNS OUT, AND A FIXED LENGTH STRING
WILL BE BLANK FILLED.
^IF DATA RUNS OUT WHILE FILLING A NUMERIC VARIABLE, THE RESULTS
ARE UNPREDICTABLE AND IN ANY CASE TERMINATE THE PROGRAM WITH AN ERROR.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 INPUT _#3,A1,B1$}
	{50 INPUT _#4@R+5,X1,X2,A1$}
	{80 INPUT "WHAT IS YOUR NAME",N$ : ! READ NAME INTO N$}
\\
.FILL
.SKIP
.X ^^INPUT LINE\\
.HEADERLEVEL 1 <INPUT <LINE
.BREAK
^THIS IS THE SAME AS THE INPUT STATEMENT EXCEPT THAT ONLY STRING
VARIABLES ARE PERMITTED IN THE INPUT LIST AND NO CHARACTER CHECKING IS
PERFORMED.
^THUS NO DELIMITERS ARE RECOGNIZED AND STRING VARIABLES ARE FILLED
SEQUENTIALLY TO THEIR DIMENSIONED LENGTH WHETHER FIXED OR VARIABLE.
^RANDOM ACCESS IS THE SAME AS FOR ^^INPUT\\.
^FOR BINARY FILES ^^INPUT#LINE\\ IS THE SAME AS ^^INPUT\\.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{30 INPUT LINE _#3,A1$}
\\
.FILL
.SKIP
.X ^^SCRATCH\\
.X ^PROGRAM DELETE
.HEADERLEVEL 1 ^^SCRATCH _<STRING FILESPEC>\\
.BREAK
^THE ^^SCRATCH\\ COMMAND MUST HAVE A FILE SPECIFIER WITH AN
EXPLICIT VERSION NUMBER IN ORDER TO DELETE A FILE.
^THE DEFAULT FILE SPECIFIER IS: ^^SY:PROGRAM.BAS\\
.BREAK
^EXAMPLE:
.NOFILL
^^
	{SCRATCH "DATA.DAT;3"}
	{50 SCRATCH "DK1:DAT3.TMP"}
\\
.FILL
.SKIP
.X ^^OPEN\\
.X ^FILE OPEN
.X ^RANDOM ACCESS ^I/^O
.HEADERLEVEL 1 <OPEN
.NOFILL
<OPEN COMMAND PROCESSOR.
^FORM:
^^
	OPEN _#EXP,STRING (WHERE STRING CONTAINS FILESPEC/SWITCHES)
\\
^ALLOWED SWITCHES:
	</FX	FOR <FIXED <LENGTH RECORDS (<VARIABLE ASSUMED)
	</RN	FOR <RANDOM <ACCESS (<SEQUENTIAL ASSUMED)
	</LN:LEN	TO SPECIFY BUFFER LENGTH IN BYTES (80 ASSUMED)
	</EN:LNO	TO SPECIFY LINE NO. FOR CONTROL XFER ON <EOF
	</BN	TO SPECIFY <BINARY FILE (<ASCII ASSUMED)
	</BL	FOR VIRTUAL ARRAY FILES (NOT TO BE USED WITH ABOVE)
^THE FOLLOWING SWITCHES SPECIFY FILE ACCESS
^THEY ARE MUTUALLY EXCLUSIVE EXCEPT FOR </SH (SHARED ACCESS):
	</RO	FOR READ ONLY ACCESS (DEFAULT)
	</WR	FOR WRITE ACCESS (CREATING NEW FILE)
	</UP	FOR UPDATE (READ,WRITE,APPEND)
	</MO	FOR MODIFICATION (READ,WRITE)
	</AP	FOR APPEND ONLY
	</SH	TO SET SHARED ACCESS BIT IN <FDB
.S
.F
^POSSIBLE VALUES OF <EXP RANGE FROM 3 TO 16. ^UP TO 6
RECORD TYPE FILES (NOT </BL) MAY BE OPEN SIMULTANEOUSLY.
^ANY NUMBER OF BLOCK MODE FILES (UP TO 14) MAY BE OPEN SIMULTANEOUSLY
SUBJECT ONLY TO TOTAL MEMORY AVAILABILITY.
^THE DEFAULT DEVICE FOR ALL <LUN\S IS <SY0:.
.S
.NF
^EXAMPLES:
^^
	{50 OPEN _#4, "LP:/WR"}
	{60 OPEN _#3,N$}
.FILL
\\
.SKIP
.X ^^CLOSE\\
.X ^FILE CLOSE
.HEADERLEVEL 1 ^^CLOSE N1[,N2...]\\
.BREAK
^THIS COMMAND CLOSES A USER DATA FILE WHOSE NUMBER IS ^N1, ^N2 ETC.
^NOTE THAT NO _# SIGN PRECEDES THE NUMBER.
^IF USED WITH NO FILE NUMBER, ALL USER FILES ARE CLOSED.
.BREAK
^EXAMPLE:
.NOFILL
^^
	{60 CLOSE 4}
	{70 CLOSE I1}
	{95 CLOSE}
\\
.FILL
.SL
.X ^^IF END\\
.HEADERLEVEL 1 ^^IF END [_#N] THEN _<LINE _#>\\
.BR
^THIS STATEMENT IS USED TO RESET THE END OF FILE BRANCH ON A GIVEN
FILE OR WITHOUT THE "_#^N", IT SETS THE TERMINAL END OF FILE BRANCH.
^THE SPECIFIED FILE MUST HAVE BEEN OPENED WITH THE POSSIBILITY OF
BEING READ FROM (I.E. CANNOT BE </AP OR </WR IN SEQUENTIAL MODE).
.BR
^EXAMPLES:
.NF
^^
	{100 IF END THEN 1500   :! SET TERMINAL END OF FILE LINE NO.}
	{120 IF END _#3 THEN 2100:! SET END OF FILE LINE NO. ON LUN 3}
\\
.F
.CHAPTER ^^LOADABLE SUBROUTINES\\
^THIS CHAPTER IS PRIMARILY CONCERNED WITH THE OPERATION OF USER WRITTEN
<MACRO SUBROUTINES. ^THE CAPABILITY OF CALLING A MACHINE LANGUAGE
SUBROUTINE TO PERFORM SOME COMPLEX CALCULATION CAN PROVIDE MUCH SIMPLER
PROGRAM OPERATION, AND/OR SIGNIFICANTLY INCREASE THE SPEED OF OPERATION.
.FG 1
^SEVERAL SPECIAL <MACRO SUBROUTINES PROVED SO USEFUL THAT THEY WERE MADE
A PERMANENT PART OF <BASIC AND AS SUCH DO NOT HAVE TO BE LOADED.
^THOSE ROUTINES ARE LISTED IN THIS CHAPTER.
.FG 1
^A SAMPLE OF A <MACRO SUBROUTINE WHICH WILL REVERSE A CHARACTER STRING
ALONG WITH A DESCRIPTION OF THE INTERNAL <BASIC SUBROUTINES IT USES
IS INCLUDED IN ^APPENDICES ^B _& ^C OF THIS MANUAL.
.SL
.X <LOAD
.HEADERLEVEL 1 ^^LOAD _<STRING FILESPEC>\\
.BR
^THIS COMMAND LOADS THE SPECIFIED FILE AS A USER CALLABLE SUBROUTINE.
^THE DEFAULT EXTENSION IS <BTK.
^SEE ^APPEND. <B FOR A SAMPLE USER LOADABLE SUBROUTINE
.BR
^EXAMPLE:
.NF
^^
	{610 LOAD "REVERS"}
\\
.F
.SL
.X <UNLOAD
.HEADERLEVEL 1 <UNLOAD
.BR
^THIS COMMAND UNLOADS ALL USER ASSEMBLY ROUTINES LOADED BY THE
<LOAD COMMAND.
.BR
^EXAMPLE
.NF
^^
	{500 UNLOAD}
\\
.F
.SL
.X <CALL
.X ^SUBOUTINE CALL
.X ^USER SUBROUTINE CALL
.HEADERLEVEL 1 ^^CALL "NAME"(ARG1,ARG2,...)\\
.BR
^THE <CALL STATEMENT IS USED BY THE <BASIC USER TO CALL SPECIALLY
WRITTEN <MACRO SUBROUTINES WHICH WILL PERFORM SPECIAL FUNCTIONS.
^THE CALLED ROUTINE NAME MUST BE ENCLOSED IN QUOTES AS ABOVE,
OR RESIDE IN A STRING EXPRESSION WHICH IS ENCLOSED IN PARENTHESES.
^THE <NAME MAY BE UP TO 6 CHARACTERS IN LENGTH.
^THE ENCLOSING PARENTHESES ARE NECESSARY TO KEEP THE ARGUMENT LIST
WHICH FOLLOWS FROM APPEARING AS A SUBSCRIPT TO A STRING VARIABLE.
.FG 1
^THE ARGUMENTS CAN BE STRING OR NUMERIC VARIABLES OR EXPRESSIONS.
^IN THE CASE THAT A VALUE IS TO BE RETURNED, THE ARGUMENT MUST
BE A SIMPLE VARIABLE (MAY BE SUBSCRIPTED).
^FOR VALUES WHICH ARE PASSED, EITHER EXPRESSIONS OR VARIABLES MAY
BE USED.
^THE VARIABLES AND EXPRESSIONS USED IN THE ARGUMENT LIST MUST
MATCH THE TYPE (STRING OR NUMERIC) EXPECTED BY THE SUBROUTINE.
.FG 1
^USER ROUTINES MUST PRESERVE THE TEXT POINTER (^R1) AND ON EXIT,
IF AN ARGUMENT LIST IS PRESENT, MUST POSITION IT JUST PAST THE
CLOSE PARENTHESIS.
^SEE <APPEND. <B FOR A SAMPLE LOADABLE ROUTINE.
.BR
^EXAMPLE:
.NF
^^
	{100 CALL "ABC"(A$,B)}
	{120 CALL (B$)(A-X,Y$+Z$)}
\\
.F
.SKIP
.HEADERLEVEL 1 <INSTRG
.X <INSTRG
.BR
^SUBROUTINE TO INSERT A STRING INTO ANOTHER STRING.
.NF
^^BASIC CALL:
	120 CALL "INSTRG"(S$,E$,P [,L])
WHERE:
	S$ = STRING VARIABLE INTO WHICH INSERTION IS MADE
	E$ = STRING EXPRESSION TO BE INSERTED
	P  = POSITION TO START INSERTION
	L  = OPTIONAL MAX LENGTH OF INSERTION
\\
.F
^IF ^L IS NOT SPECIFIED, THE LENGTH OF ^E$ IS USED BY DEFAULT FOR
THE LENGTH OF THE INSERTION.
^IF ^L IS SPECIFIED, JUSTIFICATION OF ^E$ IN A FIELD OF THAT SIZE
IS PERFORMED.
^A POSITIVE VALUE IS LEFT JUSTIFY, NEGATIVE MEANS RIGHT JUSTIFY.
^THIS ROUTINE IS AT LEAST THREE TIMES AS FAST AS THE "CUT AND PASTE"
METHOD USING THE <SBS$ FUNCTION.
^IF THE "CUT AND PASTE" IS FORMATTED AS A USER DEFINED FUNCTION,
THE SPEED INCREASE IS A FACTOR OF SEVEN.
^THEREFORE IT IS ALMOST ALWAYS PREFERABLE TO THE <SBS$ METHOD.
.SL
.X ^^OPEN LIBRARY\\
.X ^LIBRARY OPEN
.HEADERLEVEL 1 ^^OPEN LIBRARY\\
.NF
^FORMAT:
	50 ^^OPEN LIBRARY _#N,_<STRING FILESPEC>\\
.F
^THIS COMMAND FUNCTIONS SIMILARLY TO THE STANDARD <OPEN COMMAND
EXCEPT THAT A <MACRO LIBRARY FILE IS OPENED FOR QUESTION TEXT
OUTPUT AND OTHER QUESTION PROCESSING SUBROUTINES INVOKED BY THE
<CALL STATEMENT.
^A <LUN MUST BE USED THAT IS NOT ALREADY IN USE AND IS ONE OF THE
ALLOWABLE NUMBERS AS FOR THE STANDARD <OPEN.
^NO SWITCHES ARE ALLOWED AS ALL FILE OPTIONS ARE DETERMINED
INTERNALLY FOR HANDLING THE LIBRARY FORMAT.
.BR
^EXAMPLE:
.NF
^^
	{100 OPEN LIBRARY _#5,"QUESLS.MLB"}
	{200 OPEN LIBRARY _#3,A$}
\\
.F
.SL
.HEADERLEVEL 1 ^QUESTION ^DISPLAY
.X ^QUESTION ^DISPLAY
.BR
^A SERIES OF ROUTINES CAN BE USED FOR DISPLAYING QUESTIONS AT A
TERMINAL FOR INTERACTIVE DATA ENTRY APPLICATIONS.
^THE TEXT OF THE QUESTIONS THEMSELVES RESIDES IN A FILE MADE BY THE
<RSX LIBRARIAN (<LBR) AND FORMATTED AS A <MACRO LIBRARY (<.MLB
EXTENSION).
^THERE ARE THREE TYPES OF QUESTIONS THAT CAN BE DISPLAYED:
.NF
	0) ^MULTI-LINE TEXT DISPLAY
	1) ^SINGLE LINE QUESTION (TEXT INPUT)
	2) ^MULTIPLE CHOICE DISPLAY
.F
.SL
^THE QUESTIONS ARE FORMATTED AS MACROS WITH THE NAME OF THE QUESTION
BEING THE NAME OF THE MACRO.
^THERE IS A SINGLE ARGUMENT TO THE MACRO, A NUMBER WHICH IS THE
TYPE AS SPECIFIED ABOVE EXCEPT IN THE CASE OF TYPE 2, IT IS THE
TOTAL NUMBER OF CHOICES FOR THAT MULTIPLE CHOICE QUESTION (CAN
NEVER BE LESS THAN 2).
.SL
^THE QUESTION NAMES ARE USED FOR LINKING OF MULTIPLE CHOICE QUESTIONS
AND FOR QUESTION REPLACEMENT BY THE LIBRARIAN.
^QUESTION NAMES MAY BE UP TO 6 CHARACTERS IN LENGTH.
^THE CHARACTERS MUST BE LEGAL <RAD50 CHARACTERS I.E. ALPHANUMERIC,
PERIOD AND DOLLAR SIGN.
^AFTER DISPLAY, THE INPUT OF A RESPONSE IS LEFT TO THE USER PROGRAM.
.SL
^^MULTI-LINE TEXT\\
.SL
^THE MULTI-LINE TEXT QUESTION (NEED NOT BE AN ACTUAL QUESTION) IS
REPRODUCED EXACTLY AS ENTERED WITH THE CARRIAGE (CURSOR) POSITIONED
TO THE START OF THE NEXT LINE.
^THE TEXT DISPLAY IS TERMINATED WHEN THE <.ENDM DIRECTIVE IS ENCOUNTERED
AS THE FIRST ENTRY ON A LINE OTHER THAN SPACE OR TAB.
^TYPE CODE IS 0.
.NF
^EXAMPLE:
^^
	{.MACRO  MULTXT  0
	THIS IS AN EXAMPLE OF A
	MULTIPLE LINE TEXT QUESTION.
	IT MAY BE USED AS A QUESTION OR JUST
	TO PRINT OUT SOME INFORMATION FOR THE
	PROGRAM USER. ANY NUMBER OF LINES
	MAY BE USED.
	.ENDM}
\\
.F
.SL
^^SINGLE LINE QUESTION\\
.SL
^THIS TYPE OF QUESTION IS USUALLY USED TO SOLICIT TEXT INFORMATION
FROM THE USER (NAME, AGE ETC.).
^ONLY ONE LINE IS PRINTED AND THE CARRIAGE (CURSOR) IS POSITIONED
AT THE END OF THE LINE.
^ANY FURTHER LINES OF TEXT ENTERED FOR THIS QUESTION TYPE WILL NOT
BE DISPLAYED.
.BR
^EXAMPLE:
.NF
^^
	{.MACRO  SINGLE  1
	TYPE YOUR NAME: LAST, FIRST 
	.ENDM}
\\
.F
.SL
^^MULTIPLE CHOICE QUESTION\\
.SL
^THIS TYPE OF QUESTION IS USED TO SOLICIT A NUMBER RESPONSE WHICH
IS SELECTED FROM A FINITE SET OF CHOICES DISPLAYED TO THE USER.
^A SUCCEEDING QUESTION MAY BE SELECTED DEPENDING ON THE RESPONSE
TO THE DISPLAYED QUESTION.
^THUS MULTIPLE CHOICE BRANCHING STRUCTURES MAY BE SET UP.
^THE CHARACTER USED TO SEPARATE THE RESPONSE TEXT FROM ITS
ASSOCIATED BRANCHING QUESTION NAME IS THE BACKSLASH.
^THE NUMBER OF CHOICES IS THE NUMBER FOLLOWING THE QUESTION NAME
IN THE <.MACRO LINE.
.BR
^EXAMPLE:
.NF
^^
	{.MACRO  MULCHC  3
	SELECT YOUR STATE OF MIND
	GOOD_\MULCH1
	FAIR_\MULCH2
	TGIF_\MULCH3
	.ENDM}
\\
.F
.SL
^^COMMON INFORMATION FOR ALL QUESTION PROCESSING CALLS\\
.SL
^SBROUTINES ARE PROVIDED IN THREE DIFFERENT FORMS TO PERFORM A
NUMBER OF DIFFERENT FUNCTIONS.
^THE FUNCTIONS ARE AS FOLLOWS:
.NF
	1) ^DISPLAY QUESTION
	2) ^POSITION TO QUESTION
	3) ^RETURN QUESTION TEXT
	4) ^RETURN ANSWER TEXT
	5) ^RETURN QUESTION NAME
.SL
^THE THREE FORMS OF THE SUBROUTINES ARE AS FOLLOWS:
	1) '^M' FORM: PERFORM FUNCTION BY NAME
	2) '^C' FORM: PERFORM FUNCTION ON QUESTION LINKED TO PREV. QUEST.
	3) '^R' FORM: PERFORM FUNCTION ON LAST QUESTION ACCESSED
.SL
.F
^IN GENERAL THE '^M' FORM AND '^C' FORM OF THE SUBROUTINES RESET THE
LAST QUESTION ACCESSED.
^THE '^R' FORM, SINCE IT ACTS ON THE LAST QUESTION ACCESSED, DOES NOT
CHANGE IT.
^THE ONE EXCEPTION IS THE '^C' FORM OF THE RETURN QUESTION NAME FUNCTION
(<CQNAM).
^IT DOES NOT CHANGE THE LAST QUESTION ACCESSED.
.FG 1
^THE '^M' FORM OF THE SUBROUTINES USES A NAME SPECIFIED AS AN INPUT STRING
ARGUMENT (3RD PARAMETER) TO POSITION TO THE SPECIFIED QUESTION AND THEN
PERFORM THE REQUIRED ACTION.
.FG 1
^THE '^C' FORM USES THE LAST QUESTION ACCESSED (POSITIONED TO) IN ORDER
TO POSITION TO ANOTHER QUESTION.
^TO DO THIS, THE LAST QUESTION MUST HAVE BEEN A MULTIPLE CHOICE QUESTION
AND A LINK MUST BE PROVIDED FOR THE ANSWER NUMBER SPECIFIED AS THE
THIRD PARAMETER IN THE SUBROUTINE CALL.
.FG 1
^THE '^R' FORM USES THE PREVIOUSLY ACCESSED QUESTION (WHETHER BY '^M'
OR '^C') TO PERFORM ITS ACTION.
^THE THIRD PARAMETER IS A DUMMY NUMERIC PARAMETER.
.SL
^^GENERAL PARAMETERS\\
.SL
^FOLLOWING IS A DESCRIPTION OF THE SYMBOLIC PARAMETER NAMES USED IN
DESCRIBING THE VARIOUS SUBROUTINE CALLS.
^THEY ARE, OF COURSE, REPLACED IN THE ACTUAL CALLS BY LEGAL <BASIC
EXPRESSIONS IN THE CASE OF INPUT VALUES AND BY LEGAL VARIABLE NAMES
IN THE CASE OF OUTPUT VALUES.
.NF
	<LUN:    ^INPUT VALUE CONTAINING <LUN USED IN <OPEN <LIBRARY COMMAND
	<STATUS: ^OUTPUT VALUE RETURNING STATUS OF ACTION REQUESTED
	        +2 OR GREATER = MAX RESPONSE _# FOR MULTIPLE CHOICE QUES.
	        +1 = QUESTION WAS A TEXT INPUT TYPE (SINGLE LINE)
	         0 = QUESTION WAS MULTI-LINE INFO DISPLAY
	        -1 = <LUN NOT FOUND (<OPEN <LIBRARY NOT DONE ON THIS <LUN)
	        -2 = <FCS ERROR DURING READ
	        -3 = ^QUESTION NOT FOUND (FOR A VARIETY OF REASONS)
	<NAME$:  ^INPUT STRING CONTAINING QUESTION NAME ('^M' TYPE)
	<ANS:    ^INPUT NUMERIC VALUE WITH ANSWER TO PREV. QUES. ('C' TYPE)
	<DUMMY:  ^DUMMY NUMERIC INPUT ('^R' TYPE)
.F
.NOTE
^THE VALUE OF -3 RETURNED FOR <STATUS CAN INDICATE A VARIETY OF
CONDITIONS.
^FOR '^M' TYPE CALLS, IT MEANS THE SPECIIED QUESTION NAME IS NOT PRESENT
IN THE LIBRARY FILE.
^FOR '^C' TYPE CALLS, IT WILL BE RETURNED IF THE PREVIOUS QUESTION WAS
NOT A MULTIPLE CHOICE TYPE, IF NO LINKED QUESTION WAS RECORDED FOR THE
SPECIFIED ANSWER, OR IF THE LINKED QUESTION SPECIFIED WAS NOT PRESENT
IN THE LIBRARY.
.ENDNOTE
.SL
.HEADERLEVEL 1 ^^MDIS . . CDIS . . RDIS\\
^^DISPLAY QUESTION SUBROUINES\\
.BR
.X <MDIS
.X <CDIS
.X <RDIS
.NF
^FORMATS:
^^
	CALL "MDIS"(LUN,STATUS,NAME$[,STRING$,COUNT])
	CALL "CDIS"(LUN,STATUS,ANS[,STRING$,COUNT])
	CALL "RDIS"(LUN,STATUS,DUMMY[,STRING$,COUNT])
\\
.F
^THE NAMED QUESTION, LINKED QUESTION OR PREVIOUS QUESTION WILL BE
DISPLAYED RESPECTIVELY BY THE ABOVE THREE SUBROUTINE CALLS ACCORDING
TO THE FOLLOWING RULES.
^IF THE OPTIONAL PARAMETERS ARE NOT SPECIFIED:
.SL
^^MULTI-LINE INFO DISPLAY\\:
^TEXT IS DISPLAYED AS TYPED.
^CARRIAGE (CURSOR) IS POSITIONED TO THE START OF THE NEXT LINE.
^ALL LINES UP TO THE LINE WITH A LEADING <.ENDM DIRECTIVE WILL
BE DISPLAYED.
.SL
^^SINGLE LINE TEXT INPUT\\:
^THE LINE OF TEXT IS DISPLAYED WITH THE CARRIAGE (CURSOR) TO THE
IMMEDIATE RIGHT OF THE TEXT JUST DISPLAYED.
^ANY SPACES REQUIRED AFTER THE TEXT MUST BE EITHER INCLUDED IN THE
QUESTION TEXT OR ADDED FROM THE PROGRAM VIA A <PRINT STATEMENT.
.SL
^^MULTIPLE CHOICE QUESTION\\:
^FOR THIS TYPE QUESTION THE FIRST LINE IS DISPLAYED AS TYPED.
^SUBSEQUENT LINES ARE DISPLAYED WITH A LEADING SPACE AND A NUMBER
WHICH STARTS AT ONE AND INCREASES BY ONE FOR EACH SUCCEEDING LINE.
^THE NUMBER IS THEN FOLLOWED BY A RIGHT PARENTHESIS ')' AND ANOTHER
SPACE AND THEN THE TEXT FOR THAT LINE.
^AFTER ALL LINES HAVE BEEN DISPLAYED, THE CARRIAGE (CURSOR) IS THEN
POSITIONED TO THE START OF THE NEXT LINE.
.NOTE
^THE TOTAL NUMBER OF LINES DISPLAYED IS THE NUMBER GIVEN AS
THE ARGUMENT ON THE <.MACRO LINE PLUS ONE AND IS INDEPENDENT OF WHERE
THE <.ENDM LINE OCCURS.
^THIS MAY LEAD TO NOT DISPLAYING ALL OF THE TYPED IN QUESTION TEXT OR
THE OUTPUT OF GARBAGE IF THE QUESTION HAS NOT BEEN TYPED IN PROPERLY.
.ENDNOTE
^IF THE OPTIONAL PARAMETERS ARE SPECIFIED (BOTH MUST BE PRESENT), THE
FOLLOWING HOLDS:
.SL
^^MULTI-LINE INFO DISPLAY\\:
^IF ^N IS THE NUMBER SPECIFIED IN <COUNT, THEN THE TEXT IS DISPLAYED
PRECEDED BY ^N CHARACTERS OF <STRING$ FOR EACH LINE UNTIL THE
CHARACTERS IN <STRING$ ARE EXHAUSTED OR THE DISPLAY IS COMPLETE
(NORMALLY THESE SHOULD HAPPEN TOGETHER).
.SL
^^ SINGLE LINE TEXT INPUT\\:
^THE LINE OF TEXT IS DISPLAYED AS BEFORE BUT WITH ^N CHRACTERS OF
<STRING$ PRECEDING IT.
.SL
^^MULTIPLE CHOICE QUESTIONS\\:
^IN THIS CASE THE FIRST LINE IS DISPLAYED AS ABOVE, BUT THE
SUBSEQUENT LINES (ANSWERS) ARE EACH PRECEDED BY ^N CHARACTERS FROM
<STRING$.
.SL 2
.HEADERLEVEL 1 ^^MPOS . . CPOS . . RPOS\\
.X <MPOS
.X <CPOS
.X <RPOS
^^POSITION TO QUESTION SUBROUTINES\\
.BR
.NF
^FORMATS:
^^
	CALL "MPOS"(LUN,STATUS,NAME$)
	CALL "CPOS"(LUN,STATUS,ANS)
	CALL "RPOS"(LUN,STATUS,DUMMY)
\\
.F
^IN THE FIRST TWO CASES, A NEW QUESTION IS POSITIONED TO (ACCESSED)
AND A STATUS (COUNT) VALUE RETURNED.
^IN THE LAST CASE, THE POSITIONING REMAINS UNCHANGED, BUT THE STATUS
(COUNT) IS RETURNED.
.HEADERLEVEL 1 ^^MQTXT . . CQTXT . . RQTXT\\
.X <MQTXT
.X <CQTXT
.X <RQTXT
^^RETURN QUESTION TEXT SUBROUTINES\\
.BR
.NF
^FORMATS:
^^
	CALL "MQTXT"(LUN,STATUS,NAME$,STRING$)
	CALL "CQTXT"(LUN,STATUS,ANS,STRING$)
	CALL "RQTXT"(LUN,STATUS,DUMMY,STRING$)
\\
.F
^THE QUESTION TEXT OF THE NAMED, LINKED OR CURRENT QUESTION IS
RETURNED IN THE VARIABLE <STRING$ (MUST BE A SINGLE VARIABLE NAME).
^IN THE CASE OF A MULTI-LINE INFO DISPLAY (TYPE 0), THE FIRST
LINE IS RETURNED.
.HEADERLEVEL 1 ^^MATXT . . CATXT . . RATXT\\
.X <MATXT
.X <CATXT
.X <RATXT
^^RETURN ANSWER TEXT SUBROUTINES\\
.BR
.NF
^FORMATS:
^^
	CALL "MATXT"(LUN,STATUS,NAME$,STRING$,ANS1)
	CALL "CATXT"(LUN,STATUS,ANS,STRING$,ANS1)
	CALL "RATXT"(LUN,STATUS,DUMMY,STRING$,ANS1)
\\
.F
^THE TEXT CORRESPONDING TO <ANS1 IS RETURNED IN <STRING$ FOR
THE NAMED, LINKED OR CURRENT QUESTION.
^IN THE CASE OF A MULTI-LINE INFO DISPLAY, THE FIRST ANSWER
CORRESPONDS TO THE SECOND LINE OF TEXT AND SO ON.
^NOTE THAT THERE IS NO WAY TO DISCERN IN ADVANCE HOW MANY LINES
THERE ARE IN THIS CASE.
^THUS THE USER PROGRAM SHOULD TEST FOR THE PRESENCE OF '.<ENDM'
IN THE RETURNED LINE.
^NO INTERNAL RESTRAINTS ARE PLACED ON THE VALUE OF <ANS1 AND
SO PARTS OF FOLLOWING QUESTIONS MAY BE RETURNED IF CARE IS
NOT EXERCISED.
.HEADERLEVEL 1 ^^CQNAM . . RQNAM\\
.X <CQNAM
.X <RQNAM
^^RETURN QUESTION NAME SUBROUTINES\\
.BR
.NF
^FORMATS:
^^
	CALL "CQNAM"(LUN,STATUS,ANS,STRING$)
	CALL "RQNAM"(LUN,STATUS,DUMMY,STRING$)
\\
.F
^IN THE FIRST CASE, THE NAME OF THE QUESTION LINKED BY <ANS IS
RETURNED IN <STRING$.
^NOTE THAT THE LINKED QUESTION IS NOT POSITIONED TO, THUS
ENABLING A USER PROGRAM TO RECORD MULTIPLE LINKED NAMES
WITHOUT HAVING TO REPOSITION TO THE ORIGINAL QUESTION.
^IN THE SECOND CASE THE CURRENT QUESTION NAME WILL BE RETURNED
IN <STRING$.
.HEADERLEVEL 1 <SPAWNB
.X <SPAWN
^SUBROUTINE TO SPAWN A TASK USING THE <IAS SPAWN DIRECTIVE.
.BR
.NF
<FORMAT:
^^CALL "SPAWNB"(C$ [,S])\\
.BR
.FILL
^THIS ROUTINE PASSES THE <MCR COMMAND LINE IN <C$ TO THE OPERATING
SYSTEM. ^COMMANDS TO ANOTHER ^B^A^SIC PROGRAM, <PIP, ETC MAY BE
PASSED IN THE COMMAND LINE JUST AS WITH <MCR. ^THE EXITING STATUS
OF THE SPAWNED TASK IS RETURNED IN THE (OPTIONAL) VARIABLE ^S.
.FG 1
^IF THE <STATUS VARIABLE IS PRESENT, THE ISSUING <BASIC PROGRAM WILL
<STOP, AND CONTINUE WHEN THE <SPAWNED TASK EXITS. ^IF NO <STATUS
VARIABLE IS PRESENT IN THE CALL, <BASIC EXECUTION CONTINUES IMMEDIATELY.
.FG 1
^DURING THE TIME THAT <BASIC IS <STOPPED FOR THE <SPAWNED TASK, CONTROL-^C'S
WILL NOT HAVE THE NORMAL EFFECT. ^ALSO  <BASIC DETACHES THE TERMINAL
SO <PIP LISTS TO THE TERMINAL ETC. CAN OCCUR.
.NOTE
<SPAWN KNOWS ABOUT THINGS LIKE <DIR, ^^PRI\\NT, ETC., BUT THE
TASK IN QUESTION MUST BE INSTALLED IN THE SYSTEM. ^THE AUTO-INSTALL FUNCTION
FOR INFREQUENTLY USED TASKS DOES NOT WORK FOR <SPAWNB.
^IF <SPAWN DETECTS THAT THE REQUESTED TASK IS UNAVAILABLE, IT RETURNS
THE SYSTEM FAILURE STATUS (CURRENTLY -2 -- ^TASK NOT INSTALLED.)
.ENDNOTE
.APPENDIX ^^BASIC ERROR VALUES\\
.NOFILL
^^
  0.  USER STORAGE OVERFLOW
  1.  UNRECOGNIZED STATEMENT - CHECK SPELLING
  2.  ILLEGAL GOTO OR GOSUB
  3.  ILLEGAL CHARACTER IN OR TERMINATING INPUT LINE
  4.  RETURN WITHOUT GOSUB
  5.  BADLY FORMED SUBSCRIPT
  6.  SUBSCRIPT OUT OF RANGE
  7.  MISMATCHED PARENTHESES
  8.  ILLEGAL LET STATEMENT
  9.  ILLEGAL RELATIONAL OPERATOR IN IF
 10.  ILLEGAL IF
 11.  ILLEGAL PRINT
 12.  DEVICE OR FILE ERROR %D ON INPUT
 13.  BAD DIMENSION
 14.  NOT ENOUGH ROOM IN STORAGE FOR THE ARRAY
 15.  BADLY FORMED DEFINE
 16.  ILLEGAL LINE NUMBER OR DIMENSION VALUE
 17.  DIM OF PREVIOUSLY USED VARIABLE NAME
 18.  BAD VARIABLE IN INPUT LIST
 19.  BAD VARIABLE IN READ LIST
 20.  OUT OF DATA DURING READ
 21.  BAD DATA IN A DATA STATEMENT
 22.  ILLEGAL FOR STATEMENT
 23.  NO NEXT WITHOUT MATCHING FOR
 24.  NEXT WITHOUT FOR
 25.  UNMATCHED QUOTES IN STATEMENT
 26.  EXTERNAL FUNCTION NOT PROPERLY SET UP
 27.  BADLY FORMED EXPRESSION
 28.  ERROR IN COMMAND STRING INTERPRETER
 29.  SBS FUNCTION ERROR
 30.  SYNTAX ERROR IN FUNCTION
 31.  SYNTAX ERROR IN OPEN
 32.  SYNTAX ERROR IN CLOSE
 33.  INVALID FILE NUMBER
 34.  END OF FILE ERROR
 35.  FCS ERROR %D DURING CLOSE
 36.  FCS ERROR %D DURING OPEN
 37.  ERROR DURING CALL PROCESSING
 38.  ERROR IN CALL ARGUMENT LIST
 39.  ERROR IN STORE DURING CALLED ROUTINE
 40.  SYNTAX ERROR OR LUN IN USE IN LIBRARY OPEN
 41.  FCS ERROR %D DURING LIBRARY OPEN OR 1ST READ
 42.  SYNTAX ERROR IN SLEEP COMMAND
 43.  SYNTAX ERROR IN WAIT COMMAND
 44.  TIMEOUT ERROR - YOU WAITED TOO LONG TO TYPE
 45.  PRIORITY ERROR
 46.  BASIC PROGRAM FILE ERROR %D
 47.  FILE ACCESS MODE ERROR (SEQ/RAN)
 48.  ERROR IN LOADED USER SUBROUTINE
 49.  VIRTUAL ACCESS ERROR - FCS %D
 50.  VIRTUAL FILE OPEN ERROR - FCS %D
 51.  ERROR IN SET COMMAND
 52.  USE OF "/CO" SWITCH WITH NORMAL BASIC SOURCE
 53.  IMMEDIATE MODE COMMAND IN SOURCE TEXT
 62.  DEBUG _#1 AT R3=%P
 63.  DEBUGGING ERROR _#2 - CALL SYSTEM MANAGER
 64.  LOG OF NEGATIVE OR ZERO NUMBER
 65.  SQUARE ROOT OF NEGATIVE NUMBER
 66.  FLOATING DIVIDE BY ZERO
 67.  NUMBER TOO LARGE TO FIX
 68.  FLOATING OVERFLOW
 69.  FLOATING UNDERFLOW
 70.  NON-EXISTENT VARIABLE
 71.  TOO MUCH DATA TYPED
 72.  NOT ENOUGH DATA TYPED
 73.  ILLEGAL CHARACTERS ON INPUT
 74.  ERROR IN VALUE FUNCTION
 75.  NOT ENOUGH DATA TYPED
 76.  ILLEGAL CHARACTERS ON INPUT
 77.  ERROR IN VALUE FUNCTION
 78.  SYNTAX ERROR IN FUNCTION
 79.  SYNTAX ERROR IN OPEN
200.  FLOATING OVERFLOW
202.  FLOATING UNDERFLOW
211.  LOG OF NEGATIVE OR ZERO VALUE
212.  SQUARE ROOT OF NEGATIVE VALUE
.APPENDIX ^^SAMPLE LOADABLE MACRO SUBROUTINE\\
.NOFILL
^^
.TS 18,24,32,40,48,56,64
;
; TEST SUBROUTINE FOR BASIC LOAD COMMAND
;
; THIS SUBROUTINE SHOULD REVERSE A STRING
;
; CALL IS 	CALL "REVSTR"(IN$,OU$)
;
;		WHERE	IN$=STRING TO BE REVERSED
;			OU$=RESULTANT STRING
;
; IDENTIFYING INFO:
	.MCALL	ULODHD	;CALL MACRO
				;IDENTIFY START OF CODE, END OF CODE
				;AND ONE ENTRY POINT
	ULODHD	REVSTR,END,REVSTR
;
; NOW THE CODE ITSELF
;
;
REVSTR:				;LABLE ACTUAL START OF CODE
	JSR	R4,@_#GTRGPI	;GO GET ARGUMENTS IN PI FASHION
	.BYTE	3,4,0		;THIS IS ARG TYPE LIST
				;3 = INPUT STRING (TO SUBROUTINE)
				;4 = OUTPUT STRING (TO MAIN PROG.)
	.EVEN
				;WE NOW HAVE THIS DATA ON THE STACK
				;SP+4	5-WORD STRING TABLE ENTRY
				;	FOR OUTPUT STRING
				;SP>	2-WORD INPUT DESCRIPTOR
				;	(SP)=LEN, 2(SP)=ADDR
	JSR	PC,@_#PARCHK	;CHECK FOR TRAILING RIGHT PAREN
				;(ALSO BUMPS TEXT POINTER)
	MOV	R1,-(SP)	;SAVE TEXT PTR
	MOV	2(SP),R0	;LEN OF INPUT STRING -> R0
	BEQ	3$		;IF ZERO, BRANCH
	JSR	PC,@_#TSTU00	;CHECK FOR ROOM IN USER STORAGE AREA
				;WIPES R3,R4,
				;R5 -> NEXT BYTE IN USER STORAGE AREA
	BHI	1$		;BRANCH IF ROOM EXISTS
	OVFERR			;ELSE DO ERROR TRAP
1$:	MOV	R0,R4		;SAVE LENGTH IN R4
	BIS	_#160000,R0	;MAKE R0 A "SCRATCH" DATA TYPE HEADER
	MOV	R0,(R5)+	;PUT HEADER IN USER AREA
	MOV	R5,R2		;SAVE STRING ADDRESS (IN USER AREA)
	MOV	4(SP),R3	;ADDRESS OF INPUT STRING -> R3
	MOV	R4,R0		;STRING LENGTH -> LOOP COUNTER
	ADD	R4,R3		;BUMP R3 PAST END OF INPUT STRING
2$:	MOVB	-(R3),(R5)+	;REVERSE THE STRING
	SOB	R0,2$
	MOV	R2,R3		;OUTPUT STRING ADDRESS -> R3
				;STRING LENGTH STILL IS IN R4
3$:	MOV	SP,R5		;GET ADD OF RETURN ARG DESCRIPTOR
	ADD	_#6,R5		;IN R5
	JSR	PC,@_#SSTORE	;AND RETURN THE RESULT TO THE CALLER
	MOV	(SP)+,R1	;RESTORE TEXT PTR
	ADD	_#7*2,SP		;CLEAN STACK OF 7 WORDS
	RTS	PC		;AND RETURN
END:				;LABLE END OF CODE
	.END
 
 
MACRO COMMAND FILE
 
REVSTR,REVSTR/-SP=LB:[1,202]LOAMAC/ML,[1,202]REVSTR
 
 
TKB COMMAND FILE
 
REVSTR.ATK/-HD/-FP,REVSTR/-SP=REVSTR
LB:[1,1]BSCPUR.STB/SS
/
STACK=0
UNITS=0
/
.APPENDIX ^^USEFUL INTERNAL BASIC SUBROUTINE CALLS\\
.NOFILL
^^
; GETARG: TO RETRIEVE ADDRESSES OR VALUES FROM AN ARGUMENT LIST
; IN A BASIC "CALL" STATEMENT.
;
; ON ENTRY:	R5 POINTS TO A USER TABLE FOR RESULT TO BE PLACED IN
;		R1 POINTS TO POS IN ARG LIST (MUST BE "," OR "(" )
;		R0 POINTS TO LIST OF BYTE ARG TYPES (TERM. BY 0 OR > 4)
; ON RETURN:	R5 POINTS TO THE FIRST WORD PAST THE RETURNED DATA
;		R1 POINTS TO NEXT CHAR FOLLOWING LAST ARG JUST RETURNED
;		R0 POINTS TO FIRST BYTE AFTER TERMINATING BYTE
; ARG TYPES IN R0 LIST:
;		1 = INPUT NUMERIC EXPRESSION	(2-WORD FLOATING POINT)
;
;		2 = OUTPUT NUMERIC TARGET	(5 WORDS)
;						2-WORD FP VALUE
;						2-WORD FP OFFSET
;						1-WORD OFFSET TO HEADER
;
;		3 = INPUT STRING EXPRESSION	(2 WORDS) LEN, ADDRESS
;
;		4 = OUTPUT STRING TARGET	(5-WORDS)
;						1-WORD ADDRESS
;						1-WORD LENGTH
;						2-WORD FP OFFSET
;						1-WORD HEADER ADDRESS
;
;		FOR STANDARD VARIABLE, FP-OFFSET IS FROM STUDAT
;		FOR VIRTUAL  VARIABLE, FP-OFFSET IS FROM FILE START
;
;		0 OR > 4 = LIST TERMINATOR
; ALL OTHER REGISTERS WILL BE USED AND DESTROYED
;
; GTRGPI: POSITION INDEPENDENT ARGUMENT RETRIEVAL FOR USER LOADED
; ROUTINES. THE ARGUMENT TYPE LIST FOLLOWS THE CODE IN A JSR R4,GTPRI
; INSTRUCTION. THE ARGUMENT LIST ITSELF IS CONSTRUCTED ON THE STACK
; AND POINTED TO BY SP ON RETURN.
; ON ENTRY:
;	R4 POINTS TO ARG TYPE LIST (VIA JSR R4,@_#GTRGPI)
;	OLD R4 ON STACK (WILL BE POPPED)
; ON RETURN:
;	SP -> ARG LIST (ON STACK - TO BE REMOVED BY CALLING ROUTINE)
; OTHER REGISTERS: POTENTIALLY ALL
;
;
; NSTORE: TO STORE AWAY A VALUE FROM AC0 INTO A LOCATION
; STORED IN A TABLE SUCH AS THAT FILLED IN BY GETARG.
; ON CALL:	R5 CONTAINS POINTER TO ADDRESS
;		AC0 CONTAINS VALUE TO BE STORED
; ON RETURN:	NOTHING CHANGED
; REGISTERS USED: R0, AC1
;
;
;
;
;
; SSTORE: TAKE A STRING DESCRIBED BY LEN IN R4 AND ADDRESS IN R3
; AND STORE IT INTO A STRING VARIABLE WHOSE TABLE ENTRY IS
; POINTED TO BY R5.
;
; ON CALL:	R3 = ADDRESS OF STRING TO BE STORED
;		R4 = LENGTH OF STRING TO BE STORED
;		R5 = POINTER TO OUTPUT STRING TABLE ENTRY
;
; ON RETURN:	R3 POINTS PAST END OF STRING
;		R4 = 0
;		R5 UNCHANGED
; OTHER REGISTERS USED:	R0,R2 (ALL BUT R1)
;
;
; ARGCNT: COUNT ARGUMENTS ROUTINE
; ON ENTRY:	R1 POINTS TO LEADING OPEN PAREN "("
; ON EXIT:	R1 UNCHANGED
;		R0 CONTAINS COUNT OF ARGUMENTS UP TO ")" IN THE LIST
;		   QUOTED STRINGS AND SUBSCRIPTS ARE ACCOUNTED FOR
; OTHER REGISTERS USED: R2
; NOTE:		AN END OF LINE WILL TERMINATE THE SCAN IRRESPECTIVE OF
;		ENCLOSING QUOTES AS LONG AS IT IS USED AS THE INTERNAL
;		LINE DELIMITER (S.EOL1 OR S.EOL2)
;
;
;
;
; TSTU00 - CHECK FOR USER STORAGE OVERFLOW
;
;  CHECK FOR POSSIBLE USER STORAGE OVERFLOW
;
; ON ENTRY
;	R0=NUMBER OF BITES TO PUT IN USER STORAGE
; ON EXIT
;	R5-> NEXT AVAILABLE BYTE IN USER STORAGE
; OTHER REGISTERS USED
;	R0,R3,R4
;
; STATUS RETURNED IN C-BIT
;	BHI WILL BRANCH IF ROOM EXISTS
;
;
;
; PARCHK: CHECK THAT NEXT CHARACTER IN TEXT IS A ")"
;
; CALL WITH
;	R1-> PROGRAM TEXT
;
; SUCCESSFUL RETURN
;	")" IN R2
;	R1-> PAST ")"
; ERROR RETURN
;	CALL TO "ERROR IN PROCESSING CALL STATEMENT"
;
;
;
;
; SKIP00: SKIP OVER BLANKS IN PROGRAM TEXT - GET NEXT CHARACTER
;
; ENTER WITH R1 -> TEXT
;
; EXIT STATUS
;	R2 = CHARACTER
;	R1 -> NEXT CHARACTER (AFTER R2 CHARACTER) IN TEXT
;
;
; OTHER REGISTERS USED - NONE
;
;
;
; FORMAT FOR BASIC LOADABLE SUBROUTINES:
;	SET UP BY THE "ULODHD" MACRO
;
; FIRST THREE WORDS:
;	.WORD	ID0001	;THESE THREE WORDS ARE FILLED IN BY GLOBAL SYMBOLS
;	.WORD	ID0002	;FROM A SYMBOL TABLE FOR BASIC, ENSURING CORRECT
;	.WORD	ID0003	;SYMBOL LINKAGES (OR ELSE ERROR MESSAGE).
; NEXT TWO WORDS ARE LENGTHS:
;	.WORD	??????	;LENGTH (IN BYTES) OF CODE PLUS ENTRY POINTS
;	.WORD	??????	;LENGTH (IN BYTES) OF ENTRY POINTS
;	.WORD	??????	;_# OF ENTRY POINTS
; NEXT ENTRIES ARE THREE WORD BLOCKS DESCRIBING ENTRY POINTS
;	.RAD50	/NAME/	;TWO WORDS OF RAD50 ENTRY POINT NAME
;	.WORD	??????	;OFFSET FROM START OF CODE PROPER
; FINALLY, ONE WORD CONTAINING NUMBER OF WORDS OF CODE PROPER:
;	.WORD	??????	;LEN (IN WORDS) OF CODE PROPER
;
; NOTE: THESE MODULES MUST BE TASK BUILT WITH /-HD/-FP AND:
;	STACK=0
;	UNITS=0
;
; IN ADDITION POSITION INDEPENDENT CODING TECHNIQUES MUST BE USED IN
; WRITING THE CODE BECAUSE ITS POSITION IN THE INTERPRETER WILL VARY
; DEPENDING ON WHAT OTHER ROUTINES ARE LOADED.
.APPENDIX ^^INDEX\\
.PX
