Digital PDFs

XX-3C557-7D

2000

39 pages

Original

3.2MB

Document:	FOCAL-17 Wrege - How to Write New Subroutines and Use Internal Routines
Order Number:	XX-3C557-7D
Revision:
Pages:	39
Original Filename:	http://bitsavers.org/pdf/dec/pdp8/focal/FOCAL-17_Wrege_-_How_to_Write_New_Subroutines_and_Use_Internal_Routines.pdf

OCR Text

II
l

FOCAL

I.'

HOW TO WRITE NEW SUBROUTINES
AND USE INTERNAL ROUTINES

l I

I.
' l

•

'
'

j '

lI
t
f

DOUG WREGE
Engineering Experiment Station
Georgia Institute of Technology
Atlanta ,Georgia

TABLE OF CONTENTS
FOCAL: HOW TO WRITE NEW SUBROUTINES AND USE INTERNAL ROUTINES
ABSTRACT
I. INTRODUCTION
II. ASSEMBLERS, COMPILERS, AND INTERPRETERS
Ill. THE PHILOSOPHY OF FOCAL
A.
B.
C.
D.

Text Editing
The Multiple Branch Routine
Recursion
Conclusion

-IV. TECHNICAL DETAILS; GENERAL

A.
8.
C.
D.

Arithmetic Manipulation
Storage - (Core layout)
Holes
Moving Bottom

V. TECHNICAL DATA - FOCAL SUBROUTINES
A.
B.
C.
D.
E.

Page Zero Reference Locations
Text Handling Routines
Utility
Pushdown List Controllers
Other Subroutines

VI. LINKS TO FOCAL
A. Functions
B. Links to FOCAL - The LIBRARY Command
C. Debugging
VII. ACKNOWLEDGMENTS
VIII. APPENDIX A
A. A Prescription
IX. APPENDIX B
A. A Few Useful Routines
1. Argument Evaluator
2. LIBRARY Expansion
3. Function-command Extention

X. APPENDIX C
A. Example of a Recursive Subroutine - EVAL
B. Simplified Flowchart of Subroutine EVAL
XI. APPENDIX D
A. Field One Variable Array
·
1 • Abstract
2. Requirements
3. Usage
a. loading
b. Calling sequence
4. Discription
XII. APPENDIX E
A. Disk Variable Storage
1. Abstract
2. Comments
XIII. APPENDIX F
A. Hints and Kinks Department

FOCAL: HOW TO WRITE NEW SUBROUTINES
AND USE INTERNAL ROUTINES*

DECUS Program Library Write-up

FOCAL-17

ABSTRACT
It is the aim of this paper to help the user to code specific routines in FOCAL so that his
dialect 6f FOCAL can be oppl ied to his oppl icotion (without being forced to understand in
detail all the workings of FOCAL). In this way, perhaps, each and every user can make
his particular dialect of FOCAL 'perfect'.
I.

INTRODUCTION

