.PAPER SIZE 56,60
.SPACING 1
.LEFT MARGIN 5
.RIGHT MARGIN 56
.TITLE ^^RSX-11 FOCAL\\
.SKIP 2
.CENTER
^^RSX-11##FOCAL-11\\
.SKIP 5
.LEFT MARGIN 10
.RIGHT MARGIN 45
.PARAGRAPH
^THIS VERSION OF THE ^^FOCAL\\ LANGUAGE WAS DEVELOPED
TO RUN UNDER ^^RSX-11D\\ ^V6 AND LATER AND HAVE NUMEROUS
DATA MANIPULATION OPTIONS,
THOUGH IT WILL RUN UNDER ^^RSX11M\\ OR ^^IAS\\ WITH
ESSENTIALLY NO CHANGE. ^THE MANUAL HERE DOES NOT
PRETEND TO BE A COMPLETE DESCRIPTION OF ^^FOCAL\\,
BUT ONLY ATTEMPTS TO GIVE A BRIEF SUMMARY OF ITS
FUNCTIONS FOR NEW USERS. ^ADDITIONAL RELEVANT DOCUMENTS
ARE "^^FOCALRSX.DOC\\", WHICH DESCRIBES THE PECULIARITIES OF
THIS IMPLEMENTATION, "^^INSFCL.DOC\\", GIVING SOME DETAILS
OF ^^FOCAL\\'S INTERNAL WORKINGS AND ERROR CODE
MEANINGS, AND THE ^D^E^C DOCUMENT FOR ^^FOCAL-11\\.
.PAGE
.LEFT MARGIN 5
.RIGHT MARGIN 56
.CENTER
^^INTRODUCTION\\
.SKIP 1
.PARAGRAPH
^IT OFTEN HAPPENS THAT A COMPUTER IS USED FOR
CALCULATIONS OR SIMPLE DATA MANIPULATIONS WHERE THE
PROGRAMS WRITTEN WILL BE RUN ONLY A FEW TIMES (OFTEN
ONLY ONCE) AND DEBUGGING IS THE MOST ONEROUS PART OF
THE PROGRAM DEVELOPMENT. ^THE PROCEDURE WITH BATCH-
ORIENTED LANGUAGES LIKE ^^FORTRAN\\ IS TO RUN AN EDITOR,
THEN A COMPILER, THEN A LINKER OR TASK-BUILDER, AND
ONLY THEN MAY ONE FIND OUT IF ONE'S PROGRAM WORKED.
^THE LONG CYCLE OF DEVELOPMET WASTES A LOT OF TIME
AND MAKES ONE WISH FOR A LESS TEDIOUS WAY OF MAKING
TRIVIAL CHANGES. ^THIS IS IN FACT TRUE WHEN DEVELOPING
ALGORITHMS FOR ALMOST ANY CALCULATION--DEBUGGING ^^FORTRAN\\
IS NOT QUICK.
.PARAGRAPH
^FOR THIS REASON ONE USES INTERPRETIVE LANGUAGES LIKE
^^FOCAL\\ OR ^^BASIC\\. ^^FOCAL\\ READS A SOURCE PROGRAM
INTO MEMORY AND EXECUTES ITS COMMANDS ONE AT A TIME
IN THE ORDER THEY SPECIFY. IT CREATES SYMBOLS DYNAMICALLY
AND CAN STOP AND ALLOW USERS TO CHANGE PROGRAMS OR
VARIABLES AND INSPECT WHAT IS GOING ON, OR EXECUTE
THEIR CALCULATIONS A BIT AT A TIME TO SEE WHAT THE
COMPUTER IS ACTUALLY DOING. ^THIS MAKES IT EASY TO
GET A PROGRAM RIGHT, AND IT CAN BE SAVED WHEN FINALLY
WORKING. ^BECAUSE ^^FOCAL\\ READS ITS COMMANDS
IN TEXT FORM, IT IS SLOWER THAN ^^FORTRAN\\ OR ASSEMBLER
LANGUAGE. ^HOWEVER, WHERE THE CALCULATION IS SHORT,
^^FOCAL\\ IS FAST ENOUGH TO BE USEFUL, AND SINCE ONLY
^^FOCAL\\ IS EXECUTING, NO OTHER OVERHEAD IS IN THE
SYSTEM; ^^FOCAL\\ IS EDITOR, COMPILER, TASKBUILDER AND
TASK ALL IN ONE.
.PARAGRAPH
^WE WILL INTRODUCE SOME ^^FOCAL\\ COMMANDS NOW IN A
(HOPEFULLY) USEFUL ORDER. ^THE MORE COMPLEX COMMANDS
WILL BE LEFT TO ^^FOCALRSX.DOC\\. ^COMMANDS PERTAINING
TO THE MULTI-USER ^^FOCAL\\ WILL BE DESCRIBED HERE.
.SKIP 2
.TEST PAGE 10
.CENTER
^^FOCAL COMMANDS\\ (^SHORT ^VERSION)
.SKIP 1
.PARAGRAPH
^THE FIRST COMMAND ONE LEARNS IN ^^FOCAL\\ IS ^^TYPE\\.
^ITS FORMAT IS:
.SKIP 1
^^TYPE [\\EXPRESSION]
.SKIP 1
WHERE "EXPRESSION" CAN BE ANY MATHEMATICAL EXPRESSION
IN THE NORMAL ^^FOCAL\\ FORM.
.PARAGRAPH
^EXAMPLES MIGHT BE:
.SKIP 1
.NOFILL
^^TYPE 5+5
   10.0000
TYPE 250/2
  125.0000
TYPE "HELLO. 45 TIMES 3 IS ",45*3
 HELLO. 45 TIMES 3 IS  135.0000
