PiDP-8/I Software

U/W FOCAL V4E Reference Cards
Log In


The following material is reformatted from the CARD[1-4].DA files contained within the U/W FOCAL V4E distribution which we used in creating the PiDP-8/I software project's U/W FOCAL feature.

Some minimal effort has been made to make this document print well, though it doesn't paginate the same as the original material.

Since these files were likely created before 1978 and probably did not have their copyright renewed — if it was in fact applied for, not an automatic thing at the time in the United States — we believe this text to be in the public domain. If the authors of the text below request it, we will remove this file from the PiDP-8/I software distribution.

U/W FOCAL Quick Reference Card (CARD1.DA)

Single Letter Commands

A Ask ["QUERY",X,:,!] Accepts value of X from input device
B Break [L1]% Exits from a FOR loop, continuing at L1
C Comment Ignores the rest of the line
D Do [G1,G2,G3,etc.] Calls a line or a group as a subroutine
E Erase [G1] Deletes all or part of the program
F For X=E1,[E2,] E3;(commands) Executes line 1+(_E3_-_E1_)/_E2_ times
G Goto [L1] Branches to line L1
H Hesitate [E1]* Delays (or synchronizes) the program
I If (E1) [L1,L2,L3]% Transfers to L1,L2,L3 on sign of E1
J Jump (E1) [G1,G2,G3,G4...]% Calls the subroutine selected by E1
K Kontrol [E1,E2,etc]* Controls relays or other digital output
L Library/List Two-letter commands, see the next page
M Modify [L1,L2] Edits and/or Moves line L1 - see below
N Next [L1]% Ends a FOR loop, branches to L1 when finished
O On (E1) [G1,G2,G3]% Calls subroutine selected by sign of E1
P Plot [X,Y,L,M]* Controls an analog or digital plotter
Q Quit [L1]% Stops program, allows restart at L1
R Return [L1]% Exits from a subroutine call, continuing at L1
S Set [E1,E2,E3,etc.] Evaluates arithmetic expressions
T Type [E1,"TEXT",!,#,:,%,$] Generates alphanumeric output
U User
V View [X,Y,Z]* Generates graphic output on a CRT
W Write [G1,G2,G3,etc.] Lists all or part of a program
X Xecute Equivalent to SET
Y Yncrement [X,Y-Z] Increments or decrements variables
Z Zero [X,Y,...] Sets some or all of the variables to zero

* Indicates a non-standard (installation dependent) feature

% If the line number is omitted (or=0) no branch will occur

En are Arithmetic Expressions - - [] Enclose optional items

Ln are Line Numbers from 0.01 to 31.99 - excluding integers

Gn are Line or Group Numbers from 0 to +31 (0 = next or all)

Line numbers .01 to .99 refer to lines in the current group Negative or Integer line numbers denote a 'Group' operation. Arithmetic expressions may be used as Line or Group numbers

Arithmetic Operators

( ) [ ] < > Three equivalent sets of enclosures
' Character value 'A is the value of the letter A
^ Exponentiation Positive or negative integer powers
* Multiplication Note especially that multiplication
/ Division has a higher priority than division
- Subtraction or Negation Example: (to illustrate priorities)
+ Addition -5^4/3*A=2+1 is 0-<5^4>/[3*(A=2+1)]
= Replacement May be used anywhere in expressions

Ask/Type Operators

, COMMA or SPACE Separates variables and/or expressions
! Carriage return/linefeed Starts a new line for input or output
" String delimiter Case shift option uses \: "A\B\C"=AbC
# Return or Clear Screen Used for plotting or overprinting
$ Symbol table listing TYPE $4 prints 4 variables per line
: Tabulation ASK :-15 skips over the next 15 characters
(:0 is ignored) TYPE :15 spaces to column 15 if not beyond
% Format control %3 Produces 3 Digits in an integer format
(for output only) %0.04 = 4 Digits using scientific notation
(input is unformatted) %5.02 = 5 Digits, 2 decimal places maximum

Letters (but only one E) are legal numeric input: YES=25E19. ALTMODE or ESCAPE aborts input, with the variable unchanged. _ deletes all digits during input — RUBOUT is ignored.

Modify / Move Operators

CTRL/F Aborts the command leaving the line unchanged
CTRL/G (bell) Selects a new search character
CTRL/L (does not echo) Searches for next occurrence of character
_ (backarrow or underline) Deletes all characters to the left
RETURN Terminates the line at the current position
LINEFEED Copies the remainder of the line unchanged
RUBOUT/DELETE Removes the previous character, echos a \

RUBOUT or DELETE and _ also work during command input

LINEFEED retypes the corrected input line for verification

Command Summary (CARD2.DA)

In the descriptions below, arguments in square brackets are optional. Specify the argument, but don't include the square brackets. If a space is in the square brackets, a space is required to provide the argument.

Miscellaneous Commands

O D Output Date Prints system date in the form DD.MM.YY
L E Logical Exit Returns to the OS/8 keyboard monitor
L B Logical Branch L1 Branches to L1 if -no- input from TTY
J Jump L1. Equivalent to the Logical Branch command

Filesystem Directory Commands

L A,E List All [name][,E] Lists all files after the one specified
L O List Only [name]* Verifies the existence of one .FC file
O L Only List [name]* Verifies the existence of one .DA file
L L Library List [name]% Shows files with the same extension
L D Library Delete name [ L1] Removes a name from the directory
L Z Library Zero dev:[length] Zeros directory using length given

Notes on Directory Commands:

E Adding the phrase ,E will list all of the 'empties' too

% A null extension will list all files having the same name

Program Commands

L C Library Call name Loads a program, then Quits
L G Library Gosub name [ G1] Calls a program as a subroutine
L R Library Run name [ L1] Loads a program and starts at L1
L N Library Name [name] Changes the program header
L S Library Save name [ L1] Saves the current program

[ G1] indicates which line or group will be called by L G

[ L1] specifies an error return, except for the L R command

Input / Output Commands

O A Output Abort [E1] Terminates output file with length E1
O B Output Buffer Dumps buffer without closing the file
O C Output Close [E1] Ends output, saves file with length E1
O I,E Open Input [,Echo] Selects the terminal for input
O O Open Output Selects the terminal for output
O S Output Scope Selects CRT for output (if available)
O I - Open Input name [,E] [ L1] Switches input to an OS/8 device
O S - Open Second name [,Echo] [ L1] Selects a second input file
O O - Open Output name [,Echo] [ L1] Initiates OS/8 (file) output
O E - Output Everything device [,Echo] Changes error/echo device
O R R Open Restart Read [,Echo] Restarts from the beginning
O R I Open Resume Input [,Echo] [ L1] Returns to file input
O R O Open Resume Output [,Echo] [ L1] Returns to file output
O R S Open Resume Second [,Echo] [ L1] Returns to second input file

The INPUT ECHO sends characters to the current OUTPUT device

The OUTPUT ECHO sends characters to the current 'O E' device

Filename Expressions

Device and filenames may be written explicitly: RXA1:, MYSTUF, 0123.45. Numeric parts can be computed from (expressions): DTA(N):PROG(X).(A+B). Negative values specify single characters: F(-201)L(-197,.5,PI)=FILE03. An <OS/8 block number> can be substituted for the name: LTA1:<20*BN+7>. Expressions in square brackets indicate the size: TINY[1], <LOC>[SIZE].


Variable names may be any length, but only the first two characters are stored; the first character may not be an F. Both single and double subscripts are allowed - a subscript of 0 is assumed if none is given. The variables !, ", #, $, % and PI are protected from the ZERO command and do not appear in table dumps. ! is used for double subscripting and should be set to the number of rows in the array. #, $, % are used by FOCAL Statement Functions. The ZVR feature permits non-zero variables to replace any which are zero. This includes FOR loop indices, so use a protected variable if the index runs through zero. Undefined or replaced variables are automatically set to zero before their first use.

FOCAL Statement Functions

F(G1,E1,E2,E3) executes line or group G1 after first setting the variables #,$,% to the values of E1,E2,E3 (if any). The function returun with the value of the last arithmetic expression processed by the sub routine, including line number & subscript evaluations. For example:

8.1 S FSIN(#)/FCOS(#) is the TANGENT function = F(TAN,A) if 'TA' = 8.1
9.1 S FEXP($*FLOG(#)) computes X^Y for any value of Y using F(9.1,X,Y)

Miscellaneous Material (CARD3.DA)

Internal Functions

FABS(E1) Returns the absolute value of the argument
FADC(N) Reads A/D converter channel N (LAB/8e or PDP12)
FATN(A) Computes the arctangent of A, result in radians
FBLK() OS/8 block number of the current input file
FBUF(I,V) Display buffer storage (single-precision)
FCOM(I,V) Extended data storage in Fields 2 and 4-7
FCOS(A) Computes the cosine of A (A is in radians)
FCTR(N) Reads a frequency counter using timebase N
FDAC(N,V) Sets D/A converter channel N to the value V
FDAY(MONTH256+DAY8+YEAR-78) Reads/Sets the OS/8 system date
FDIN(B1,B2,...,Bn) Reads selected bits from the input register
FDVM(N,R) Reads a digital voltmeter, channel N, range R
FEXP(E1) Base 'e' exponential function \|E1\|<1420
FIN() Reads a single character, returns the ASCII value
FIND(C) Searches for code C, returning C if found, 0 if EOF
FITR(E1) Returns the integer part of the argument
FJOY(I) Places the cursor (joystick) coordinates in XJ,YJ
FLEN(I) File length: I=0 for Output, I=1 for Input
FLOG(E1) Natural logarithm of the absolute value of E1
FLS() Returns unsigned value of the Left Switches (PDP12)
FMIN(A_,_B) Returns the minimum or argument
FMAX(A_,_B) Returns the maximum argument
FMQ(N) Displays the lower 12 bits of N in the MQ register
FOUT(C) Outputs character code C, returns the value 0
FRA(I,V) Reads or writes in a binary file at location I
FRAC(E1) Returns the fractional part of the argument
FRAN() Pseudo-random number function, range 0-1
FSAM(N) Samples N channels and stores results in buffer
FSGN(E1) Returns -1,0,+1 for E1 negative, zero, positive
FSIN(A) Computes the sine of A (A is in radians)
FSQT(E1) Finds the square root using Newton's method
FSR() Reads the Switch Register
FRS() Reads the Right Switches on a PDP-12
FSS(N) Tests Sense Switch N: -1 = OFF, +1 = ON
FTIM(N) Reads, sets or clears the elapsed time counter
FTRG(N) Returns status and clears Schmitt trigger N
FTRM() Returns the last input terminator
FXL(N) Tests external level N (PDP12) returning -1 or +1

And others. There are a total of 36 possible function names

Functions indicated by a * are not available in all versions. The functions FBLK & FLEN are useful in filename expressions. FIN, FOUT, FIND and FTRM use decimal ASCII codes - see below.

Decimal ASCII Character Codes

Code Character Code Char Code Char Code Char
128 CTRL/@ (leader/ 152 CTRL/X 176 0 201 I
trailer-ignored) 153 CTRL/Y 177 1 202 J
129 CTRL/A 154 CTRL/Z (EOF) 178 2 203 K
130 CTRL/B 155 ESCAPE or 179 3 204 L
131 CTRL/C (OS/8) CTRL/[ 180 4 205 M
132 CTRL/D 156 CTRL/\ 181 5 206 N
133 CTRL/E 157 CTRL/] 182 6 207 O
134 CTRL/F (BREAK) 158 CTRL/^ 183 7 208 P
135 CTRL/G (BELL) 159 CTRL/_ 184 8 209 Q
136 CTRL/H (BACKSP) 160 SPACE 185 9 210 R
137 CTRL/I (TAB) 161 ! 186 : 211 S
138 LINEFEED 162 " 187 ; 212 T
139 CTRL/K (LINEUP) 163 # 188 < 213 U
140 FORMFEED 164 $ 189 = 214 V
141 RETURN 165 % 190 > 215 W
142 CTRL/N 166 & 191 ? 216 X
143 CTRL/O 167 ' (APOST) 192 @ 217 Y
144 CTRL/P 168 ( 193 A 218 Z
145 CTRL/Q (X-ON) 169 ) 194 B 219 [
146 CTRL/R 170 * 195 C 220 \
147 CTRL/S (X-OFF) 171 + 196 D 221 ]
148 CTRL/T 172 , (comma) 197 E 222 ^
149 CTRL/U 173 - (minus) 198 F 223 _
150 CTRL/V 174 . (period) 199 G 253 ALTMODE
151 CTRL/W 175 / 200 H 255 RUBOUT

Codes 224-250 are lower case letters. Codes 000-127 are similar to codes 128-255 except that the parity bit has been eliminated.

Many keyboards use SHIFT/K, /L, /M, /N, /O for [, \, ], ^ and _

A single quote before a character indicates the-value-of: 'A=193 Use CTRL/@ to page the TV display to avoid getting error 12.40

To erase the screen on a Tektronix terminal: S FOUT(27) FOUT(12)

To make a copy: S FOUT(27) FOUT(23). Note: FOUT(27) = ESCAPE

To make bold letters on a Centronics printer: T :FOUT(14) "text"

To set 'Hold Screen' mode (VT50 terminals): S FOUT(27) FOUT(91)

To rubout the last character on the PDP12/LAB8e display FOUT(92)

Error Code Table (CARD4.DA)

For extreme economy of memory, FOCAL does not print error message strings. Instead, an error routine prints a question mark followed by a four digit fixed point number corresponding to where in the FOCAL runtime executable the error was encountered.

I.E. If an error was encountered in the FOCAL interpreter's parsing of a variable name, the error message prints out the error message traceable to that parser within FOCAL.

This means that an error table must be produced, and every time code shifts around, the error table must be updated.

The U/W FOCAL manual contains an error table, but it is incomplete. Here is a complete one which comes from the file CARD4.DA in the U/W FOCAL archive from which this distribution is taken.

Errors appearing in bold face denotes an error from a command with an optional error return.

Error Meaning
? Keyboard interrupt or restart from location 10200
?01.03 Secondary input file missing
?01.11 No secondary input file to resume
?01.50 Group number greater than 31
?01.93 Non-existent line number in a MODIFY or MOVE command
?03.10 Line called by GO, IF, J, R, Q, L B, or L R is missing
?03.30 Illegal command
?03.47 Line or group missing in DO, ON, JUMP, L GOSUB or a FSF
?04.35 Bad syntax in a FOR command (missing semicolon?)
?06.03 Illegal use of a function or number: ASK, YNCREMENT, ZERO
?06.41 Too many variables (ZERO unnecessary ones)
?07.44 Operator missing or illegal use of an equal sign
?07.67 Variable name begins with F or improper function call
?07.76 Double operators or an unknown function
?08.10 Parentheses don't match
?10.50 Program too large
?12.10 Error detected in the BATCH input file
?12.40 Keyboard buffer overflow (eliminated in 8/e versions)
?13.65 Insufficient memory for BATCH operation
?14.15 Display buffer overflow
?14.50 Bad Sense Switch number on a PDP12 (range is 0-5)
?14.56 Illegal external sense line (PDP12 range is 0-11)
?17.22 FRA not initialized
?17.33 FRA index too large (exceeds file area)
?17.62 FRA mode error: only modes 0,1,2,4 allowed
?18.42 FCOM index too large: reduce program size
?19.72 Logarithm of zero
?21.57 Square root of a negative number
?22.65 Numeric overflow: too many digits in a string
?23.18 OUTPUT ABORT or CLOSE requested too much space
?23.37 Output file overflow: recover with: O O name;O A FLEN()
?23.82 Cannot open output file (file open, too big or no name)
?24.05 No output file to resume
?24.25 Illegal OPEN command
?24.35 Illegal RESUME command
?24.40 Input file not found (wrong name? wrong device?)
?24.47 No input file to restart
?24.52 No input file to resume
?25.02 Stack overflow: reduce nested subroutines and expressions
?25.60 Device does not exist or illegal 2-page handler
?26.07 Illegal LIBRARY command
?26.32 File specified is already deleted (wrong extension?)
?26.39 File loaded is not a FOCAL program - better reload UWF!
?26.56 Program requested is missing (wrong device?)
?26.66 LIBRARY SAVE error: no name, device full, or no directory
?27.18 Attempted LIBRARY operation on a device without a directory
?27.75 No length specified in a LIBRARY ZERO command
?27.90 Zero divisor
?29.25 Cannot use the '<>' construction with OPEN OUTPUT
?29.38 Device error (write-lock, bad checksum or illegal request)

_ Indicates EOF detected in input - I/O continues from terminal

?....? TRACE feature: Text enclosed by ? marks is typed during execution to help find the source of an error. The value of each expression in a SET command is also printed