. Many users hove found FOCAL** to be the answer to their real-time and computational
problems. The language is extremely powerful and flexible with unique text editing and
debugging features. Although FOCAL is slow in execution compared to machine language
coding, for most real-time problems or one-time calculations, lack of speed is not a serious
·handicap. Most users will agree that a program can be written, debugged, and executed in
"FOCAL" before the· equivalent could even be coded {and/or punched) in any other language.
Additions or changes ore easily made.
It will be assumed that the reader has a basic knowledge of PDP-8 processor instructions, PAL
mnemonics {see Digitol's Small Computer Handbook or Introduction to Programming), as well
as a familiarity with the Floating Point Package (DEC-08-YQYA-D). In addition, he should
be familiar with the "FOCAL"** language.
As many users hove discovered, the internal workings of FOCAL are on incredibly complex
piece of programming. With the need to interface the computer to specialized equipment for
individual oppl ications, there is the corresponding need for appropriate software. If FOCAL
could communicate with this equipment, one would hove on extremely powerful and flexible
computation and control package. This paper is on attempt to explain how user developed
software con be interfaced to the basic FOCAL package, without requiring the user to spend
valuable time trying to understand oil of its detailed workings.
Section II will deal with a general discussion of how FOCAL works, in a descriptive fashion.
Sectioi:t Ill will be concerned with the philosophy of the language. The lost few sections will
be more technically oriented toward helping the user actually code his additions. Finally,
several examples and ready coded routines, which may be used to simplify the user's problems,
are included.

*Supported in port by the U. S. Atomic Energy Commission.
**Throughout this paper a "FOCAL" program written in the "FOCAL" language wil I be
enclosed in quotes. The machine language coding of the FOCAL interpreter wi 11 be referenced
by the word FOCAL without quotes.

II. ASSEMBLERS, COMPILERS, AND INTERPRETERS
In general, there ore three routes that the programmer can fol low for machine execution. Programs
that pcrf'"'lrm translations ore assemblers, compilers, or interpreters; each operate from conceptually
different vantage points.
In a compiler level language, such as FORTRAN, ALGOL, and BASIC, coding is written in o syntax
closi:; to the way a human thinks. A compiler interprets this and generates on object code which is
close to machine language. This, in turn, is translated into actual machine language instructions.
Finally these machine language instructions must be read into core before execution. If any
corrections ore t~ be made to the. program (debugging, additions, or corrections), one must recompile
the 'ource coding, read the new object coding in, and finally execute it.
An assembly level language is inherently closer to machine language than a compiler level language.
The user's coding is indeed remote from the way he thinks about formulating a problem (he is even
forced to think in binary or octal, the machine's way of formulationg problems}. About all an
assembler lets the programmer do is use mnemonics (words} and symbols instead of binary numbers.
For example, in the PAL language, the instruction TAD I TEMP is assembled as follows from the
definitions:
TAD = l.0'00'8

/in the assembler's internal symbol table

I = 0'40'0'8

(internal symbol table

TEMP= 0'10'0's

/user defined in coding

The assembler masks out the first 5 bits from the last mnemonic
if there are more than one (in this case TEMP); it then ORS the
result with the other mnemonics:

10'0'0'
040'0'
& 0'10'0'

150'0

This is the machine equivalent.

The PAL assembler is a I ittle more sophisticated than this, of course, and performs functions a
little more complicated, but generally an assembler is incredibly stupid for what it can do. Note
the similarity between PAL mnemonics and machine language. Throughout the following sections
various mnemonics wil I be defined so that the PAL assembler con generate instructions compatible
with FOCAL (e.g. GETC = 450'6 causes the assembler to odd this to its symbol table).
In an interpretive level language, no machine language coding is generated for execution. An
interpreter is essentially a subroutine cal Ier. It contains a subroutine for every conceivable
ope;ation it thinks the user wishes to perform. If it cannot understand what the user wonts, it
pi-ii.ls an error message and waits for the user to make himself clear. Every character that the
11ser inputs is stored in core. Upon execution the interpreter "interprets" the program character
by character and calls the subroutine indicated.

FOCAL is an interpretive level language. In particular, it is a recursive interpreter (see
Section 111). That is, uni ike FORTRAN, one may cal I a function from within itself.
Nevertheless, it is basically a subroutine caller, even though these subroutines may be
incredibly interlocked. It hos a subroutine to evaluate arithmetic expressions (EVAL),
subroutines to make it recursive (PUSHJ, PUSHA, etc.), branching routines (SORT J),
a subroutine to find a certain line (GETLN), one to get a character (GETC), etc. Once
the user understands what all these routines do, he can odd his own coding in a highly
efficient and powerful manner. Descriptions of these subroutines will be given in later
sections.

Ill. THE PHILISOPHY OF FOCAL
A. Text Editing
Since FOCAL is on interpretive language, it must have facilities for manipulation of user
written text. In order to facilitate these manipulations, there are a number of text formatting
and editing features, such as WRITE, MODIFY, TYPE, and the "trace" (" ?") function. One
of the main features of the FOCAL interpreter is the simplicity of concept and power of operation
of the format controlling statements. The user finds a convenient, easily understood way of
control Iing the format of his output, regardless of his level of programming experience and
sphistication.
Since much of FOCAL execution is involved in various text decoding routines, FOCAL is slow
in execution of programs (compared to assembly or compiler language coding}. The text handling
routines may be cal led from the user written assembly language subroutines, and thus are Iisted
with a short description of their function, in Table 1.
FOCAL is concerned with interpreting what the user's text means by specific combinations of
characters, so it must have a flexible means of decoding these characters according to type.
The most efficient way this can be done is to use a subroutine (SORTC) that compares the
present character with a Iist. It is necessary to have the address of the Iist as an argument for
this subroutine. For example, suppose that it is desired to find a text terminator. To do this,
a list is made of all legal terminators(;, carriage return, space comma, etc.}, and the value
of the present character (stored in location CHAR) is compared to the Iist: if a match is found,
an index is set to the list element number, and a normal return is taken. If a match is not
found, then another return is taken.
8. The Multiple Branch Routine
FOCAL is in many ways similar to JOSS2. All of the JOSS-like languages incorporate a
"command" in addition to the arithmetic statements available in other languages (ALGOL,
FORTRAN). One of the advantages of the command is that, using only the first symbol of a
new statement, the interpreter (or compiler, int he case of BASIC) can decode the action
required, and thus need not "understand" the whole line before proceeding. This is an advantage
in a smal I machine such as the PDP-8, where the paucity of core demands highly efficient coding.
2 ..1oss - An Introduction to a Helpful Assistant, Rand Memos 5058-PR July 1966.

A Unique feature of FOCAL is the ability to operate with single-letter abbreviations of the
command. As an example, consider the subroutine that actually selects the command branches
(and is used for other operations within FOCAL, as well}. This routine (SORTJ} is called with
on argument pointing to the list of characters to be compared and another argument containing
a pointer to a list of associated addresses. FORTRAN programmers might recognize the result
as a sort of character-driven computed GOTO. The calling sequence is:
SORTJ
TABLEl-1
TABLE2-TABLE

/Sort and Branch Routine
/pointer to character Iist
/difference in addresses of the tables
/return if not in table

xxx

Absolute addresses are specified in the arguments; hence, tables may be stored between pages.
Since FOCAL refers to lists for its decoding operations, it is often referred to as o table driven
interpreter. A table driven interpreter is especially suited to addition of new coding, since only one
or two addresses need to be added to a table (I ist} for a new branch.
C. Recursion
One of the features of FOCAL which makes it so powerful is that of recursion. Recursion is the
ability of a subroutine to call itself, e.g. FSQT ( 1 - FSQT(X)). In most compiler level languages
this operation is carried out by repeating the machine language (FSQT} coding so that one version
of the subroutine can call the other. In thes'e cases the subroutine never really calls itself, rather
it calls a separate identical piece of coding. An interpretive level language cannot afford multiple
identical subroutines for every possiblity, since it would take too much core.
Consider how a 'normal', nonrecursive subroutine works. Schematically we may divide the subroutine into o segment in which the logical operations are coded and o segment where temporary
values in the calculation are stored. We con consider the subroutine return to be stored in this
temporary storage area also. VIZ,

SOT,

COOING

return oddr.
Intermediate
Variable
Storage

--~

- (~~ ~~"'!n!.!. (toke SQT of org.)

If this hypothetical. subroutine were to cal I another subroutine (as is normally done in assembly
language), there would be no difficulties provided that the intermediate storage of the two
subroutines are separate.
If the subroutine was to call itself from within its own coding, the original intermediate values of
the variables and the return pointer would be overwritten (as the program executes the coding the
second time}. If there was a way to use a different intermediate storage area, the original values
would not be lost.

The Push-Down List (POL) concept involves an intermediate storage area which is "pushed-down"
(making a new intermediate storage area available) whenever a subroutine is called and "poppedup" whenever a return occurs. VIZ,

STORAGE

AREA

COOING

J!!O!:. ~~'".!"!.!
(Storo!UI

oreos·1

SQT may be in

arvument

(take SQTof or9.)

---~:.-r

To continue the example, the steps in the evaluation of FSQT 1-FG.ST(X)) would proceed as
follows:
1. The main program cal Is the FSQT subroutine. Storage area 1 is now pusheddown into the push-down list making area 2 available.
2. The argument "1-" is evaluated up to the next FSQT(X).
In order to evaluate this, the FSQT subroutine is called again ~
3. On second entry to the subroutine, storage area 2 (containing the main
program return and the intermediate value of the argument) is pushed-down.
4. X is evaluated and then the square root is taken.
5. The subroutine returns (to the middle of itself} with the answer FSQT(X).
When this return is effected, storage area 2 is popped-back-up (with the
old intermediate values}.
6. The answer FSQT(X) is subtracted from 1 to form the argument 1-FSQT (X).
The square root of this is token and the function returns to the main program.
Obviously, by using the POL concept, subroutines may call themselves to any level (as long as
there is POL space available}.
For most·efficient core utilization, FOCAL uses the same POL intermediate storage for all subroutines. To do this, one value (PDP-8 word) is pushed-down at a time. Values are 'popped'
in the reverse or~er that they ore 'pushed'.
An additional feature of a POL is that it can be used for temporary storage of variables in nonrecursive routines. One may consider the POL as on extension of page zero since it can be accessed
from any page. Section V will describe POL handlers available in FOCAL.

D. Conclusion
The concepts outlined above will introduce the experienced programmer to the internal working
of FOCAL. In the sections that follow, a more technical exposition of these routines wi 11 be given.

TABLE 1
FOCAL TEXT HANDLERS

MNEMONIC

DESCRIPTION

GETC

Get the next character from the text

SORTC

Sort the present character against the table

TESTN

Sort the present character into one of three types

TES TC

Sort the present character into one of four other types

TESTLPR

Test CHAR from left parenthesis

RE ADC

Read a character from the Teletype

PRINTC

Print CHAR on Teletype

PAC KC

Pack a character into buffer (store it)

PRINTLN

Print the current line number

FINDLN

Find a given line

SPNOR

Ignore spaces

The Appendices contain examples elucidating the principles outlined in this report.
IV. TECHNICAL DETAILS - GENERAL
A. Arithmetic Manipulations
Arithmetic is done using the three word floating point format. Input and output of numbers
are handled via the Fleeting Point Package (FPP) 1/0 controller (with modifications to run
with the interrupt enabled). For details, see FPP documentation (DEC-08-YQYA-D).
B. Storage·- (Core layout) ·
The FOCAL interpreter occupies locations 1 - 3220 (see Figure 1). The FPP occupies
approximately 4600 - 7577, depending on how many functions are kept. The initial dialogue
sets BOTTOM, the end of storage space, depending on the number of functions kept. The
remaining storage is used for text, variable storage, and push-down Iists.
3220 - 4577

with all functions

3220 - 5177

FEXP, FLOG, FATN deleted

3220 - 5232

FSIN, FCOS and above deleted

The text is bui It up from location 3220 occupying approximately two characters per location.
Variables are built upward from the top of the text. They occupy 5 locations per variable
and are created as they are found in execution. Whenever the indirect program is changed,
(modified, appended, or collapsed), a new starting point for variables is indicated; hence,
old variables are erased. The push-down list (explained more fully later} is built from the
FPP down toward the variable storage area. Error messages occur with termination of the
program whenever these lists overlap.
Instructions are stored in the command/input buffer when in the command mode; the buffer
has sufficient locations for one I ine of characters.
C. Holes
The following locations are free for the user:
PAGE ZERO

FPP

16
162 - 175
171 - 175
5571 - 5577
5754 - 5777
6171 - 6177
7154 - 7177
7346 - 7377
7554 - 7577
6317 - 6377

(Auto Index Register)
(Free in 4K FOCAL)
(Free in SK FOCAL)

is used by the high-speed
reader control -- if you do
not have one, this is available

0000

PAGE ZERO
FOCAL
INTERPRETER

EXT. FUNCTIONS

6400

FLOATING
POINT

7600

PACKAGE
!LOADERS-MONITORS

7777
lEXT STORAGE FORMAT

VARIABLES FORMAT

LINE

A ]

SWSCRIPT

l 0

EXP

ASCII CHAR

MANTISSA

etc.

C.R.

Figure 1

D. Moving Bottom
For additional user coding room, BOTTOM may be changed at the sacrifice of text storage
To move BOTTOM, set the contents of locoti~n 27 (C(27)) to the lost location available for
text (POL) storage; e.g. in order to free locations 4420-4577 for user additions to the interpreter, change C (27) to 4417.

V. TECHNICAL DATA - FOCAL SUBROUTINES
With the use of subroutines available in the FOCAL interpreter and a listing, a must, it is
relatively simple to write powerful user coded additions.
Unless otherwise stated, these subroutines must be entered with the AC= fi; they return with the
AC= f$.
A. Page Zero Reference Locations
·CHAR -The contents of this location (142) contains the current character (in ASCII code)
from the text buffer.
SORTCN - This register contains references used by sorting routines (see below).
FLAC - This is the first word of the floating accumulator (contains the exponent). The floating
accumulator occupies locations 44 - 46.
FLAC is defined as 44.
B. Text Hand I ing Routines
GETC =4506
Gets next character from the text; exits with next character is CHAR.
SORTC= 4511
Calling sequence:

SORTC
LIST-1

/call
/address of LIST -1
/return if in LIST
/return if not in LIST

xxx
xxx
Description:

If the accumulator is nonzero, its contents ore used;
otherwise the contents of CHAR are used to sort against
the LIST. If it is in the LIST, return to cal I + 2; if not,
return to coll+ 3. SORTCN is set to how far down in the
Iist the match occurred.

Example:

If we are testing for one of the fol lowing:
LIST
254
273
215

T/77
9

/,
/;

/carriage return
/list is terminated by a negative
number

Assuming it is an error for CHAR not to be in the I ist,
the following coding applies:
SORTC
LIST -1

/sort against LIST
/address of LIST

SKP
/do an error exit as not in LIST

ERROR

If o match were found, SORTCN would have the values:
Contents of CHAR
-------

SORTCN Value

carriage return

1
2

by negative numbers.

Lists are term

PRINTC = 4512
Print the occumuluto1-; If the AC= ~ print the conients of CHAR.
READC = 4513
Read and echo a choracter from the keyboord.

Put it into CHAR.

SPNOR = 4521
Ignore spaces in text; exit with the first character that is not a space in CHAR.
ERROR= 4526
Used to exit upon error detection; transfers control to the command mode and terminates
execution; prints error message. (In the FOCAL listing there are ERROR2, ERROR3, and
ERROR4. Al I of these ore identical.)
TES TN
This subroutine is actually a series of SORTC 's with various returns:
CALL:

TES TN
return 1
return2
return3

/coll
/return if a period
/return if not a period or a number
/return if a number; SORTCN is set to the
binary equivalent.

This routine tests only CHAR.

AC must be 0.

TESTC
(4525)
This subroutine is actuol ly a series of SORTC's with various returns:

CALL:

TES TC
return 1
return2
return3
return4

/call
/terminator; SORTCN set according to TERMS
/number; SORTCN set as in TESTN
/function; (CHAR=F)
/alphabetic· character

SORTJ
(4510)
This subroutine is used as a multiple sort and branch routine. CHAR 'or the AC if nonzero)
is compared to a Iist. If it is in the Iist, an address is looked up and an effective JMP
ADDRESS is executed. If a match is not in the list, then return is to cal1+3.
CALL:

SORTJ
LISTl -1
LIST2-LIST1
RETURN

/ADDRESS of character list
/difference in the addresses of Iists
/return here if not in LISTl

An example of this is the FOCAL branch to a library command:
POPA
SORTJ
COMLIST-1
COMGO-COMLIST
ERROR2

/get command CHAR
/branch

COMLIST =.

COMGO=

323 /S

/ADDRESS OF SET CODING
SET
/ADDRESS OF FOR
FOR
IF
DO
GO
COMMENTS
ASK
TYPE
LIBRARY

/invalid command

where

306 /F
311 /I
304 /D
307 /G

303 /C
301 /A
324 IT
314 /L

(ASCII)

n77 /list is terminated by a negative number
NOTE: Lists are terminated by a negative number.

C. Utility
RTL6= 4520
Rotate the AC six pieces to the left.

D. Pushdown List Controllers
For those unfamiliar with more powerful processors than the PDP-8, the ideas of recursion
and pushdown lists are explained in Section II. These subroutines appear to simulate hardware
commands on more sophisticated machines I ike the PDP-10 and even use the same mnemonics

PUSHA= 4503
Puts the contents of the AC on the PDL; clears the accumulator.
POPA= 1413
Get the top entry on the PDL and put it in the AC. (Note: auto-index register 13 is the pointer
to the pushdown list; thus 'POPA' is actually TAD I 13.)

PUS HF= 4504
This is essentially three PU SHA 's and is used for storage of floating point data.

Coll:

PUS HF

ADRESS

/address of first location of three word floating point number.

POPF= 4505
The inverse of the PUSHF routine.
Call:

POPF

ADDRESS

/address of where to put data.

PUSHJ = 4501
This is the recursive subroutine call. The subroutine return is put on the POL and a .:!Mf. to the
subroutine address is executed.
Call:

PUS HJ
SUBROUTINE

xxx

/address of SUBROUTINE
/address of this location is
/stored on the PDL

POPJ =5502
Recursive subroutine return; the top element of the PDL is used as the effective address of the
return.

E. Other Subroutines
INTEGER
Enter via o JMS I INTEGER. This routine makes on integer out of the FLAC. The low order
part is in FLAC + 2, the high order part is in FLAC + 1. Al.so, returns with the low order part
in the accumulator.
EFUN31
This routine is the return from o function routine. It checks for o right bracket in CHAR ( 1 ) 1 )
and normalizes the floating accumulator. Enter via o JMP I EFUN31.
EVAL
This subroutine evaluates arithmetic expressions; because it is recursive, it must be called via:
PUS HJ
EVAL

xxx

/return

The subroutine return is to cal I+ 2 wit.h the floating point value of the expression it evaluated
in the FLAC. (How EVAL works is discussed in Appendix A.)
NOTE:

All temporary storage must be in the POL before colling EVAL. This data must be
restored ofter the return. (see Appendix for examples.)

VI. LINKS TO FOCAL

A. Functions
The general form of a function in "FOCAL" is FUNC(ARG 1,ARG2, ---). The function coding
is entered via a SORT J where the address in designated in the table:

FNTABF
XABS
XSGN
XINT
XDIS
XRAN
XDXS
XADC
ATN
EXP
LOG
SIN

/(376) in FOCAL-W 8/68
/address of FABS coding
/FSGN
/etc.

cos

SQT
NEW

/user defined function

To add a user coded fun.ction put the entry point of the function coding in the appropriate
location in the above table. FOCAL will branch to that location ofter the function name is
decoded,· and ARG 1 is evaluated in the floating accumulator (FLAC). To delet.,.-: function
from the Iist, replace the current contents with 2725.
13

When the function evaluation is complete, the answer must be left in the FLAC, and~ JMP I
EFUN31 executed. The EFUN31 routine will check to see if there is a right parenthesis(")")
in CHAR, and normalize the FLAC, before returning to the opproP,riate place in FOCAL. (See
Hints and Kinks, Section XIII A, if the answer is an integer.)
B. Links to FOCAL - the LIBRARY Command

FOCAL hos an unimplemented command, the LIBRARY command (SET, ASK, TYPE, etc. are
commands). The general form of a command is:
X

(any syntax allowable by coding).

For example the SET command's allowable syntax is:
SET

(variable)= (arithmetic expression).

To generate the link to the user's LIBRARY command, put the entry address in 1201. FOCAL
will enter via a JMPwith CHAR containing 2408 (a space). The following coding may be used
at the end of a LIBRARY command to space over extraneous characters too semicolon or carriage
return, which must be in CHAR before doing an effective JMP PROC to return to FOCAL:
SKP
GETC
SORTC
GLIST-1
JMP PROC
JMP. -4

/entry
/fetch the next character
/sort for a; or c.r.
/FOUND IT~
/not yet

C. Debugging
It hos always been a problem to debug FOCAL programs, as FOCAL runs with the interrupt on.
Recently, a DECUS program XOD (DECUS #8-89) became available. This program may be used
in field 1 to debug FOCAL in field 0 with the fol lowing patches mode by J. C. Alderman.
FIX UP XOD
Patch FOCAL
(field (!)
Patch XOD
(field 1)

0001
0175
6761
6762
6763
6764
6765
6766

5575
2603
5002
0002
5404
0003
6613
0004

VII. ACKNOWLEDGEMENTS
The author wishes to express his thanks to J. C. Alderman for his help in formulation of ideas
and text editing. Also, on emphatic "thank you" to Rick Merrill for the most beautiful program
in the world, FOCAL!

VIII.

APPENDIX A

A. A Prescription
To add a function:

1. Put the function address in FNT ABF.
2. Do coding.
a. Use POL for temporary storage
b. If more than one argument is needed:
PUS HJ
ARG
where ARG is a supplied subroutine (See Appendix B). ARG is
a subroutine which moves past commas and evaluates arithmetic
statements, leaving the result in the FLAC.
3. Put the functional result in the FLAC.
4. Return to FOCAL via JMP I EFUN31.
To odd the LIBRARY command:

1. Put the initial address in the contents of 1201
(for expansion of commands see Appendix B).
2. Exit from coding via on effective JMP PROC. Note: the contents of CHAR
must be either ; or a carriage return.

X. APPENDIX C
A. Example of a Recursive Subroutine - EVAL
The subroutine EVAL is an example of a recursive subroutine. The POL is used to defer
evaluation so that the arithmetic operations are performed according to operand priority.
In order to take care of bracketed quantities EVAL does the following:
if a left bracket occurs

- PUSHJ
EVAL
if a right bracket occurs - POPJ •

Given that EVAL evalueates arithmetic expressions, the above operations have the effect of
changing all bracketed quantities to evaluated numbers. Hence, all bracketed quantities
have now "gone away" and we are left with expressions like:
·

A+ B*C-D/E 't F.
Operand priority is assigned as fol lows:
opperation

priority level

1
2

3
4

A flow diagram approximating this subroutine is given in Figure 2.

IX. APPENDIX B
A. A Few Useful Routines

1. Argument evaluator
A common requirement, expeciolly in function additions, is o routine which test for and
evaluates additional arguments. The subroutine ARG (coded below), checks if the contents
of CHAR is a comma(,), moves post the comma, evaluates the argument, and returns to
call+ 3. If the contents of CHAR is anything other than a comma, return is to coll+ 2.

PUS HJ

Call:

ARG

xxx
xxx

/CHAR was not a comma
/return with ARG(next) in FLAC

TAD CHAR
/get CHAR
TAD MCOMMA
SZA CLA
/A comma?
JMP .+4
/yes: exit via POP J
PUSHJ
/move past comma and evaluate next arg.
EVAL-1
IAC
/increment return
POPJ
2.

LIBRARY expansion

As FOCAL hos only one 'extra' command character, LIBRARY, a routine to expand the number
of commands is useful. In this way the normal format:
L

(statement)

which al lows only one command branch, may be extended into the syntax:
L

(statement)

where X represents another command. A listing of this routine follows.

:s. Function-command extention
The user may desire to perform a branch within a function, e.g. ARG2 in the function call
FNEW (ARG 1,ARG2,ARG3, ---)may be used as a command letter to specify a branch to
perform different operations.
An example of a subroutine to do this follows. (see next page)
NOTE: The return to FOCAL from each branch must be via a JMP I EFUN31.
With the use of the last two routines, the number of commands and/or functions may be extended
to any level.

* cv~ ro+ 10
t..I!TP·f
/

"'731:''
/ C;):v; ~ A\1[· I--·F1CF ~ .S:1 F
/

TAD CHAF

SPACES
trFT CQ~XA~L

PtJSHA

/.STASn IT

fFTC
fJ?TC

/CFT ~FXT
/~OVF T1 TFY~I~ATOI

LifiPF1 SPN0F

/IG~0FF

CHAF

P.LI ~T- 1
!-~t<P

JV.P .-I'.
SPNi)fP:JPA
~-JETJ

/IC:\Jl)?F ~PACFS
/C:F1' C:JV.:"iA'llL CHM
I GO THFFF

CLI ~T- 1
f.·)LI ST-CLI ST
FF'f/)F

/:'J:JT DJ LI .ST

I
/

* 5S71

CLI ~:T= •
3::-'3

I Sl:.'AP

~Pf-

IFFST!)F
/PUT