\\
.FILL
.PARAGRAPH
^^FOCAL\\ USES CERTAIN SPECIAL CHARACTERS FOR OUTPUT
FORMAT CONTROL. "!" MEANS TYPE CARRIAGE RETURN, LINEFEED
AND "_#" MEANS TYPE CARRIAGE RETURN ONLY WITHOUT LINEFEED.
^IN ADDITION, TEXT IN DOUBLE QUOTES IS TYPED AS IT APPEARS,
AND THE PERCENT (%) KEY SPECIFIES THE FORMAT FOR NUMBERS.
^NUMBERS ARE PRINTED WITH %WW.DD SPECIFICATION AS HAVING
WW DIGITS AND DD DECIMAL PLACES. ^THUS, THE DEFAULT
FORMAT IS %8.04 [NOTE THAT THE 04 MUST BE IN THAT FORM
TO DISTINGUISH FROM 8.4 =8.40], AND ONE CAN OBTAIN AN "^E"
FORMAT OUTPUT BY THE COMMAD "^T %". ^^FOCAL\\ AUTOMATICALLY
OUTPUTS NUMBERS IN ^E FORMAT IF THEY ARE TOO LARGE FOR
ITS FORMAT. ^F^O^C^A^L MATH IS ACCURATE TO ABOUT 6 DIGITS,
AND WHILE IT CAN PRINT WIDER FIELDS, ONLY THE
FIRST 6 DIGITS ARE SIGNIFICANT.
.TEST PAGE 10
.PARAGRAPH
^MATHEMATICAL EXPRESSIONS ARE FORMED OF VARIABLES AND
NUMBERS ENTERED IN FREE FORM WITH THE USUAL RULES OF
ALGEBRAIC PRECEDENCE (FUNCTIONS, EXPONENTIATION, MULTIPLICATION,
DIVISION, ADDITION, SUBTRACTION). ^THE CODES FOR ARITHMETIC
OPERATIONS ARE AS FOLLOWS:
.SKIP 1
.NOFILL
.TAB STOPS 12,24
+	ADDITION
-	SUBTRACTION
*	MULTIPLICATION
/	DIVISION
_^	EXPONENTIATION (^^INTEGER POWERS ONLY!\\)
.FILL
.SKIP 1
^OPERATIONS MAY BE GROUPED WITH PARENTHESES TO FORCE
CALCULATIONS TO BE DONE AS DESIRED. ^FUNCTION CALLS
WILL BE EVALUATED IN THE STANDARD PRECEDENCE.
.SKIP 1
.TEST PAGE 12
.PARAGRAPH
^^FOCAL\\ FUNCTION NAMES ALWAYS START WITH THE LETTER "^F"
AND PERFORM MOST CALCULATIONS ONE NEEDS. FUNCTIONS AVAILABLE
ARE AS FOLLOWS (SOME ADDITIONAL ONES ARE AVAILABLE):
.SKIP 1
.NOFILL
.TAB STOPS 20,30
^^FSQT(X)	SQUARE ROOT OF X
FSIN(X)	SINE OF X, X IN RADIANS
FCOS(X)	COSINE OF X,X IN RADIANS
FLOG(X)	NATURAL LOGARITHM (BASE E) OF X
FEXP(X)	EXPONENTIAL OF X
FATN(X)	ARCTANGENT OF X IN RADIANS
FRAN()	RANDOM NUMBER BETWEEN -1 AND 1
FAND(I,J)	BINARY AND OF 2 INTEGERS
FIOR(I,J)	BINARY INCLUSIVE OR OF 2 INTEGERS
FITR(X)	INTEGER PART OF X (FORMED BY
	TRUNCATING THE FRACTION)
FSGN(X)	+1 IF NUMBER IS +, -1 IF -,
	0 IF ZERO.
FADR(SUBSCR,VAR)	ADDRESS OF VECTOR ELEMENT
FCHR(-1)	READS A CHARACTER OFF INPUT DEVICE
FCHR(X)	OUTPUTS ASCII CODE X TO TI:
FSBR(GROUPNO,ARG)	EXECUTES GROUP "GROUPNO"
	WITH VARIABLE "_&" SET TO ARG.
	FINAL VALUE OF _&
	IS THE VALUE RETURNED FROM FSBR.
FDAY()	RETURNS A VALUE OF
	DD+32*(MM+12*YY), WHERE THE
	DATE WOULD BE EXPRESSED
	AS DD/MM/YY TO THE SYSTEM.
FCLK()	RETURNS THE NUMBER OF SECONDS
	SINCE MIDNIGHT FROM THE SYSTEM.
.FILL
\\