320
7777

IC:J~MANC

LIST

TFRMI~~TOF

*f,171
rm.I 5T=.
S \:AF
rF~TOF

POT
I
I

I
/~1CPL

[FCODFI

CJ~XP~r

I
JV!~

I.\:TFrEr

IV!?~E

Pt 1 Si-!f~,

Prcv~FNT

I~TFCFf

I ~P:tJE IT
I C'JY:Vi P S!-i:WLL f E :-:E :·'.'i

TM Ci-l?":·
TAD :-JC').y,.;p.
S7.A CLP
F FrOFL!
C-FTC

FA.ST C·JV:.'l/'.'
:"" ~:AC L ~
IGFT CO~XA~[ Crl?f·

/~·11-Jf

~P:JOF

I I G\J 0 !· E

CH?':!
ptjSHP.

/STASH IT

TAC

S':lFTC

TFF'l ~:- I
•+3

J~>'; P

GETC
J:'1P

II ': L I ~ T

/CF1

\JF~T

P~[

IG\JOrE

• - Lt

:: Fl1\i 1 r
P·1P t,

II t:\JJ:·F ~·!:f:CE:
ICFT C')V::-'.A\l[· Ci-lPI

St);. . TJ
C'JV:"~ p:,; DS- 1
P['[;S- C 1:'E'1 fl\1[ s
1

EFFJf~
~t, C·)·;;:vi A,

IC')

/N1T

TO A:t·rr (jj:.} I .CTF
I~

LIST

- 25L!

} ')T :n :·~ :·

SIMPLIFIED FLOWCHART OF SUBROUTINE EVAL

putTHISOP

Ewklate a wriable

'C:.r

IN lASTOP

to
lc:MClt for brackets)

Cdlecll for termlnatoi s)
push-down
¥0rlable(FlAC)

qnswv In FLAC

vet THISOP

push-down
lASTOP

SORTC for priority

POP-up

new lASTOP

Figure 2

Two locations, LAS TOP and THISOP, contain the priority assignment of the present and lost
operands respectively. The steps in the evaluation of
A+ B*C-D/E't F
would be:
THISOP

LAST OP

FLAC

N.A.

evaluate A into FLAC; lastop
starts out 0.

plus has priority 1

PDL

0
1

EXPLANATION

THISOP higher than LASTOP;
put LASTOP and FLAC in POL

evaluate B into FLAC; put THISOP
into LASTOP

THISOP has priority 3 - *

0
8
1
A

THISOP higher than LASTOP;
put LASTOP and FLAC in PDL
put THISOP into LASTOP

0
3

evaluate C into FLAC

1
A

0
2

b
1

- has priority 2

0
C*B

1
A

do the last operation between
FLAC and top of PDL.

0
2

C*B

get new LASTOP from PDL

THI SOP

LAST OP

FLAC

POL

C*B

t
A

EXPLANATION
THISOP higher than LASTOP
put LASTOP and FLAC in POL
put THISOP in LASTOP

k1
2

C*B
1
A

evaluate D

k1
4

C*B

/ has priority 4

t
A

k1
4

2
C*B
1
A