.TEST PAGE 10
.SKIP 1
.PARAGRAPH
^WHEN YOU LEARN TO EVALUATE EXPRESSIONS, YOU MAY WANT
TO WRITE PROGRAMS. ^^FOCAL\\ PROGRAMS ARE ENTERED BY TYPING
IN LINES WITH LINE NUMBERS IN THE FORM GG.LL.
.PARAGRAPH
^THE "GG" IN THE LINE NUMBER IS CALLED THE "GROUP" OF LINES,
AND WHERE ALL LINES IN A GROUP ARE TO BE REFERRED TO, THE
LINE NUMBER ZERO (0) IS USED; HENCE LINE NUMBERS MUST BE
NONZERO WHEN ENTERED. ^THE "LL" IS THE "LINE NUMBER" AND
UP TO 2 DECIMAL PLACES ARE PERMITTED. ^LINES MAY BE ENTERED
IN ANY ORDER, BUT ARE EXECUTED IN STRICTLY ASCENDING
ORDER. ^IF A SECOND LINE IS ENTERED WITH THE SAME LINE NUMBER
AS THE NUMBER OF A LINE ALREADY ENTERED, THE OLD LINE IS
DELETED AND THE NEW ONE REPLACES IT. ^THE ^WRITE COMMAND
MAY BE USED TO LIST LINES ENTERED ALREADY TO SEE WHAT HAS
BEEN ENTERED.
.TEST PAGE 10
.PARAGRAPH
^^FOCAL\\ VARIABLES MAY BE AS LONG AS DESIRED, BUT THE FIRST
CHARACTER MUST NOT BE A NUMBER, AND SINCE ^^FOCAL\\ RETAINS
ONLY THE FIRST 2 CHARACTERS TO IDENTIFY A VARIABLE, THE FIRST
2 CHARACTERS OF VARIABLE NAMES MUST BE UNIQUE. VARIABLES
MAY HAVE ZERO, ONE, OR TWO DIMENSIONS, THOUGH ^^FOCAL\\ WILL
ONLY ACTUALLY ALLOCATE THE VARIABLES THAT ARE REFERENCED.
^NEWLY REFERENCED VARIABLES ARE AUTOMATICALLY ZERO WHEN
CREATED, SO ONE NEED NOT ZERO THEM AT THE START OF A
PROGRAM. ^IF A VARIABLE HAS 1 DIMENSION, THAT DIMENSION
MUST BE BETWEEN -32768 AND 32767; IF IT HAS 2 DIMENSIONS,
EACH MUST BE BETWEEN -128 AND +127. ^NOTE FINALLY THAT
A SCALAR VARIABLE IS THE SAME AS ONE WITH DIMENSION 0.
^THAT IS, ^A, ^A(0), AND ^A(0,0) ARE ALL THE SAME VARIABLE.
(^THERE IS A CONDITIONAL ASSEMBLY IN ^^FOCAL\\ TO MAKE THEM
DIFFERENT, HOWEVER. ^IF IT HAS BEEN USED, ALL THESE WILL BE
DISTINCT (AS IS THE CASE IN ^^BASIC\\), AND MAY BE SEPARATELY
ALLOCATED. ^A SIMPLE TEST AT THE CONSOLE WILL TELL YOU WHETHER
YOUR VERSION OF ^^FOCAL\\ HAS BEEN ASSEMBLED THIS WAY.)
.TEST PAGE 10
.PARAGRAPH
^^FOCAL\\ RESERVES SOME VARIABLES THAT MAY NEVER BE ERASED, FOR USE
IN COMMUNICATING BETWEEN CHAINED PROGRAMS. ^THEY ARE NORMAL ^^FOCAL\\
FLOATING POINT SCALAR NUMBERS, NAMED _&A THROUGH _&Z INCLUSIVE. ^NOTE THAT
WHERE THE "EXTENDED SYMBOL TABLE" OPTION OF ^^FOCAL\\ IS SELECTED,
_&A(0) WILL NOT USE A SYSTEM VARIABLE, THOUGH _&A WILL.
.TEST PAGE 10
.PARAGRAPH
^SOME EXAMPLES OF ^^FOCAL\\ PROGRAM TEXT MIGHT BE:
.NOFILL
.SKIP 1
^^
1.10 C: GIVEN PHOTON ENERGY, GIVE OUTGOING PROTON
1.15 C: ENERGY FOR O16
1.20 ASK "TYPE IN PHOTON ENERGY IN MEV ",K
1.30 ASK "TYPE IN SCATTERING ANGLE, DEGREES:",DEG
1.40 SET THETA=DEG/57.29578
1.50 SET Q=12.126
1.60 SET MRESID=13972.27
1.70 SET A=K*FCOS(THETA)
1.80 SET B=938.256;C: MASS OF PROTON
1.90 SET C=B+MRESID-Q+K
2.10 SET D=MRESID*(K-Q)-Q*(K-Q/2.)
2.20 SET EP=(C*D+A_^2*B+A*FSQT(A_^2*B_^2+2*B*C*D+D_^2))
2.30 SET EP=EP/(C*C-A*A)
2.40 TYPE "THE PROTON ENERGY IN MEV IS ",EP,!
2.50 SET EMOM=FSQT((EP+B)_^2-B_^2)
2.60 TYPE "THE PROTON MOMENTUM IN MEV/C IS ",EMOM,!
2.70 SET RQ=FSQT(EMOM_^2+K*K-2*EMOM*K*FCOS(THETA))
2.80 TYPE "THE INITIAL MOMENTUM IN MEV/C IS ",RQ,!
2.90 ASK "DO YOU WANT ANOTHER CASE?[YES/NO] ",KC
3.10 IF (KC-0YES) 3.2,1.1,3.2;C: END OR GO BACK
3.20 TYPE "THANKS. ALL DONE. ",!;QUIT
.FILL
.TEST PAGE 10
.SKIP 1
.PARAGRAPH
T\\HE ABOVE IS ACTUALLY A COMPLETE CALCULATION AND SHOWS A
FEW OF THE VARIABLES AND LINE NUMBERING SCHEMES USED.
^NOTICE THAT LINES 2.00 AND 3.00 ARE ILLEGAL AND NOT
PRESENT, AND THAT (AS IS GOOD PRACTICE) LINE NUMBERS
HAVE BEEN LEFT BETWEEN LINES. ^IT IS POSSIBLE TO
RENUMBER A ^^FOCAL\\ PROGRAM, BUT IT IS RATHER
PAINFUL, AND ONE SHOULD TRY TO AVOID HAVING TO DO IT.
.TEST PAGE 10
.PARAGRAPH
^THE MOST COMMON ^^FOCAL\\ COMMAND IS THE ^^SET\\ COMMAND,
WHICH FUNCTIONS EXACTLY AS THE ^^FORTRAN\\ ASSIGNMENT
STATEMENT DOES. ^ITS FORM IS:
.SKIP 1
^^SET#V\\ARIABLE=EXPRESSION
.SKIP 1
WHERE THE EXPRESSION MAY BE ANY MATHEMATICAL EXPRESSION
INCLUDING CONSTANTS, ^^FOCAL\\ VARIABLES, OR ^^FOCAL\\
FUNCTIONS. ^THE EXPRESSION MUST BE ALL ON ONE LINE.
.PARAGRAPH
^TO ENTER NUMBERS INTO A CALCULATION, ^^FOCAL\\ PERMITS A
RATHER SIMPLE FORM OF DATA ENTRY VIA THE ^^ASK\\ COMMAND.
^ONE USES ^^ASK\\ TO PROMPT THE USER IF DESIRED AND READ IN,
IN FREE FORM, HIS REPLY. ^THE GENERAL FORM OF ^^ASK\\ IS:
.SKIP 1
^^ASK "TEXT",V\\ARIABLE(S)
.SKIP 1
WHERE THE TEXT MAY BE OMITTED IF DESIRED. ^IF SPECIFIED,
THE TEXT WILL BE PRINTED AND ^^FOCAL\\ WILL PROMPT FOR
USER INPUT. ^OTHERWISE, ^^FOCAL\\ JUST TRIES TO READ INPUT.
.TEST PAGE 10
.PARAGRAPH
^THERE ARE SEVERAL USEFUL PECULIARAITIES OF ^^ASK\\ DUE
TO THE WAY IT IS IMPLEMENTED. ^THE USER INPUT IS FED INTO
^^FOCAL\\ WITH A 0 CHARACTER IN FRONT TO FORCE IT TO BE
TREATED AS A NUMBER. ^WHERE CHARACTERS ARE INPUT, THEY ARE
TREATED AS NUMBERS BY TAKING THE LOWER 5 BITS OF THEIR
^^ASCII\\ CODES AND TREATING THE CHARACTERS A THROUGH Z AS
1 THROUGH 26. ^THUS, ANY CHARACTER BUT ^E BECOMES A
NUMBER AND ^E IS USED AS AN EXPONENTIATION CHARACTER.
^THUS, A REPLY OF "^^YES\\" TO AN ^^ASK\\ COMMAND
MAY BE TESTED FOR IN AN ^^IF\\ STATEMENT (SEE BELOW)
BY COMPARING WITH "0^^YES\\". ^SINCE ^Y REPRESENTS 25.
AND ^S REPRESENTS 19., A "^^YES\\" REPLY IS ENCODED AS
25^E19. ^WHERE IT IS DESIRED TO ENTER AN EXPRESSION FOR
^^FOCAL\\ TO EVALUATE, ONE NEED ONLY PUT A + OR - 
AS THE FIRST CHARACTER OF INPUT. ^THIS CAUSES ^^FOCAL\\ TO
PERFORM A NORMAL EVALUATION USING ANY SYMBOLS IT HAS
DEFINED. ^THUS, RESULTS ARE: (TO "^^ASK A\\")
.SKIP 1
.NOFILL
.TAB STOPS 14,25
^^REPLY	VALUE
25	25
NO	14*10+15=155.
+FSQT(25)	5
.FILL
.SKIP 1
\\
.TEST PAGE 10
.PARAGRAPH
^^FOCAL\\ IS ABLE TO TEST EXPRESSIONS AND TRANSFER CONTROL
DEPENDING ON THEIR SIGN. ^THIS IS DONE VIA THE ^^FOCAL IF\\
STATEMENT. ^ITS FORMS ARE:
.SKIP 1
^^IF (EXPRESSION)G1.L1,G2.L2,G3.L3
.BREAK
IF (EXPRESSION)G1.L1,G2.L2;(MORE STATEMENTS)
.BREAK
IF (EXPRESSION)G1.L1;(MORE STATEMENTS)
.SKIP 1
\\
WHERE "^G1.^L1" THROUGH "^G3.^L3" ARE ^^FOCAL\\ LINE NUMBERS
(OR GROUP NUMBERS WHERE THE FIRST LINE OF THE GROUP
IS TO GAIN CONTROL IF DESIRED). ^CONTROL GOES TO THE
DESIGNATED LINE IF THE EXPRESSION IS NEGATIVE, ZERO,
OR POSITIVE FOR ^G1.^L1, ^G2.^L2, OR ^G3.^L3 RESPECTIVELY. ^NOTE
THAT ^^IF\\ IS NOT RECURSIVE; CONTROL GOES TO THE DESIGNATED
LINES AND DOES NOT RETURN. ^IN THIS IT CLOSELY RESEMBLES
THE ^^FORTRAN\\ "^^ARITHMETIC IF"\\ STATEMENT.
^WHERE THE ^^IF\\ IS TRUNCATED (THE SECOND 2 FORMS), CONTROL
"FALLS THROUGH" TO THE NEXT LINE(S) IF THE EXPRESSION IS
POSITIVE (2ND FORM) OR NON-NEGATIVE (3RD FORM). 
.TEST PAGE 10
.PARAGRAPH
^WHERE THE USER WANTS CONTROL TO RETURN FROM THE LINE(S)
TRANSFERRED TO, HE MAY USE THE "^^JUMPON\\" FORM OF ^^IF\\,
WHICH IS IDENTICAL EXCEPT THE CONTROL TRANSFER IS
VIA A SUBROUTINE CALL SO CONTROL EVENTUALLY RETURNS TO
THE COMMAND AFTER THE ^^JUMPON\\ AFTER WHATEVER STATEMENTS
WERE TO BE EXECUTED ARE DONE. ^THE FORM NORMALLY USED IS:
.SKIP 1
^^JUMPON (EXPRESSION) \\G1.L1,G2.L2,G3.L3
.SKIP 1
THOUGH ALL LEGAL FORMS AS IN ^^IF\\ SHOULD WORK.
.TEST PAGE 10
.PARAGRAPH
^TO MAKE PROPER USE OF ^^FOCAL\\ ARRAYS, ONE MUST BE ABLE TO
LOOP. ^THE ^^FOCAL\\ FORM OF LOOPING IS VIA THE ^^FOR\\
STATEMENT, OF FORM:
.SKIP 1
^^FOR VARIABLE=LO,[INC,]HIGH; STATEMENTS ON SAME LINE\\
.SKIP 1
WHERE THE STATEMENTS ON THE REST OF THE LINE ARE TO BE
EXECUTED FOR VALUES OF THE VARIABLE FROM "^^LO\\" TO
^^"HIGH\\", AND "^^INC\\" MEANS 
"INCREMENT". ^SINCE THE LINE MAY NOT BE LONGER
THAN 80 CHARACTERS, IT IS USUAL TO USE THE ^^FOCAL\\ ^^DO\\
COMMAND TO ALLOW LONGER SEQUENCES TO BE CONTROLLED.
^NOTE THAT THE TEXT INCLUDED IN THE LOOP IS ONLY THAT ON THE
REMAINDER OF THE LINE; IT DOES NOT INCLUDE ANY FOLLOWING LINES,
ALTHOUGH THE USE OF THE ^^DO\\ COMMAND WILL ESSENTIALLY REMOVE
THE RESTRICTION ON LENGTH SO IMPOSED. ^THE PECULIARITY THIS
INDUCES IS THAT THE BODY OF A LOOP IS NOT ADJACENT TO THE
LOOP - CONTROLLING ^^FOR\\, BUT IS SOMEWHERE ELSE IN A DIFFERENT
GROUP OF ^^FOCAL\\ LINES, IN MOST CASES.
^AS AN EXAMPLE OF HOW TO USE ^^FOR\\, CONSIDER THE FOLLOWING 2
EXAMPLES:
.SKIP 1
^^FOR N=1,45;SET A(N)=N+FLOG(N);TYPE A(N),!
.BREAK
FOR N=1,45;DO 2.0
.SKIP 1
\\
^NOTICE THAT IN THE FIRST EXAMPLE, ^A(^N) WILL BE
CALCULATED AND TYPED FOR 45 VALUES OF ^N. ^IN THE SECOND
CASE, GROUP 2 WILL BE EXECUTED 45 TIMES WITH ^N RANGING
FROM 1 TO 45. ^ALL LINES IN GROUP 2 WILL BE DONE, AND
CONTROL WILL EVENUALLY PASS TO THE NEXT
STATEMENT.
^WHERE A COMPLICATED CONDITION SHOULD ALLOW ONE TO PREMATURELY
EXIT FROM A "^^FOR\\" LOOP, A SIMPLE ^^GOTO\\ WILL NOT WORK,
BUT WILL MAKE THE LINE AN EXTENSION OF THE GROUP BEING EXECUTED.
^TO ESCAPE A "^^FOR\\" LOOP, EXECUTE A "^^BREAK\\" COMMAND TO
GO UP ONE LEVEL OF ^^FOR\\ LOOPS. ^IF THERE IS NO ^^FOR\\
LOOP, THEN THE ^^BREAK\\ COMMAND IS AN ERROR AND ^^FOCAL\\
WILL BE QUIETLY RE-STARTED.
.TEST PAGE 10
.PARAGRAPH
^THE ^^FOCAL\\ ^^DO\\ COMMAND IS SIMPLY A RECURSIVE CALL
TO A LINE OR LINES, SO THAT CONTROL PASSES TO THE LINE(S)
SPECIFIED AND RETURNS WHEN THEY ARE DONE. ^ITS
FORM IS JUST:
.SKIP 1
^^DO\\ LINE-NUMBER OR GROUP-NUMBER
.SKIP 1
^EXAMPLES:
.SKIP 1
^^DO 1.3
.BREAK
DO 2.0
.BREAK
DO 4.5
.BREAK
DO 4
.SKIP 1
^THE ^^DO\\ COMMAND MAY BE NESTED TO ANY (REASONABLE)
DEPTH PROVIDED THAT THE RANGES OF INNER NESTS
ARE INSIDE THOSE OF OUTER NESTS (I.E., THE SAME IDEA
AS ^^FORTRAN\\). ^THE ^^DO ALL\\ COMMAND IN IMMEDIATE MODE
WILL CAUSE THE WHOLE PROGRAM TO BE EXECUTED AS A SUBROUTINE;
ONE MAY SINGLE-STEP A PROGRAM BY GIVING THE ^^DO\\ COMMAND
FOR EACH LINE; LINES WILL THEN BE EXECUTED ONE AT A TIME.
.TEST PAGE 10
.PARAGRAPH
^^FOCAL\\ SUPPORTS CONTROL TRANSFER VIA ^^GOTO\\ ALSO;
IT ACCEPTS THE STATEMENT:
.SKIP 1
^^GOTO GG.LL\\
.SKIP 1
AS MEANING TRANSFER CONTROL TO THE LINE ^^GG.LL\\
DIRECTLY. ^NOTE THAT IF THIS IS DONE FROM INSIDE A ^^DO\\,
THE END OF THE LINE WILL BE TREATED AS THE END OF THE ^^DO\\.
^LIKEWISE, INSIDE A ^^FOR\\ LOOP, A ^^GOTO\\ ONLY PASSES
CONTROL FOR ONE LINE. ^THE ^^BREAK\\ COMMAND WILL BREAK OUT
OF A ^^FOR\\ LOOP, GOING UP ONE LEVEL, IF IT IS DESIRED TO
DO SO; THIS MUST BE USED INSTEAD OF A ^^GO TO\\ TO ACHIEVE
THE PURPOSE.
.PARAGRAPH
^ONE STARTS ^^FOCAL\\ PROGRAMS BY A SIMPLE ^^GO\\
COMMAND TO BEGIN AT THE START OF THE PROGRAM. ^^FOCAL\\
PROGRAMS SHOULD END IN ^^QUIT\\ TO TERMINATE EXECUTION, THOUGH
THIS WILL BE ASSUMED IF OMITTED.
^^FOCAL\\ HAS A TRACE MODE WHICH IS ACTIVATED BY STARTING UP
WITH ^^?GO\\ RATHER THAN JUST ^^GO\\.
.TEST PAGE 10
.PARAGRAPH
^YOU CAN COMMENT YOUR ^^FOCAL\\ PROGRAMS BY PUTTING STATEMENTS
BEGINNING WITH THE ^^COMMENT\\ (OR JUST ^C IF YOU LIKE) COMMAND.
^THIS COMMAND CAUSES ^^FOCAL\\ TO IGNORE THE REST OF THE LINE.
^NOTICE THAT MULTIPLE STATEMENTS ON A LINE AFTER A COMMENT WILL
BE IGNORED. ^THIS IS THE ONLY CASE WHERE ^^FOCAL\\ IGNORES
SEMICOLONS. ^NORMALLY, THEY DELIMIT MULTIPLE COMMANDS ON A LINE.
.TEST PAGE 10
.PARAGRAPH
^^FOCAL\\ IS ABLE TO DELETE VARIABLES OR PROGRAM TEXT BY THE
^^ERASE\\ COMMAND. ^THIS COMMAND HAS 4 FORMS:
.SKIP 1
.LEFT MARGIN 15
.INDENT -8
^^ERASE\\ ERASES VARIABLES ONLY. ^^ERASE\\ WILL ALSO CLEAR ANY
PRESET AMOUNT OF ^^VECTOR\\ SPACE
.INDENT -8
^^ERASE#NN.NN\\ ERASES SOME TEXT, AND VARIABLES. ^IF A LINE NUMBER IS
ENTERED, THAT LINE IS ERASED. ^IF A GROUP NUMBER IS ENTERED, ALL LINES
OF THAT GROUP ARE DELETED. 
.INDENT -8
^^ERASE#ALL\\ ERASES BOTH VARIABLES AND ALL TEXT. ^ALL OF ^^FOCAL\\'S PROGRAM
STORAGE AREA IS RE-INITIALIZED.
.INDENT -8
^^ERASE TEXT\\ ERASES ALL PROGRAM TEXT BUT LEAVES ALL VARIABLES ALONE.
.SKIP 1
.LEFT MARGIN 5