THISOP higher than LASTOP
put LASTOP and FLAC in POL
put THISOP into LASTOP

k1
5

0
2
C*B
1

has priority 5
evaluate E

k1
E
4
0
2
C*B
1
A

THISOP higher than LASTOP
put LASTOP and FLAC in POL
put THISOP into LASTOP

k1
5

(same as
above)

evaluate F
no more operations so this
operation has priority 0

THISOP

LAST OP

FLAC

PDL

EXPLANATION

E1'F

D
2
C*B

THISOP lower than LASTOP
do LASTOP with top of PDL
get new LASTOP from PDL

1
A

fif
2

C*B

D/E1'F

1
A

THISOP lower than LASTOP
do LASTOP with top of PDL
get new LASTOP from PDL

fif
C*B-D/E 1-F

(same as above)

¢
¢

A+B*C-D/E1'F

TH!SOP LASTOP 0 hence we are done:

do POP J exit

(same as above)

XI.

APPENDIX D

A. Field One Variable Array
1. Abstract
A new form of SK FOCAL W. (DEC-08AJAD-PB), is available which uses field one to store
data arrays in three word floating-point form. This facility is added to 4K FOCAL W via the
function call FNEW. The function may be called recursively to any level, and all of the
features of FOCAL are retained. In addition, an ERASE or ERASE ALL command will not wipe
out the array. Hence, variables may be stored for use in successive programs.

2. Requirements
Fits into unused locations in the F looting-Point Package (DEC-08-YQYA-PB)

7154-7177
6572-<>576
5755-5764
7554-7577
3. Usage
Loading
Load ofter FOCAL W. has been loaded into the machine (before or ofter initial dialogue). Restart
FOCAL W. at 2008.
Colling sequence
To store a variable Z as array element J:

* S X=FNEW(J,Z)
or

* 4.3 S X= FNEW(J,Z)
In addition X will be set equal to Z.
To get the data from array element K and set Z equal to this element:

* S Z= FNEW(K)
i.e. If there is only one argument the instruction is interpreted as a 'GET'. If there are two
arguments it is interpreted as a 'PUT'. In the above examples the arguments may be any
arithmetical expression that con be evaluated.

C. Recursive cal Iing
The function FNEW may be called recursively at any level. VIZ,
* s
sets Z

FNEW(J+lO) and

z = FNEW(J FNEW(J +1 O))
I

stores FNEW( +10) in array element J.

~ 3. 2 S . Z= FDXS(J*l 000)

+ FDIS(FNEW(J)*NORM)

The arguments may be any arithmetical expression. The following are valid:
*S

Z = FNEW(J*M-3, FEXP(X*2)*Y)

* S Z = FNEW(J,FNEW(J)*FEXP(FNEW(L)))
4. Description
The function FNEW protects the binary loader in upper core. The user, of course, may subdividr>
his array into any number of smaller arrays, keeping track of his own indecies.

AIT

5755

f'JTTO:V: 0027
C 1 L!2

F Fl'·~3I
F. '.'

t•
- \j-·
. !

C 100

7573
0077
Ll526

I: :t·! Jr
F ~J?L
lF03
FF:.!T
t~LlO 7
F F::T
oooc
OOLlL~
FLt•C
F LI .''i' l 0 6C3
F:~;: L
:3000
F \) t \-"
7 l :;:.L1
F''.1 'Tf.\FF
r ET
f L I ~: T

Ic\J:)y
I LI ~'.T
I.'.\JTFCF
I l'FT\1
'\1CQV,V;f.

VJC:
P')!-:-A

t' ') j• J
F~'~HP:

TTfEJ
-:i T '-.

r .. i

I" 7f.00
fFP.I:'·C

c -·-r ,,,

• .' l:: 1 . '·

0376
•/ ~' ~::,I:
1 Lt 0 f

0?17
0 7 fl
0052
023 l
Olf3
00f5
lLJ! 3
550:).
Lt503
LJ501
756'-l
002Lt
Lj 5 13
657'2

~/HTC

LI 5 1 l

~·JFTJ

Ll5 10

~p\]'.)f

LJ52l

fTPFTv 0 13LJ
TE!EE
7173
TLIST
T?

1Ll07
0157

I
I

FIF.Lr 0
I

/PACF

~Eno

CJN~TA~TS

*lf3
01~3

7524

~C1~~A,

-254

I
I

*F''.'JTAPF+ 15

0L!l3

715ll

FZ\JF.F

/PUT

ADD!ES~

F~T?PF

I
I

* 71 St1
/FIELL ONF FNFt
/CALL:
I

UAFIAELF~

F:-lf','CAF-Cl)
F\ifFCf'S(l,Af:f.2)

trET Ai'I·AY FLf'./,f\jT A! Cl
/Ft'.7 vP.LT:f 01' AICl !\: MJ?'."f

FLJ·.W:J.\~"i