.TEST PAGE 10
.PARAGRAPH
^TO GET OUT OF ^^FOCAL\\, ONE MAY EITHER TYPE CONTROL-^Z
OR HAVE ^^FOCAL\\ EXECUTE A ^^KILL\\ COMMAND. ^THE ^^KILL\\
COMMAND CAUSES IT TO EXIT FROM ^^FOCAL\\ BACK TO ^^RSX\\.
^THIS COMMAND WILL CLOSE ANY OPEN ^^LIBRARY\\
FILES AND ANY OPEN ^^OPERATE\\ FILES, AND
WILL ATTEMPT TO DISABLE ANY PENDING ^^FOCAL\\
INTERRUPTS AUTOMATICALLY, AND
CAUSE THE WHOLE ^^FOCAL\\ SYSTEM TO EXIT. ^BE SURE, WHEN
PROGRAMMING IT, THAT IT IS REALLY ^^KILL\\ YOU WANT, RATHER
THAN ^^QUIT\\, WHICH EXITS FROM YOUR PROGRAM BUT DOES NOT
REMOVE THE ^^FOCAL\\ SYSTEM AND HENCE LEAVES YOUR PROGRAM AND
VARIABLES FROM MEMORY.
.TEST PAGE 10
.PARAGRAPH
^TO READ IN OLD ^^FOCAL\\ PROGRAMS, ONE USUALLY WILL USE THE
COMMAND FORM:
.SKIP 1
^^@PROGRAM.FCL\\
.SKIP 1
^THERE ARE, HOWEVER, SOME FILE SERVICES TO PERMIT ACCESS TO THE
^R^S^X FILE SYSTEM. ^THESE ARE THE ^^LIBRARY\\ COMMANDS (AND ALSO
THE ^^USING\\ COMMANDS, DESCRIBED ELSEWHERE). ^THERE ARE 7
^^LIBRARY \\COMMANDS AVAILABLE:
.PARAGRAPH
^LIBRARY ^READ ALLOWS ONE TO READ ANY FILE FOR INPUT. ^THE FILE
IS TREATED EXACTLY AS THE CONSOLE, SO PROGRAMS OR ^^ASK\\ INPUT
MAY BE READ. ^THE FORM IS:
.SKIP 1
^^L#R#DV:[UIC]FILNAME.TYP;VER\\
.SKIP 1
AND MUST BE THE LAST COMMAND ON THE LINE. ^THE USUAL DEFAULTS
APPLY. ^IT IS INTENDED THAT NORMAL READ-BACK OF OLD ^^FOCAL\\
PROGRAMS BE VIA @, BUT THIS COMMAND IS PROVIDED TO PERMIT
OVERLAYING OF PROGRAMS AND/OR VARIABLES. ^A ^LIBRARY ^READ
IN A DATASET BEING READ VIA A ^LIBRARY ^READ CAUSES THE OLD
DATASET TO BE CLOSED AND THE NEW ONE OPENED. ^ONLY ONE LIBRARY
^READ DATASET MAY BE OPEN AT A TIME.
^NOTE THAT THE ^^LIBRARY\\ FILE WILL NOT ACTUALLY BE READ UNTIL
YOU GIVE THE ^^OPERATE A\\ COMMAND, AND IF YOU GIVE A COMMAND
^^OPERATE K\\, INPUT WILL COME FROM THE CONSOLE, THOUGH THE
LIBRARY INPUT DATASET WILL REMAIN OPEN AND POSITIONED.
.PARAGRAPH
^LIBRARY ^OPEN IS FOR OPENING OUTPUT FILES TO PREPARE TO WRITE
OUT PROGRAMS. ^IT DOES NOT WRITE ANYTHING, BUT PREPARES A FILE TO
RECEIVE DATA OR TEXT. ^ITS FORM IS:
.SKIP 1
^^L#O#DV:[UIC]FILENAME.TYP;VER\\
.SKIP 1
AND LIKE ^L ^R, IT MUST APPEAR AT THE END OF A LINE.
.PARAGRAPH
^LIBRARY ^WRITE AND ^LIBRARY ^TYPE PERMIT PROGRAM OR TEXT TO BE
WRITTEN TO THE OPENED OUTPUT FILE. ^THE SYSTEM STAYS
IN ^"LIBRARY" MODE UNTIL THE END OF THE LINE. ^HENCE, POSSIBLE
LINES WOULD BE:
.SKIP 1
.NOFILL
^^L W ALL
L W 3.0;W 4.0;W 6.0;T "T !",!
L W 3.5;W 6.2;W 9.1;W 12.0
\\
.FILL
.SKIP 1
^IN THE FIRST EXAMPLE, THE ENTIRE ^^FOCAL\\ PROGRAM IS WRITTEN
TO THE OUTPUT FILE. ^IN THE SECOND, GROUPS 3, 4, AND 6 ARE
WRITTEN AND A LINE READING ^^T#!\\ IS ADDED TO THE END. ^IN THE THIRD
EXAMPLE, SELECTED LINES OF THE ^^FOCAL\\ PROGRAM ARE WRITTEN TO
THE OUTPUT FILE.
.PARAGRAPH
^FINALLY, THERE IS PROVISION FOR CLOSING FILES OPENED.
^THE ^LIBRARY ^CLOSE STATEMENTS DO THIS. ^THEIR FORM IS:
.SKIP 1
^^L#C#I\\##########CLOSES ^L ^R INPUT FILE
.BREAK
^^L#C#O\\##########CLOSES ^L ^O OUTPUT FILE.
.SKIP 1
^THE ^L ^C ^I COMMAND ALSO DOES A ^^RCML$\\ TO CLOSE ANY INPUT
RESULTING FROM AN "@"-FORMAT INPUT READIN. ^SINCE INPUT IS DONE
A LINE AT A TIME, ^^FOCAL\\ MAY BE ABLE TO READ A FEW MORE CHARACTERS
AFTER A ^L ^C ^I FROM THE OLD FILE. ^THEY MAY BE FLUSHED USING
^^FCHR\\ AND LOOKING FOR ^CARRIAGE ^RETURN. ^IF NO FILE IS OPEN,
^LIBRARY ^CLOSE IS STILL NOT AN ERROR.
.PARAGRAPH
^FINALLY, IT IS USEFUL TO BE ABLE TO REMOVE FILES WRITTEN ERRONEOUSLY
TO BULK STORAGE. ^^FOCAL\\ IS ABLE TO DO SO VIA THE ^LIBRARY
^ERASE STATEMENT. ^UNLIKE A ^^PIP\\ DELETE, THE ^^FOCAL\\ DELETE
WILL DEFAULT THE VERSION NUMBER TO THE HIGHEST VERSION. (^IT
OPENS THE FILE FIRST, THEN DELETES IT.) ^A VERSION NUMBER
MAY BE ENTERED IF DESIRED, BUT * IS ILLEGAL. ^THE FORM
OF ^LIBRARY ^ERASE IS
.SKIP 1
^^L E DV:[UIC]FILENAME.TYP;VER\\
.SKIP 1
^CONTROL RETURNS AFTER DONE.
.PARAGRAPH
^FOR SIMPLICITY, A ^^LIBRARY XECUTE\\ COMMAND EXISTS THAT WILL
CHANGE THE ^^OUTPUT\\ DATASET TO THE LIBRARY FILE AND EXECUTE
A FUNCTION (AND ANY FOLLOWING LINE). ^THIS IS MAINLY TO SIMPLIFY
OPERATIONS WITH CHARACTER STRINGS, BUT MAY BE USED FOR ANY
PURPOSE THE USER WISHES.
.PARAGRAPH
^A NORMAL SEQUENCE OF COMMANDS TO SAVE A PROGRAM IS THEN:
.SKIP 1
.NOFILL
^^L#O#SY:NEWPGM.FCL
L#W#A
L#C#O\\
.SKIP 1
.FILL
^THESE COMMANDS CREATE ^^SY:NEWPGM.FCL\\, WHICH CAN BE READ IN
VIA A COMMAND "^^@SY:NEWPGM.FCL\\".
.SKIP 2
.TEST PAGE 10
.CENTER
^^VECTORS\\
.PARAGRAPH
^^FOCAL\\ HAS PROVISION FOR DATA CONSISTING OF VARIABLE NUMBERS OF
16-BIT WORDS IN NAMED, 1-DIMENSIONAL ARRAYS. ^THE ONLY RESTRICTIONS
ARE THAT SPACE FOR THESE ARRAYS MUST BE PRE-ALLOCATED, AND THE
SECOND LETTER OF THE ARRAY NAMES IS ALWAYS % (^PERCENT ^SIGN).
^TO USE THIS TYPE OF DATA, ONE USES THE ^^VECTOR\\ STATEMENT OF
^^FOCAL\\. ^THIS STATEMENT HAS THE FOLLOWING FUNCTIONS:
.LEFT MARGIN 15
.INDENT -8
1. ^ALLOCATE TOTAL SPACE FOR ALL VECTOR AND STRING ARRAYS IN
^^PDP\\11 16-BIT WORDS. ^THIS MUST BE DONE PRIOR TO DEFINING
^^ANY\\ VARIABLES, OF ^^ANY\\ KIND. ^THE FORMAT IS:
.SKIP 2
.INDENT -10
^^VECTOR#500\\
.SKIP 2
^TO ALLOCATE 500 WORDS FOR ALL VECTORS.
.INDENT -8
2. ^ALLOCATE A VECTOR. ^THIS STATEMENT MAY BE USED AS OFTEN AS DESIRED
AND IS DONE ONCE FOR EACH VECTOR USED. ^IT SETS UP THE VECTOR, FILLS
IT WITH ZEROES AND PUTS THE VECTOR'S DATA ADDRESS (SUBSCRIPT 1) INTO
ITEM 0 OF THE VECTOR. ^THE FORMAT IS:
.SKIP 2
.INDENT -10
^^VECTOR V(50)\\
.SKIP 2
TO GENERATE A VECTOR CALLED ^V% WITH 50 WORDS OF DATA MAXIMUM (HIGHEST
LEGAL SUBSCRIPT=50).
.INDENT -8
3. ^CREATE A BYTE VECTOR OUT OF A PREVIOUSLY INITIALIZED INTEGER
VECTOR. ^THIS ONLY CHANGES THE ADDRESSING TO BYTE ADDRESSING 
(UNSIGNED 8-BIT INTEGERS) STARTING IN THE HIGH BYTE OF WHAT WAS
VECTOR (1). ^THE FORM IS:
.SKIP 2
.INDENT -10
^^VECTOR "^V%\\
.SKIP 2
TO CHANGE VECTOR ^V% FROM INTEGER TO BYTE. ^ONE MAY ALSO CHANGE THE
OTHER WAY.
.INDENT -8
4. ^CONVERT A BYTE VECTOR TO AN INTEGER VECTOR. ^THE FORM IS:
.SKIP 2
.INDENT -10
^^VECTOR _#^V%\\
.SKIP 2
TO CHANGE ^V% TO AN INTEGER VECTOR. ^IN CASES OF CHANGING VECTOR ADDRESSING
MODES, THE PREVIOUS CONDITION IS IGNORED.
.LEFT MARGIN 5
.TEST PAGE 10
.PARAGRAPH
^TO USE THESE VECTORS, THE FUNCTION ^^FADR\\ IS DEFINED. ^^FADR\\
HAS 2 ARGUMENTS -- A SUBSCRIPT OF A VECTOR, AND THE VECTOR NAME.
^^FADR(NN,^V%)\\ WILL RETURN THE VIRTUAL ADDRESS OF THE VECTOR ELEMENT
GIVEN, FOR ACCESS VIA ^^FX\\ OR OTHER FUNCTIONS. ^VECTORS ARE MAINLY TO
BE USED WITH BINARY DATASETS (IN CONNECTION WITH THE ^^USING\\
STATEMENT, DESCRIBED IN ^^FOCALRSX.DOC\\) AND ASSEMBLY LANGUAGE
FUNCTIONS.
^VECTORS MAY HOWEVER BE USED ANYWHERE NORMAL ^^FOCAL\\ VARIABLES MAY
APPEAR, WITH THE RESTRICTION THAT VALUES STORED IN VECTORS WILL
BE INTEGERS ONLY. ^AS STRINGS, VECTORS MAY BE INITIALIZED BY
THE ^^HOLLERITH\\ STATEMENT, WHICH HAS THE FORM:
.SKIP 2
^^HOLL#V%(10),"STRING DATA TO FILL IN",A\\
.SKIP 2
^WHERE THE VECTOR SUBSCRIPT (10 IN THE EXAMPLE ABOVE) SAYS WHERE
THE FIRST BYTE OF THE STRING IS PUT, AND VARIABLE A WILL RETURN THE
LENGTH+1 OF THE STRING FILLED IN. ^THE LENGTH VARIABLE MAY NOT BE
AN ELEMENT OF A VECTOR.
.PARAGRAPH
^AN ENTIRE ^VECTOR MAY BE TYPED OUT VIA THE SPECIAL FORMAT OF
^^TYPE\\ THAT LOOKS LIKE THIS:
.SKIP 2
^^TYPE#'^V%'\\
.SKIP 2
.TEST PAGE 10
^FINALLY, THERE ARE SEVERAL FUNCTIONS THAT OPERATE ON STRINGS
SPECIALLY. ^THEY INCLUDE THE FOLLOWING:
.SKIP 1
.LEFT MARGIN 15
.INDENT -10
^^FS2N(S\\UBSCRIPT 1,^VECTOR NAME,^LENGTH) CONVERTS THE STRING
IN THE NAMED VECTOR TO A NUMBER AND RETURNS THE VALUE OF THE
NUMBER.
^THE STRING CONVERTED WILL USUALLY BE JUST A NUMBER, BUT IT MAY
BE ANY VALID ^^FOCAL\\ EXPRESSION AND IT WILL BE EVALUATED AND
CONVERTED.
.INDENT -10
^^FTRNS(^SUBFUNCTION,^VECTOR(SUBSCRIPT),^LENGTH) WILL CONVERT ANY
STRING TO INTERNAL ^^FOCAL\\ REPRESENTATION. ^SINCE ^^FS2N\\ WILL
EVALUATE FULL EXPRESSIONS ONLY IF THEY ARE IN INTERNAL FORM, THIS
FUNCTION IS USEFUL. ^IF THE SUBFUNCTION IS 0, THE CONVERSION IS
FROM ^^ASCII\\ TO ^^FOCAL\\ INTERNAL FORM; IF THE SUBFUNCTION IS
NON-ZERO, THE CONVERSION IS FROM ^^FOCAL\\ INTERNAL FORM TO
^^ASCII\\.
.INDENT -10
^^FN2S(N\\UMBER,^VECTOR,^SUBSCRIPT) MAKES A STRING OUT OF A NUMBER
AND SAVES IT IN ^VECTOR STARTING AT ^SUBSCRIPT, IN THE CURRENT
FORMAT. ^THE FUNCTION RETURNS THE LENGTH OF THE STRING CREATED.
.INDENT -10
^^FSTRD(S\\UB,^VECTOR,^MAXLEN) READS ^^ASCII\\ INTO A STRING STARTING
AT ^SUB AND RETURNS THE LENGTH READ. ^THE LENGTH MAY NOT EXCEED
^MAXLEN.
.INDENT -10
^^FSTWT(S\\UB,^VECTOR,^LENGTH) TYPES TEXT FROM A VECTOR STARTING AT
SUBSCRIPT ^SUB.
.INDENT -10
^^FINDS(S\\UB1,^VECTOR1,^LEN1,^SUB2,^VECTOR2,^LEN2) LOOKS
IN VECTOR ^VECTOR2 STARTING AT ^SUB2 FOR ^LEN2 BYTES AND TRIES
TO FIND THE STRING IN ^VECTOR1 STARTING AT ^SUB1 FOR ^LEN1
BYTES. ^IF IT FINDS THE STRING, THE FUNCTION RETURNS THE SUBSCRIPT
IN ^VECTOR2 OF THE FIRST BYTE OF THE MATCHING SUBSTRING. ^OTHERWISE
IT RETURNS 0.
.INDENT -10
^^FCMPS(S\\UB1,^VECTOR1,^LEN,^SUB2,^VECTOR2) COMPARES THE STRING IN
^VECTOR1 (DEFINED AS ABOVE) WITH THAT IN ^VECTOR2 (ALSO DEFINED
AS ABOVE) AND RETURNS 1 IF THEY ARE EQUAL, 0 OTHERWISE.
.INDENT -10
^^FMOVB(S\\UB1,^VECTOR1,^SUB2,^VECTOR2,^LEN1) MOVES A STRING IN
^VECTOR1 INTO ^VECTOR2 STARTING AT ^SUB2 FOR ^LEN1 BYTES, WHERE
THE DATA IN ^VECTOR1 STARTS AT SUBSCRIPT ^SUB1.
.LEFT MARGIN 5
.PARAGRAPH
^A FEW FUNCTIONS ARE AVAILABLE THAT ARE USEFUL WITH EITHER TYPE
OF DATA, GOING BY ADDRESSES.
.SKIP 1
^^FLIM(DATA ADDR,WC,LO,HI,DEFAULT)\\ WILL START AT "^DATA ^ADDR"
FOR ^^WC\\ WORDS AND IF THE NUMBER IS NOT BETWEEN ^^LO\\ AND ^^HI\\
IT SETS THE WORD TO ^^DEFAULT\\.
.SKIP 1
^^FMOV(IN.ADDR,WC,OUT.ADDR)\\ MOVES DATA FROM ^IN.ADDR TO ^OUT.ADDR
FOR ^^WC\\ WORDS.