715L1
7155
715(:
7157
7160

4/JQ 7
3373
0000
4452
7500

7 161
7162
71 (-.3
7 1 M!
7165
7 161S
7 1 f-7
7170
7171
7172
7173
7 l 7l!
7175

5366
1056
7700

I
I
F>iFh

1:''1TiLT• AlUIFS~
/FP ~l'J!'f,GF

FFZT
J~S

Lt526

1046
ll503
LJ501
5755
5777
5776
0002
3000
0000

FF\IT

I NTEGFT

1ri!EF

I~TFCFF

fYlfl

/FFGli\i Ci':FCA. FO!·

J:.'i? .+5
'i'Af:' Sf
S'.'1.C. CLA
ETF'JF
TAD F'LAC+2

10.r-:.

PP SHA

/~TOTS

rOi

Ff0TEC1

/XU~T

ALLFFr~

/CET

LJ~VFI

·1F

A~r?.f

VJ ;:TL

/Fv?'·LU\TF AY u·

pp~·HJ

AFC
/AFG~

J:"!F CET
J~P

PUT

FXIST~;rFT

/Ft1T DATA A~·.f:,Y
/CHP'.H::F THI~ rm

THfFF,

/Ot

3000
0000

756ll
755lt

l~TFGF~

D~Tf

n !') ~·()JD

STOfACF

T·!!FI·.

ADLFF~~

•JFJ: !'.\•I I ll:\f

/+?:·~~

I
I

7 1 7 (:
7177

/~A~F

'..t

L•)<'~L!::

*5755

~ 755

/F>)ALT1ATF A\: P:!-CT'.1E~·JT; IF N·JT
/THFPE FFHJY::~J TO CALL+2 iJIA FOFJ
/IF THFfF TO CtLL+3
I
AJ.C,
TtT. Ci-: AL

5 75r~

l 1LI2
1 1f3

~757

7640

SZA CLA /IS IT A co~~A?

57f0

536L!

J ·...i··
.!-' .+c

TAL '1CJ:"1>'.1A

5 7fl

L;50 l

Pti~:HJ

5762

160?.

571'3

7001

5 7f.i.J.

550?.

FVP.L- 1
I I \i c r f '<1 F\]'T' n Tti f\J
!AC
?')?J
/Dt) ::TFI OUT! 'lF ;:1. Ti'i \1
/

I
*7551~

7 5 ~ill
7555
7556
7557

7560
75f. 1
7562

7Sf<3
7 5f.LJ
7565
756f
7567
7570
7571
7r;.,72
7573
757'-1

11777
lLJlf.

CET,

/SETT?

:~ E TUP

?0I~T~f

LCA FL.AC+ 1

l l! 16
30L!6

FUT,

3Ltl6

1045
3L!l6
1OLJ6
3Lt 16
F201

5500

/GET Len: o; LE F

TAD I 16
DC.A FL.AC+ 2
J:".P F:'-IL
JV!
C:)
_J ...
SFTllP

TAC
DC.A
TAD
LCA

FLAC

TAD

FLAC+ 2

FLAC+ 1
I

DC.A I
CDF

0 'Vi
.• rr

E FlJ.\l 3 I

/FE.STJFF

6572

*f572
/SF.T UP pi')l:\JTFF T'.::J AffAY l'\J zr-lf
/CHA~CE

TO DATA FIFLL 1

f57?
6573
f~7b

GOOD
1413
3016

6575

6211

657f

5772

SFTCP,

0
POPA
DCA

/GFT

DP.Tl' FI FLL•

/Del FU:,JCTI O:\J FETt'I ,,;

I
I

7577

/GET F:·:FQ\ff\!T

T l'L· I 1 f
I.•CA FL.PiC
T.AL I 16

30L!Ll
1L;1 f
30.l!S

5373
!J777
1 OLJL!

J>'J ~--

ACCfF~S

CDF 10
J~? I ~FTUP
/

L?T~

XII. APPENDIX E
A. Disk Variable Storage
1. Abstract
This FOCAL overlay is equivalent to the FIELD ONE variable addition to FOCAL described in
Appendix D. In this case, however, variables are stored on the Disk.

2. Comments
The contents of location 167 (BASE) must be set for the user's machine configuration. Disk
variables are written on the disk from BASE upward. BASE is the disk extended address of the
lowest used location.
e.g.
last 4K of one disk system

C(167) = 7008

last SK of two disk system

C(167) = 1600

last 16K of two disk system

C(167) = 140¢

The present listing is for the last 4K on a two disk system, i.e. C(167) = 17¢¢8 .

~·IT

57!'5

!'A!"
0167
1'1TTO"'.! 0027

Ct>

016[.)

CHA!'

014?.
Cl CO

F i-P>!3I

r \:1·
F} ! Dr
F t.:PL
i' F'\: T
r E<,:T

0077
L.:526
1603
L1L101

0000

FL/\C
OOLlLf
FLl.5Tl Of03
F '1'UL
3000

r ,\IF t'

lo \!T?tF

7 l 5Li
C37£!.

rLI ~;T

lL:06

I nnr
I LIST
I ~,1c-TF
I NTF C'F
I I :F'1'\i

o::-i 17

V: COV!:~p

0761
7!'165
005?
0231
0162

:':CF

0065

V!'JfE
!'.'.)FA

755LJ
lL! 13
550::>
L.1503
4501
7574

PO?J
?PSH~
?l 1 ~HJ

f'L!3
~- 700
F 7600
1FAf
FFALC

717~
OO~LJ

0165
.ll513
r TLf:
L.!520
~Jf:TC
4511
SOFTJ L1510
~PNOF
.ll52 l
~TAFTV 0134
THFEF
7173
TLIST
1407
T2
0157
\•'C
0163
~.:p1 TE
0166

/ r F r I ,,~ I LI I\ c: *

F IC r.t.

I
CHf'.O~= lL·~

!·TLf=Li520
rn;:EA=L.!503

f·lPA= li.' 1 ~~
PTJE:-1..1== L• 5,c l
F')FJ= :~ 502
f1;;.L= 1 f.CJ
l \'TF, r:;;::='.'-2
FT! )f:::LJ~::?A
FLf'.C=Lil!

S] l T ,J::: L! 5 l 0
;· ') F TC = I! ~. 1 l
E F: '-~ 2 I = 1 C. n
~TAFT'.;= 13L

I FFPJ= ~<? l
·~CI =f.:"·

TLI: T= 1L107
FLI ~T 1= ,.;03
l 1 1TT1'~=?7

Fi\1T=77
T ?= 1 ~?
p7r-.oo=~Ll

!FALC=L!c:.13

CL I ~ 'T= l/J() f.
~T'jlf=Ll:'>21
IC\l1F=~ 1 17

F F,\l T= 1:110 7
F .V: n.= 300 0

rf:':T=O
I L I ~ 1· = 7 r- l
F \l TA E F= 3 7 f
I
/
I

fl:EL.l

-44I
I
f.Il:.Lf
I

/f'/:lf!F

7.ET~

CO\J.S1'A:\JT$

(• 1 ff-

"'162
75f i.J
7750
7751

tv: C:J V..'1 A, -?5i•

\• c,

7750

CA,

77~1

f (,(13

FE:AL,

tr 1 1 ......

D:-1A!

(-(.()~

Clf3
0 1 (-Li
01 f.5
OJr.r.

u 1 f .,

1700

EA.Sb

1700

/
I
/

/LI'.'JK T!J FOCAL

* F'.!TALI<+ 15

FNF\.
I
/
I

*5755
/EVALPATF AN AFC.::t'YffNT; IF NOT
FETtT\J T') CP.LL+P

ITHFFF

5755
~ 75f
'5 75 7
!:17~0
~ 7f 1
i.:.. 7f ~)
~,

7 f.3

57f/J.

11 i.!2
1lf 2
7fi'-!O
53€-i.J

/
AFC,

T.AV CHAP

TAC '."lCO:'i:"i.A
f:ZP. CLA
JV.P • +J.j
?t'.SHJ

J.:501
If.OP
7001
5502

F'JAL- 1
IAC

POPJ
I
I

* 7 1 Sll
/DI~K

F.\JFt.·

715ll
7155
715f
7157
71f0
7161

i1LIO 7

FENT

3373
CCGO
l!ll!')2
ll 50 3

F~l1L THFE F
FEXT
JMS I INTEGFT
PUSHf>

/,V:Ai<E A'.'J I :-VTE GE l·
/?l 1 SH LISK ~F~· Aft•

10it5

TAD FLAC+ 1

/Gi:T HIGH ·Ol:f.El·

716~

t1 s ~o

F.TLf.

/SHIFT FOF

7 1f.3
716l!
711S5
7 1 f (.
71 f:.7
7170
7171
7172
7173
717

0372
1167
L15G3
J.150 l
5755
734l!
5777
0700

ANt P700

/:vlAS:-< F·)F EXTF\Jf FL

TAD BA~F
PUSH A

/AD[

P700,

0002

THFFF,

PliSHJ
AFG

Dl~K

BA.SF

/SP.vE LEA
/FVALrATE

ALG~

STA CLL fAL

1-r. FOL EFt:r:

J'.YiP '.'10FE

/St.VE DtiTA

700
2

~-ViT

EXTE~rFr

?[L!~~s

rr T~

?L~~ES~

7 l 7 :~
71711
717~

oco~~

1HiFE1

30CC

oooc

,.,
'
300C
("·'

7177

7554

7~~.lj

1 l (:fl

7~-~~

33(5
1ll 13
f.f.15
73llf3563

7~~f.
7~r:..7

7 5'·0
7~f1
7~f f'

75f<·
'I 5f:L!
7~(:5

75f 6
7 ':-,(-7
7570
7571
757~

7573
7~7'1

137L:
351'LI
l .l.! 13
0000

* 75511
X·1FF1

TA[ ;, ;··1 't"l·
I:C? I:,,~- 'iT
p.)pp
LFN.
:Tr.; CLL ITL
tCA I ~- c
, ..At: Pll3
LCA I er

/rF 1

I Gr.1

10 F

LF:C

53~7

J-.1:;.: • - 1

( fC 1
fOO l

LC"<J A
I ·1 '.\

J.-:r- I
p/13,.
/
I

~11:.(,'il:)>

r 1~ t

. ;, ·]! L ~

I I \i'i") FI.re

((-.~2

r: I ~· :·: I

/Tl P"J ~-Fr!

r<Jr- r

I\l~ll ..

f.00~

5500
00l;3

/f:P,:<.F

[i'."i f.

/J:I ~AH... F I ': ·; r ! ! •
lt·1\;F?
/\]') ~· N ·1·
/ 1P~i-i FL£, C~
/L-1 A r-r·:-.cTI·)\

!- Ft.1 \!~·I

I..• 'C
·~

;:·~.:

XI II.

APPENDIX F

A. Hints and Kinks Department
For the experienced programmer the fol lowing may be helpful.

1. location EVAL-1 contains the subroutine call GETC.
and evaluate an argument one may:

Hence, to move past a character

PUS HJ
EVAL-1

2. The first instruction in the POPJ subroutine is TAD I 13. Hence, for multiple returns
from a subroutine one may POP J with the AC nonzero, e.g. if the AC is 1, return is to
col I + 3 instead of col I + 2 (as in a normal POP J return).
VIZ,
PUS HJ
SUB

/call

xx
xx
xx

/normal return
/POPJ return if AC= 1 when POPJ
called
/return if AC= 2
/etc.

In al I coses the subroutine wi 11 return with the AC =fa.

3. When using signed and unsigned integers core must be taken that minus zero is not in the
FLAC since EFUN31 normalizes the FLAC.
coding will apply for unsigned integers.

(FOCAL will 'hang' in that event.) The following

/make sure sign bit is fO

CLL RAR
DCA FLAC + 1
RAR
DCA FLAC+ 2
TAD Pl4
DCA FLAC
JMP I EFUN31

/put carry bit away
/put exponent in

for signed integers:
CLL RAL
SNA
CLL
RAR
DCA FLAC + 1
DCA FLAC + 2
TAD DCA FLAC
JMP I EFUN31

/make sure positive fi

4. There is a BUG in FOCAL. The RMF in the interrupt routine must be moved to just
prior to the ION. This will not give trouble until field one coding is added.
5. For hardware initialization when FOCAL recovers (Control-C) one may use location
2775.
6. For machines without a high-speed reader, additional coding room of 6320-6377 may
be gained by overwriting the HRS routine. To remove the * command deposit 2725 in
location 1207.