P System_Users_Manual_Supplement_Version_IV.0_Apr82 System Users Manual Supplement Version IV.0 Apr82

pSystem_Users_Manual_Supplement_Version_IV.0_Apr82 manual pdf -FilePursuit

pSystem_Users_Manual_Supplement_Version_IV.0_Apr82 pSystem_Users_Manual_Supplement_Version_IV.0_Apr82

User Manual: pSystem_Users_Manual_Supplement_Version_IV.0_Apr82

Open the PDF directly: View PDF .
Page Count: 233

Download
Open PDF In Browser	View PDF

UCSD

USERS'

P-SYSTEM

MANUAL
VERSI'ON

8

SUPPLEMENT
IV

April 1982
SofTech Microsystems, Inc.
San Diego, California.

Copyright © 1982 by SofTech Microsystems, Inc.
All rights reserved. No part of this work may be reproduced in any form or by
any means or used to make a derivative work (such as a translation,
transformation, or adaptation) without the permission in writing of SofTech
Microsystems, Inc.
DISCLAIMER: These documents and the software they describe are subject to
change without notice. No warranty expressed or implied covers their use.
Neither the manufacturer nor the seller is responsible or liable for any
consequences of their ·use.
ACKNOWLEDEGMENTS: This document was edited at SofTech Microsystems by
Paula Johnson and Stan Stringfellow.
UCSD 9 , UCSD Pascal S, and UCSD p-System are all trademarks of the Regents
of the University of Califomia. Use thereof in conjunction with any goods or
services is authorized by specific license only, and any unauthorized use is contrary
to the laws 01 the State of California.
XenoFileS is a trademark of SofTech Microsystems, Inc.
CP/M@ is. a registered trademark of Digital Research, Inc.

TABLE OF CONTENTS
Section
I

INTRODUCTION.
1.1
1.2
1.3

II

Page

. .. .. .. . .... ... . . . .

• 1-1

New and Upgraded Standard Facilities
New Optional F acili ties ••••••••
Installation Guide Supplement •••••

• •••• I-I
• 1-3
., ••• 1-4

NEW AND UPGRADED STANDARD FACILITIES
II.I The
II.I.I
II.I.2
IJ.l.3
II.l.4

• • II-I

..

Symbolic Debugger ••••••••••
• • I1-1
Entering and E xi ting the Debugger
• • II-I
Using Breakpoints • • • • • • • • • • •
• • II-2
Viewing and Altering Variables ••
• ••• II-3
Viewing Text Files from the DeblJgger •••••••
• ••• I1-4
H.l.S Displaying Useful Information
• • • • • • • 11-5
II.l.6 Disassembling P-code • • • • •
II-6
II.l.7 Example of Debugger Usage •
• ••••• 11-6
II.~.8
Symbolic Debugging ••••••
• ••• I1-7
II.l.9 Symbolic Debugging Example.
• II-9
II.I.ID Interacting with the Performance Monitor
• ••• II-II
II.l.ll Summary of' the Commands.
• ••••
• • • • •
II-12
II.2 Event Handling • • .. • • • • • • • • • • • • •• • •
• • • • • II-14
II.3 New F He Handling F acili ties • • • • • • • •• • • • • •
II-17
II.3.1 Subsidiary Volumes ~ • • • • • • • • • • • • • • •
II-17
II.3.1.1 Creating and Accessing Subsidiary Volumes ••
• 11-18
II.3.1.2 Mounting and Dismounting Subsidiary Volumes
I1-I9
II.3.1.3 Installation Information •••
II-21
II.3.2 User-Defined Serial Devices ••••
., II-21 .
II.3.3 The Flip Swap/Lock Command •••
• II-22
II.3.4 The V(olumes Command ••••••
II-23
II.3.S Filer P(refi x Notes ••••••••
II-24
II.3~6
File Management Units • • • • • • • • • • • •
U-24
II.3.6.1 Directory Information (DIR.INFO)
II-25
II-25 '
II.3.6.1.1 Notation and Terminology •••••
II.3.6.1.2 Wild Cards • • • • • • • • • • • • • • •
• • II-26
11.3.6.1.3 File Name Arguments '••
I1-27
II.3.6.1.4 File Type Selection •
• • II-27
II.3.6.1.S File Dates • • • • • • • •
II-28
II.3.6.1.6 Error Results •••••••
II-29
II.3.6.1.7 DIR INFO Interface • • • • • • • • • • • • •
II-30
II.3.6.1.8 Detailed Description of Functions.
• • II-32
II.3.6.2 Wild Cards (WILD) • • • • • • • • • • • •
• II-58
II.3.6.2.1 Special Wild Card Characters •
II-59
II.3.6.2.1.1 Question Mark Wild Card ••
• ll-60
II.3.6.2.I.2 Equals Sign Wild Card •••
• • U-6D
~

·..

iii

Users' Manual Supplement, Version IV
Table of Contents

1l.3.6.2.1.3 Subrange Wild Card •••••••••
I1.3.6.2.2 Function 0 Wild Match ••••••••
II.3.6.2.2.1 Pattern Matching Information ••
II.3.6.3 System Information (SYSJNFO) ••
II.3.6.4 File Information (FILE.INFO)

• ••• I1-6l
U-62
U-63
11-67
II-71
I1.4 Error Messages • • • • • • • • • • • • •
• •• H-75
II.4.1 Format of Error Messages ••••
• • • • • • • II-75
11.4.2 User Control of Error Messages ••••
11-76
II.5 Pascal Compiler Enhancements • • • •
• •• • • • • • • • • 11-78
11.5.1 Selective Uses • • • • • • • • • • •
• •••
• ••••• 11-78
11.5.2 Enhancements to the Compiled Listing ••
• 11-83
11.5.3 Pascal Compiler Back-End Errors
• • • • • • • • • • • c • • 11-84
II.6 Extended Memory ••••
• •••
II-88
II.7 Echoed Characters • • • •
• • • • • •
U-89
11.8 Editor Enhancements.
• •••
11-90
I1.8.l Setting Tab Stops • • • • • •
• • • • • • • • • • • • •
U-90
11.8.2 Editing Line in Set Environment Display •••
• II-90
11.8.3 Byte Sex Independent Environment Information
• ••••• 11-91
11.8.4 Editor Control Characters •
• 11-91
I1.9 The 8086 and 68000 Assemblers
U-93
11.9.1 The 8086 Assembler •••••
11-93
II.9.1.1 Notational Conventions •••
11-93
II.9.1.2 8086/88/87 Error Messages ••••
• ••••• II-96
11.9.1.3 Sharing Resourses with the Interpreter
II-98
11.9.1.3.1 Calling and Returning.
11-98
11.9.1.3.2 Accessing Parameters. • • • •
U-98
11.9.1.3.3 Register Usage ••••••••• •••••••••
II-99
II.9.2 68000 Assembler Syntax Conventions
U-99
II.9.2.1 Miscellaneous.......
• • • • • • • • •
• II-IOO
II.9.2.2 68000 Error Messages ••
II-lOO
11.10 Turnkey Applications Facilities
• ••• II-I02
11-102
fi.lO.l SYSTEM.MENU ••••
11.10.2 Turnkey Packages •••
• • • • •
• 11-102
I1.10.3 System Initialization •••••
• •••••• U-I03'
11.11 Performance Monitor
••••••••••••••
• •
• ••• II-I04
11.12 REALCONV Utility •••••
• •••••• U-106

...

...

. ·. ..

...

iv

...

. ...

Users' Manual Supplement, Version IV
Table of Contents

III

NEW OPTIONAL FACILITIES • •

...

• 111-1

111.1 Native Code Generator ••••
•
Ill.l.l Native Code Directives and Pascal.
•
III.l.2 Native Code Directives and BASIC ••••
•
III.l.3 Native Code Directives and FORTRAN
•
III.l.4 Running the Native Code Generator
•
IIl.l.5 Limits of Native Code Generation
•
III.2 Print Spooling • • • • • • • • • • • • • • •
• • • • •
Ill.3 X e n o F i l e . . . . . . . . . . . . . . . . . . . . .
• • •
• •
III.3.1 Configuring the XenoFile Package
• ••••
III.3.2 The CP/M Filer ••••••••••••
•
III.3.3 Using XenoFile CP/M Via UCSD Pascal.
• •
111.3.4 The File Control Block •••
•
III.3.5 File Control Block Intrinsics ••••••
• •
Ill.3.6 CP/M Interface Entry Points •••••••
•
III.3.7 Summary: CP/M Interface--Calls to CPM2 Unit.
•
Ill.3.8 FORTRAN Interface to XenoFile • •
III.3.9 BASIC Interface to XenoFile
••
• • • • •
111.4 Turtlegraphics • • • • • • •
• ••
•
III.4.1 Using Turtlegraphics ••••
•
Ill.4.1 1 The Turtle ••••
111.4.1.2 The Display •••
•
Ill.4.1.3 Labels •••••••
• ••••
111.4.1.4 Scaling ••••••
• • • • • • • • • • • •
Ill.4.1.5 Figures and the Port
••••••••••
III.4.1.6 Pi xels • • • • • • • •
• • • • • •
•
111.4.1.7 FotoFiles ••••••
• •
111.4.1.8 Routine Parameters
lll.4.1.9 Sample Program •••••••

· . .· .

· ..

.. . ... .

III-l
IIT-l
III-2
IIl-2
III-3
IIl-9
111-10
In-12
111-12
11l-13
III-14
IIl-14
111-17
IIl-20
III-43
In-47
III-51
Ill-57
III-58
In-58
III-61
III-62
111.. 62

Ill-64
111-66
111-67
III-68
III-70

v

Users' Manual Supplement, Version IV
T able of Contents

IV

INST ALLA TION GUIDE SUPPLEMENT •

• ••• IV-1

IV.l Installation of Adaptable Systems •
• •••
IV.l.l Release Disk Format. • • • • • • • • • • • • • • • •
IV.l.2 Installing Events • • • • • .~ • •
•
IV cl.3 Required New 58105 Routines: QUIET and ENABLE
• •
IV.1.4 New Definition of PRNST AT and SETTRAK.
IV.l.5 Floating Point Number Configuration ••
• •
IV.l.6 Installing GOTOXY • • • • • • • • • • • •
•
IV .,1. 7 p-System Support for ANSI Terminals
• •
IV.2 The 8086 Adaptable System " • • • • • • • •
•
IV ,,2e>1 Bootstrapping the p-System • • • • • • • •
• •
IV .. 2.2 S810S Interface. • • . . . . . . . . . . . .
• • • • • • • •
• •••••
IVv2.3 BIOS Routines Accessible to the SBIOS •••••
• • •
IV.2.4 The Primary Bootstrap. •
• •••
• • • • • •
IV.3 SETUP ••••••
IV.4 Installing Turtlegraphics ••••
IV ,,4.1 Introduction.......
• •
IV.4.2 Graphics I/O Routines •••
•
IV.4.3 Graphics System Initialization.
IV .. 4.4 T urtlegraphics Character Fonts
IV.4.5 Linking and Librarying Turtlegraphics ••
• •••
IV.S Adaptable System Release Disk Directories
IV.S.l Z80 Adaptable System Release Disks ••
• •
IV.5.2 8080 Adaptable System Release Disks •
• •
IV.5.3. CP/M Adaptable System Release Disks
IV.S.4 8086 Adaptabie System Release Disks
IV.S.5 6502 Adaptable System Release Disks •
e.

D

•

•

•

•

•

•

...

vi

IV-2
IV-2
IV-2
IV-3
IV-4
IV-S
IV-7
IV-9
IV-II
IV-13
IV -13
IV -17
IV-17
IV -18
IV-26
IV-26
IV-28
IV-35
IV-36
IV -37
IV-42
IV -42
IV-45
IV-46
IV-47
IV-49

I

INTRODUCTION

This supplement describes new and upgraded portions of the Version IV UCSD pSystem. It is an update to the UCSD p-System Users' Manual, Version IV.O and
the UCSD p-System Installation Guide.
This document is divided into four chapters. Chapter I (this introduction) gives an
overview of what is covered in the rest of the supplement. Chapter II describes
the new and upgraded standard facilities which are available with each p-System
purchase. Chapter III covers features which may be optionally purchased with the
p-System. Chapter IV contains information pertaining to the installation of
adaptable systems with the current version IV p-System.
The following paragraphs summarize chapters II through IV and explain how the
information in this supplement should be used in conjunction with the Users'
Manual and the Installation Guide.

1.1

New and Upgraded Standard Facilities

The following topics are covered in Chapter II.
Symbolic Debugger
The P-code debugger has been upgraded to allow the specification of break
point locations with a line number instead of a P-code offset. Also, variables
can be specified by name rather than data offset. The information in the
supplement replaces the information in the Users Manual, Version IV.O.
Event Handling
An event is a low level I/O action (e.g. an interrupt or the pressing of a
key). The SBIOS can now notify the p-System that an event has occurred.
If desired by the programmer, the occurrence of a given event will signal a
Pascal semaphore. Use this part of the supplement as an update to the
Users Manual, Version IV.O.
New File Handling Facilities
Subsidiary volumes is a file organization tool that creates a two-level file
hierarchy on principal (or physical) disks. This mechanism is useful on large
storage devices such as Winchester disk dri ves. Subsidiary volumes, can
increase the number of files that may be stored on a disk.
User-defined serial devices is a new feature that allows the user to access
more than the standard three serial -devices.
The V(olumes command of the filer has been upgraded to display additional
information that indicates the size, in blocks, of the disks that are on-line.
Also, information pertaining to subsidiary volumes is displayed.
A new filer command called F(lip swap/lock

allows memlocking of the filer's
1-1

Users' Manual Supplemen t, Version IV
In traduction

code segmen ts. This is a convenient mechanism that can be used if your
system has enough memory_ It allows the user to remove the disk containing
the SYSTEM.FILER (and the boot disk, if they are different) while the filer is
being used.
Use this part of the supplement as an update to the Users
Manual, Version IV.O.
The file management units allow programs to simulate the functions of the
filer. For example, directories may be listed and information about files may
be obtained. This part of the supplement is new information which is not
found in the Users Manual, Version IV .0.
Error Message Handing
The programmer may now alter the way in which the p-System displays error
messages. The location of the message on the screen and, in some cases, the
actual message may be changed. The error message is then erased after the
proper user input, and the cursor is returned to its previous position whenever
possible.
These features should be especially useful to applications
developers. Section II.2 of the Users Manual, Version IV.O, is still correct
except for the format of the error messages. There are additional error
handling features described in Chapter IV of this supplement under SETUP.
Execution errors are correct as described in Appendix A of the Users
Manual, Version IV.O.
Compiler Enhancements
The Selective USES statement specifies to the compiler which identifiers from
a uni t are needed. The compiler then selects only the relevant identifiers
thereby reducing c.ompile-time symbol table space requirements. The
selective USES statement is designed for compiling programs that use units
wi th very large interface sections, only a small portion of which is required.
The compiler enchancements section is an update to the Users Manual,
Version IV.O and the UCSD Pascal Handbook.
Extended . Memory
It is now possible to place the code pool outside the stack/heap ,area within
what is called "extended memory". The extended memory· area may be as
large as 64K bytes. This means that the 'p-System may run in configurations
of up to 128K bytes with the current release. The extended memory section
of the 'supplement is new information that is not found in the Users Manu'al,
Version IV.O. See the section on SETUP in Chapter IV of this supplement to
install this feature.

1-2

Users' Manual Supplement, Version IV
Introduction

Echoed Characters
The user may now specify the characters that the keyboard will echo to ~he
screen. Besides the standard ASCII character codes (0 through 127), the
codes 128 through 255 may also be echoed if desired. This part of the
supplemen t is new information that is not found in the Users Manual, Version
IV.O. See the section on SETUP in Chapter IV of this supplement, to install
this feature.
Editor Enhancements
This section describes user-defined tab stops, an addition to the SCet
E(n vironmen t display, byte sex independence of text files created by the
editor, and editor control characters. Use this part of the supplement as an
update to the Users Manual, Version IV .0.
The 8086 and 68000 Assemblers
This section describes the 8086 and 68000 Assemblers. These assemblers are
new to the p-System and are not described in the Users' Manual.
Turnkey Applications Facilities
The p-System will now recognize a user-written executable code file called
SYSTEM.MENU. This file is executed automatically whenever the mail"'!
system prompt line is normally displayed. This facility is useful for creating
applications environments in which users will not be aware of the underlying
p-System environment. Also, the p-System is now available as a tum key
package which does not include such system components as the filer and
editor.
Performance Monitor
It is now possible to write a unit called PERFOPS and place it in the
operating system. This unit allows the user to be cognizant of various pSystem activities such as fault handling and segments being removed from
memory.

1.2

New Optional Facilities

This section describes new optional facilities that are not found in the Users
Manual, Version IV.O. The following topics are covered in Chapter III.
Native Code Generation
A new facility called the native code generator translates P-code, created by
the p-System compilers, into native code, or the machine language of the host
procesor. The resulting code file executes faster than an untranslated code
file.

1-3

Users' Manual Supplement, Version IV
Introduction

Print Spooling
The print spooler is a new facility that allows files to be sent to the printer
during regular use of the p-System. You may, for example, print files and
use the editor at the same time.
CP /M Xenofile
This facility allows you to access files on CP/M disks. This is accomplished
by calling XenoFile from Pascal, BASIC, or FORTRAN just as the CP/M
operating system routines are called.
Turtlegraphics
Turtlegraphics is a new package for creating and manipulating images on a
graphics display. Routines are available to control the colors displayed, draw
figures, alter old figures, save figures in disk files and retrieve them, etc.

1.3

Installation Guide Supplement

This section should be used in conjunction with the Installation Guide to install or
upgrade adaptable systems. Even if you do not have an adaptable system, you
should read through the topics below, or in the introduction to Chapter IV, todetermine if any of the material presented is pertinent to your needs. Chapter IV
discusses the following topics.
Adaptable System Disk Packaging
Adaptable systems are now shipped in a new format as described in this
section.
Event Installation
To install the new even t facili ty, two new SBIOS routines must first be
written: QUIET and ENABLE. Then EVENT (a routine within the BIOS) may
be called from the SBIOS. (The routines QUIET and ENABLE are required in
any case in order to run the current version IV p-System.)
New Definition for PRNST AT
The SBIOS routine PRNST AT now accepts a new parameter as described in
this section. PRNST AT'must ~ be updated to run the current p-System.

1-4

Users' Manual Supplement, Version IV
Introduction

Floating Point Number Configuration
This section describes how to configure the p-System for real numbers. No
floating point package, two word floating point representation, or four word
floating point representation may be used.
Installing GOTOXY
GOTOXY is slightly altered in the current release to allow for keeping track
of the cursor on the screen.
p-System Support for ANSI Terminals
The p-System now can support American National Standards Institute (ANSI)
term in als. If you have such a terminal you should read this section. This
section should also be read by anyone who plans to Library or memlock
Screenops.
The 8086 Adaptable System
This section describes the details of bringing up the adaptable system on the
8086 processor.
SETUP
The SETUP utility has been upgraded in accordance with the rest of this
release. Echoed characters, extended memory, print spooling, subsidiary
volumes, user-defined serial volumes, and code segment alignment are all
affected by SETUP.
Installing Turtlegraphics
If you purchased Turtlegraphics as an adaptable package, you should read this
section in order to install it.
Adaptable Svstem Release Disk Directories
This section lists the directories of the adaptable system release disks. If
you purchased the UCSD p-System as an adaptable system, reference these
listings.

1.. 5

II

NEW AND UPGRADED STANDARD FACILITIES

Chapter II details new and upgraded p-System standard features including the
symbolic debugger, event handling, new filer facilities, error message handling,
compiler enhancements, extended memory, echoed characters, editor enhancements,
the 8086 and 68000 assemblers, file management units, system initialization
enhancements, and performance monitor.

11.1

The Symbolic Debugger

This section of the Users' Manual Supplement, Version IV is a complete description
of the P-code symbolic debugger. Use of the symbolic debugger is described in
Section II.l.8.
The symbolic debugger is a tool for debugging compiled programs, which can be
called from the main system prompt line or can be called during the execution of
a program (when a breakpoint is encountered). Using the symbolic debugger,
memory may be displayed and altered, P-code may be single-stepped, and
markstack chains may be displayed and traversed.
There are no promptlines explaining the debugger commands because such prompts
would detract from the information displayed by the debugger itself. However,
when a command is entered, the system displays several short prompts that may
ask for information.
Many of the debugger commands require two characters (such as 'LP" for LOst
P(code, or "LR" for LOst R(egister). To exit the program after typing the first
character, press  to recall the main mode of the debugger.
To use the debugger effectively, a user must be familiar with the UCSD P-machine
arch i tecture and must understand the P-code operators, stack usage, variable and
parameter allocation, etc. These topics are discussed in the Internal Architecture
Guide.
A· compiled listing of the program is a helpful debugging tool. It helps the user
determine P-code offsets and similar information and should be current.
The debugger is a low-level tool, and as such, must be used with caution.
debugger is used incorrectly, the p-System can fail.

If the

ILI.l Entering and Exiting the Debugger
Press D(ebugger to enter the debugger from the main system prompt line. If the
debugger is entered in a fresh state, the system displays the following prompts.
DEBUG [version II]
(

A fresh state means that the debugger was not previously active, and no
breakpoints are currently enabled. If the debugger is entered in a non-fresh state,

II-I

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

only the left parenthesis "(n appears.
Exit the debugger by pressing Q(uit, R(esume, or S(tep. The Q(uit option disables
the debugger. If the debugger is re-invoked, it is in a fresh state. The R(esume
option does not disable the debugger and execution continues from where it left
off. The debugger is still active; and if it is re-invoked, it is in a non-fresh
state. The S(tep option executes a single P-code and automatically re-invokes the
debugger in a non-fresh state.
If a program is running under the debugger's R(esume command, it may force a
return· to the debugger by calling the HALT intrinsic (described in the Users'
Manua!). In fact, any run-ti me error causes a return to the debugger, if the
debugger is active while the program is runn ing.
The debugger may be memlocked or memswapped (see the descriptions of those
intrinsics) by using the M(emory command at the outer level. "ML" memlocks and
"MS" memswaps the debugger.

11.1.2

Using Breakpoints

To en ter the debugger while a program is running, but not alter the program's
code, use the debugger to set breakpoints. Press B(reakpoint and then use either
the S(et, R(emove, or LCist command. To set a breakpoint, press S(et after
pressing B(reakpoint. There are, at most, five breakpoints numbered 0 through 4.
The system displays four prompts asking for information. The first prompt is-Set Break II?
Enter a digit in the range 0•• 4 and press .

The next prompt is--

Segname?
Enter the name of the desired segment and press .
Procname or

The next prompt is--

II?

Enter the number of the desired procedure and press .
is--

The final prompt

Offset II?
Enter the desired offset within the procedure and press . The system sets
a breakpoin t, and if that segment, procedure, and offset are encountered during
execution resumption, the debugger is automatically re-invoked.

II-2

(

\

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Use a compiled listing of the program to determine the location of the breakpoint.
If no compiled listing is available, use the text file viewing facility. See Section
II. 1.4.
To set a breakpoint that differs only slightly from the one most recently set, press
 for the break number or segment. The system uses the previous
breakpoint's information. For example, to break in the same segment and
procedure but with a different offset, enter a space for everything except the
offset.
To remove a breakpoint, press B(reakpoint, then press R(emove.

The prompt,

Remove break II?
appears.

To remove a breakpoint, enter its number followed by a .

To list the current breakpoin ts, press B(reakpoin t an d then press LOst.

11.1.3

Viewing and Altering Variables

The V(ar command allows the system to display data segment memory. It is
another two-character command that must be followed by G(lobal, L(ocal,
1(n termediate, Eextended, or P(rocedure. If G(lobal or L(ocal is selected, the
system displays the following prompt.
Offset /I?
Enter the desired offset into the data segment.
If I(ntermediate is selected, the system displays the following prompt.
Delta Lex Level?
Enter the appropriate delta lex level for the desired intermediate variable.
If E(xtended is selected, the system displays the following prompt.
Seg II?

Offset II?

Enter the appropriate segment number and offset number for the desired extended
variable.
If P(rocedure is selected, the system may display an offset within a specified
procedure. The following prompts are displayed in sequence.
Segment name?

Procname or II?

Varname or Offset II?

II-3

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

When any of these options are used, the system displays a prompt similar to the
following line.
( t) S = INIT Pill VOIII 2ClA: 08 05 53 43 41 4C 43 61 --SCALCa

This example is a portion of the local activation record for segment INIT,
procedure 1, variable offset 1, at absolute hex location 2CIA. Following this, eight
bytes are displayed, first in HEX and then in ASCII (a dash ,,_It indicates that the
character is not a printable ASCII character).

To view surrounding portions of memory press V(ar. After a line has been
displayed by the V(ar command, a "+" or "_" may be entered. This displays the
succeeding or preceding eight bytes of memory.
The eight bytes that are currently displayed may be ~ltered. If a "I" is typed,
then the line may be altered in hex mode. If a ''\'' is typed, then the line may be
al tered in ASCII mode. When altering in hex mode, any characters that are to be
left unchanged may be skipped by typing . In the f\SCII mode, any
characters to be left unchanged may be skipped by typing .
I t is possible to change the frame of reference from which the global, local, and
in termediate variables are viewed. This can be done by using the C(hain
cornman d. After "Cff is typed the U(p, D(own and LOst options are available. If
ilL tI is typed, all of the currently existing mark stack control words are displayed,
with the most recently created one first. An entry in the List resembles the
following line.

(ms) S=HEAPOPS PII3 01123 msstat=347C msdyn=FOAO msipc=OlDA
msenv=FEE8
This corresponds to a mark stack control word with the indicated static link
(msstat), dynamic link (msdyn), interpreter program counter (msipc), and erec
pointer (msen v). The indicated segment (HEAPOPS), procedure (113), and offset
(1123) are the return point for the procedure call which created the MSCW.
If the U(p or D(own options are used, the frame of reference moves up or down
one link and the frame of reference for variable listings (using the ''V'' command)
changes accordingly.

11.1..

Viewing Text Files from the Debugger

To view a text file from the debugger, press FOle.
following prompt:
Filename?
II-4

First line II?

Last line II?

The system displays the

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Enter the name of the text file to be viewed followed by . The .TEXT
portion of the file name is optional. Then enter the first and last line numbers
that delimit the portion of text that the user wishes to view. This command lists
as many lines as possible in the window from "first line" to "last line" of the
indicated file.
The F(iie command is useful for debugging (especially using symbolic debugging)
when a hard copy of the relevan t compiled listing is not available. Using this
command, the user can view source files on disk and disk files containing compiled
listings without leaving the debugger.

11.1.5

Displaying Useful Information

Whenever control is returned to the debugger (e.g. after a single step operation, or
when a breakpoint is encountered), it displays various information if it is desired.
This in formation may include P-machine registers, the current P-code operator, the
in formation in the current markstack, or any specified memory location. In order
t a select what will be displayed, the E(nable mode should be used. A fter typing
'E', the following options are available at the command level, H(egister, P(code,
M(arkstack, A(ddress, and E(very (all of the preceding). Any or all of these
options may be enabled at the same time.
If R(egister is enabled, a line is displayed after each single step.
line is an example of that display.

The following

Crg) mp = F082 sp = F09C erec = FEE8 seg = 9782 ipc = OlC3 tib =0493 rdyq =2ESC
If PCcode is enabled, a line such as the following is displayed after each step:
(cd) S = HEAPOPS Pfl3 01123

LLA I

If M(arkstack is enabled, a line such as the following is displayed after each step:
(m s) S =HE A POP S P II ") 0112 3 m sst at =347 C m s d y n =F 0 A Oms i pc = 010 A
msenv=FEE8
If A(ddress is enabled, the system generates a display like the following line.
(a ) S =HEAPOPS PII3 01123 2CIA: OS 05 53 43 41 4C 43 61 --SCALea

To initialize this address to a given value, use A(ddress mode at the outer level.
Press A(dress and the system displays the following prompt.
Address?

iI-5

Users' Manual Supplement, Version N
New and Upgraded Standard Facilities

Enter the absolute address in hex. The system displays eight bytes starting at
that address. Also, that address is now displayed if the E(nable A(ddress option is
on.
Enabling E(very causes all of the above options to be enabled.
The DCisable mode disables any of the options just described.
any of the above options.

D.1.6

The LOst mode lists

Disaasembling P-code

A t the debugger's outer level, there is a P-code option that displays the P-code
mnemonics for selected portions of code. This option asks for:
Segname?
Procname or II?
Start Offset II? and End Offset II?
The indicated portion of code is then disassembled. This may be useful during
single-step mode if you wish to look ahead in the P-code stream. This mode may
be exited before it reaches the ending offset by typing ; control returns to
the debugger.

11.1.7

Example of Debugger Usage

Suppose the following program is to be debugged:
Pas c a I Camp i 1e r I V • 0
1 0
2 2
3 2
4 2
5 2
6 2
7 2
8 2
9 2

O:d 1
1:d
1:d
1:d
1:0
1:1
1:1
1:1
:0

End of

Il-6

1
1
4
0
0
3
6
0

{$L LIST.TEXT}
NDT_DEBUGGED;
VAA I ,J ,K: INTEGER;
B1,B2:Bcx:LEAN;
BEGIN
I : =1 ;
J:=1;
IF K <> 1 TJ-EN ~ I TELN ('Whats wrong?');
END.
PR~

Co~ilation.

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

First we enter the debugger and set a breakpoint at the beginning of the IF
statement:
(85) Set break II? 0 Segname? NOTOE8UG Procname or II? 1 Offset II? 6
(EP)
(R)

A fter setting the breakpoint we enable P-code (EP) and resume (R). Now we
execute the program above, and when it reaches offset 6, the debugger is entered.
We single-step twice:
Hit break 110 at S =NOTOE8UG Pill 0116
(cd) S =NOTDEBUG Pill 0116 SLOOI
(cd) S =NOTDE8UG Pill 0117 SLOCI
(cd) S =NOT DEBUG Pill 0118 NEQUI
We see that our first single-step did a short load global 1. (Note: This put K on
the stack. K is NOT global 3; I is global 3, J is global 2, and K is global l.
Every string of variables (such as 1, J, K' in a declaration) is allocated in reverse
order.
Boolean 81, which follows, is at offset 5, and B2 is at offset 4.
Parameters, on the other hand, ARE allocated in the order in which they appear.)
The second single-step did a short load constant 1 onto the stack. Now we are
about to do an integer comparison
But this is where our error shows up, so
we decide to look at what is on the Stack before doing this comparison:

«».

(LR)
(rg) mp =EB62 sp =E882 erec = •••
(A) Address? E882
(a )
EB82: 01 00 C5 14 •••
We list the registers and then look at the memory address to which register sp
points. We discover a I on top of the stack (01 00: this is a least-significantbyte-first machine) followed by a word of what appears to be garbage. This leads
us to suspect that K was not initialized. Looking over the listing, we quickly
realize that this is the case.

11.1.8

Symbolic Oebugging

The sy mboli c debugging feature allows specification of variables by name, rather
than P-code offset. Also, breakpoints and portions of code to be disassembled may
be indicated by procedure name and line number, rather than procedure number and
P-code offset.
Having a current compiled listing of the code in question is still essential for
serious debugging efforts.

II-7

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

To use symbolic debugging, it is necessary that the code being debugged is
compiled with the $0+ option (the Users Manual, Version IV.O describes compiler
options in genera!). The $0+ option, which defaults to $0-, instructs the compiler
to output symbolic debugger information for those portions of a program that are
compiled with $0+ turned on. Once a program is debugged, it should be
recompiled without symbolic debugger information, because this information
increases the size of the code file.
Using symbolic debugging, breakpoints may be specified by procedure name and line
number for all statements covered by the $0+ option. The B(reakpoint command
will request:
"Procname or II?"
En ter the first eight characters of the procedure name.
will be--

The next line displayed

"Firstll_ Lastll_ Linell?"
The underlines will actually be values that define the range of line numbers
av ailab Ie to you within the specified procedure. (These line numbers appear on
compiled listings.) You should then enter the desired line number for your
breakpoint.
Variables within a given routine may be specified by name (rather than data
segment offset number) if at least one statement within that routine is compiled
by $0+. The V(ar. command allows specification of GOobal, L(ocal, I(ntermediate,
or P(rocedure variables in this manner. E(xtended variables are not allowed to be
specified symbolically. The V(ar command will prompt:
-"Varname or Offset II?"
You may enter the first eight characters of the declared identifier.
to the following will then appear:

A line similar

( 1) S=INIT P=FILLTABL V=TABLEI 2CIA: DB 05 53 43 41 4C 43 61 --SCALCa

The segment is INIT, the procedure is FILL_TABLES, and the variable is TABLE!.
Similarly, the code to be disassembled by the P-code command can be specified
symbolically for all portions of code covered by the $0+ option. This command
will request:
Procname or II?

II-a

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Enter the first eight characters of the procedure name.
prompted as follows:
First /I

Last II

Start Linell?

You will then be

End Line/l?

The underlines will actually be the boundaries that are available to you. You
should enter the desired starting and ending line numbers. The specified code will
then be disassembled.

11.1.9

Symbolic Debugging Example

To use symbolic debug9.ing, some part of a Pascal compilation unit must be
compiled with the {$O+I
compile-time directive. A fter this code has been
generated, it is possible to reference variables and procedures by name rather than
offset. The following example is a small Pascal program that has been compiled
with the '0' option.

----------------------------------------------------Pascal Compiler IV.1 cSs-4

3/ 4/82

Page

1

----------------------------------------------------1
2
3
4
S
6
7
8
9

10
11
12
13
14
15
16
17

0
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2

O:d
l:d
1:d
l:d
l:d
2:d
2:0
2:1
2:1
2:2
1:0
1:0
1:0
1:1
1:1
1:1
:0

1
1
1
4
4
1
0
0
5
B

0
0
0
0
3
6
0

{$O+ }
program example;
var a,b,c: integer;

procedure set c i f d;
var d:boolean;
begin
d:=a)b;
i f d then
c:=a*b;
end;

-

begin
a:=O;
b:=S;
set c i f - d·,
- end.

End of Comp i 1a t ion.

II-9

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

The following listing is an example of a debug session.
Debug [xI5]
(85) Segname=E~LE Procn~e or # = SETCIFD
symbol ic seg not in mem Line#? 8
(R )

Hit break#O at S=EXAMPLE P=SETCIFO L#B
(8S) Segname=EXANPLE Procn~ or # = SETCIFO
First#8 Last#lO Line#? 9
(R )

Hit break#l at S=E~LE P=SETCIFD L#9
(VL) Varname or offset#? 0
(1 ) S=EXAMPLE P=SETCIFO V=O E782 : 0000 9448 BEE7 I90C-H(Q )

The first time the debugger is entered, the program example is not in memory and
hence the symbolic segment is not in memory. However, a breakpoint can still be
set sy mbolically providing the user knows on which line number to stop. For the
secon d breakpoint, the symbolic segment is in memory; because of this, its first
and last line numbers are given.
Notice the variable '0' was accessed symbolically, and its contents are displayed.
If the user tries to access symbolically when the actual code segment is in
memory and its symbolic segment counterpart is not present, the system will
display the error message 'symbolic seg not in mem'. Use the 'z' command in the
symbolic debugger to find out if symbolic information is available for a particular
segment.

II-I 0

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

The 'z' command lists all of the principal segments with their environment list.
F or example, the following example is a partial list of the principal segments
(EDITOR and EXAMPLE) and their environments. The lowercase name 'example' is
the symbolic segment for 'EXAMPLE'. The existence of 'example' indicates that
symbolic debugging information is available for at least one procedure in
'EXAMPLE'.
(Z ) the sib is EDITOR
1 KffiJ\EL
2 EDITOR
3 INIT IAL I
4 PASCALIO
5 EXTRAIO
6 mTOXY
7 STRII\GOP
8 EXTRAf-EAP
9 FILECPS
10 cur
11 CXPYFILE
12 ENV I RCNvl

13 PUTSYNTA
14 EDITCXJR
the
1
2
3

sib is EXAMPLE
KffiJ\EL
EXAlvPLE
examp Ie

11.1.10

Interacting with the Performance Monitor

The "I" command will call the PM Interactive procedure within the operating
system if the performance monitor is enabled. The user may, in this way, gain
access to fault handling data, and information concerning what programs have
started and completed execution. For more information, see Section II.II entitled
Performance Monitor.

II-II

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

fi.I.II

Summary of the Commands

A(ddress

Displays a given address

B(reak point
SCet
R(emove
LOst

Segment, procedure and offset must be specified
Allows a break point (0 through 4) to be set
Allows a break pain t to be removed
Lists current break points

C(hain
U(p
DCown
LOst

Changes frame of reference for V(ariable command
Chains up mark stack links
Chains down mark stack links
Lists current mark stacks

F(ile

Allows viewing of text files

E(nable
OCisable
LOst
R(egister
P(code
M(arkstack
A(ddress
E(very
I(nteractive

Enables the following to be displayed
Disables the following from being displayed
Lists the following
The registers: mp, sp, erec, seg, ipc, tib, rdyq
Current P-code mnemon ic
Mark stack display
A given address
A.ll of the above
Interacts with the performace monitor

M(emory
L(ock
S(wap

Memlocks the debugger
Memswaps the debugger

P(code

Dissassembles a given procedure

Q(uit

Quits the debugger, 'fresh' state if re-entered

R(esume

Exits debugger, debugger remains active, 'non-fresh'

S(tep

Single steps P-code and returns to debugger

II-12

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

V(ariable
GOobal
L(ocal
I(nter
P(roc
E(xtended

Z(

Displays
Displays
Displays
Displays
Displays
Displays

global memory
local memory
intermediate memory
data segemen t of given procedure
variables in another segment
segment lists.

II-13

Users' tv1anual Supplement, Version IV
New and Upgraded Standard Facilities

11.2

Event Handling

E v en t handling is a new feature which allows Pascal programs to respond to low
level events. These events include such things as hardware interrupts and low
level I/O actions.
The new print spooler, for example, is able to function concurrently with other pSystem activity through this mechanism. Every time a character is entered at the
keyboard, an event occurs (on those systems set up for print spooling). The
software can take advantage of this knowledge and switch back and forth between
an editing session, for example, and the print spooling process.
To install the event handling facility, the user must add two relatively simple
routines to the SBIOS. These routines are called QUIET and ENABLE and are used
by the p-S ystem to control event handling. It is also necessary to augment the
SBIOS with calls to the new BIOS routine EVENT. These calls will inform the
upper levels of the p-System that it has recognized the event with that number.
This is discussed in Chapter IV of this supplement.
The remainder of this section describes how to use the event handling facility
after it has been installed.
Irrl order to understand event handling, it is necessary to understand Pascal
processes. A process is a routine similar to a function or procedure. Processes
may run concurrently with each other and with the main program. Once a process
is STARTed, it may WAIT on a semaphore before continuing execution. While a
process waits, other processes (including the main program) may resume execution.
When the semaphore in question is SIGNALed, the waiting process may have the
opportunity to resume execution. (For more information concerning processes, see
The UCSD Pascal Handbook.)
An event is assigned a particular number. Whenever that event occurs, the SBIOS
informs the p-System that it has recognized the event with that number. System
events use the numbers 0•• 31 and user-defined events may use the numbers 32 •• 63.)
The Pascal programmer should
Version IV.O and The UCSD
semaphores. When an event
semaphore. If no semaphore
taken.

use the ATTACH intrinsic (see the Users Manual,
Pascal Handbook) to assign event numbers to
occurs, the p-System SIGNALs the corresponding
is A TTACHed to the event number, no action is

Therefore, the occurrence of a low level event may possibly cause a particular
Pascal process to receive processor time.

II-14

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

The following example shows how events might be used. This program assumes
that the SBIOS has been set up to cause event 32 whenever input is received from
a special user device. It executes normally until the user device input is noticed,
at which point it handles that input and returns to normal execution.
PROGRAM USER EVENT;
CONST
EVENT NUM = 32;
VAR
PID: PROCESSID;
S: SEMAPHORE;
FINISHED: BOOLEAN;

PROCESS HANDLE USER INPUT;
BEGIN
-WHILE TRUE DO
BEGIN
WAIT(S);
IF FINISHED THEN EXIT(HANDLE_USER_INPUT);

END
END;
BEGIN
FINISHED: =FALSE;
SEMINIT(S,O);
ATT ACH(S,EVENT NUM);
ST ART(HANDLE_UsER_INPUT ,PID,300,200);

FINISHED: =TRUE;
SIGNAL(S);
END.
In the preceding example, the semaphore 5 is ATTACHed to event number 32.
Then process HANDLE USER INPUT is STARTed with a high priority of 200.
HANDLE USER INPUT then WAITs on S while the rest of the program continues
normal execution. Whenever the SBlaS notices input from the user device, event
32 is caused. This event SIGNALs S, and because HANDLE USER INPUT has a
high priority, it immediately receives processor time to take care of the input.

II-15

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Each time HANDLE USER INPUT returns to the beginning of the loop, it WAITs on
S an d the main program resumes. Finally, the boolean FINISHED is set to true by
the main program and S is SIGNALed directly. This causes an exit from the loop
within HANDLE_USER_INPUT, and the program terminates.
NOTE: An occurrence of ATTACH using a given event number will override any
previous occurrence of ATTACH with that event number. This means that the
first semaphore will no longer be ATTACHed to the event.
NOTE: To detach a previously attached semaphore from an event number, attach
NIL to that event number. For example, Attach(NIL,EVENT NUM); detaches S
from EVENT NUM in the preceding program example.
-

II-16

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

fi.J

New File Handling Facilities

In previous versions of the UCSD p-System, there were 6 blocked devices (4, 5, 9,
10, 11, 12). Each blocked device could contain a maximum of 16 megabytes, and
the p-System could access 96 megabytes of storage. Now the user can change the
number of blocked devices, allowing the p-System to access more than 1.7 billion
bytes of on-line storage. See Chapter IV under SETUP to allocate blocked device
numbers.
Section II.3.1 covers subsidiary volumes, which allows the user to create
subdirectories on a blocked device. Subsidiary volumes are especially useful for
large storage devices such as Winchester Drives. See Chapter IV under SETUP to
allocate device numbers for subsidiary volumes.
Section II.3.2 describes user-defined serial devices, which allow the user to access
more serial devices.
Section II.3.3 describes the upgraded V(olumes command. This filer command now
displays additional information pertaining to the size of disks. Also, information
related to subsidiary volumes is displayed.
Section II.3.4 covers the new F(lip swap/lock filer command. This command allows
memlocking of the filer's code segments on systems that have enough memory to
do so. When the filer is memlocked, the disk containing SYSTEM.FILER (and also
the boot disk, if it is different) may be removed during filer use. This facilitates
the use of the filer, especially on two-drive systems.
Section II.3.5 documents the use of the filer P(refix command.
Section II.3.6 presents a new facility called file management units, which are used
by a Pascal program to accomplish tasks normally performed by the filer.

ILJ.l

Subsidiary Volumes

The purpose of subsidiary volumes is to provide two levels of directory hierarchy
and to expand the p-System's ability to use large storage devices such as
Winchester disk drives. Currently, p-System disk volumes contain a 4-block
directory located in blocks 2 through 5. The rest of the disk is occupied by the
actual files described in the directory. The size of the directory allows for a
maximum of 77 files to reside on the corresponding disk image.
Subsidiary volumes are virtual disk images that actually reside within a standard pSystem file.
(The physical disk is referred to as the principal volume.) Each
subsidiary volume may contain up to 77 files.

U-17

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

A subsidiary volume appears in the directory of the principal volume as a file ..
Subsidiary volume file names can have a maximum of seven characters and must
be followed by the suffix ".SVOL tI. The following listing is an example.
MAIL.SVOL
TESTS.l.SVOL
DOC B.SVOL
The subsidiary volume disk image resides within the actual .SVOL file. The
directory forma t an d file formats are the same as for any other p-System disk
volume.
The volume 10 of the subsidiary volume is that portion of the
corresponding file name that precedes the ".S VOL tI. For example, the three
preceding files would contain the following subsidiary volumes.
MAIL:
TESTS.I:
DOC B:

11.3.1.1

Creating and Accessing Subsidiary Volumes

To create a subsidiary volume, use the filer M(ake command and the file name
suffix, .SVOL. As with any other file created by the M(ake command, the
subsidiary volume will occupy:
1. All of the largest contiguous disk area if created as follows:
Make what file? DOCS.SVOL
2. Half of the largest area or all of the second largest area, whichever is
larger, if created as follows:
Make what file? DOCS.SVOL[*]
3. A speci fied number of blocks, in the first area large enough to hold that
many blocks, if created as in the following examples:
Make what file? DOCS.SVOL[200]
Make what file? DOCS.SVOL[1500]
A fter you have entered the M(ake command to create a subsidiary volume, the
filer will display the following prompt.
Zero subsidiary volume directory?

II-18

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

If the user responds with a ''V'', the directory of the new subsidiary volume will be
zeroed. If the user types an ''Nil, the directory will not be zeroed, and any files
that may have existed on a previous subsidiary volume in the same location will
reappear within the directory. In both cases, the number of blocks indicated
within the directory will always correspond to the size of the actual .SVOL file.
Subsidiary volumes may not be nested.
another .SVOL file.

That is, do not M(ake a .SVOL file within

When a subsidiary volume is created, it is automatically mounted and may be
accessed and used like any other p-System volume. The filer command V(olumes
will indicate that the new volume is on-line, and will show its corresponding device
number (for example, 1113:). Either the volume 10 or the device number may be
used when referencing the subsidiary volume. Files may now be placed on the ne-w
subsidiary volume, and all of the applicable file commands may reference it.

11.3.1.2

Mounting and Dismounting Subsidiary Volumes

This section describes how to mount and dismount subsidiary volumes. It should be
noted that a mounted subsidiary volume is subtly different from an on-line
subsidiary volume.
A mounted subsidiary volume means that the p-System is aware of the existence of
the volume and sets aside a device number for it (e.g., 1113:). It is required that a
subsidiary volume, be mounted before it can be used. While it is mounted, only that
speci fic subsidiary volume will correspond to that device number. A subsidiary
volume stays mounted until it is dismounted. Once mounted, it is on-line anytime
its principal volume is in the disk drive. It is off-line when the principal volume
has been removed from the disk drive.
CA UTION: There is a danger of confusing the p-System if two principal volumes
each contain a subsidiary volume in the same location with the same name. This
might easily be the case where backup disks are used. If these principal volumes
are swapped in and out of the same drive, and the similar subsidiary volumes are
accessed, the filer may become confused in the same way that it can when any
two on-line volumes have the same name.
CAUTION: Low level I/o routines, like UNITWRITE, must be used cautiously with
subsidiary volumes and principal volumes. If a principal volume is removed from a
disk drive, and another disk is inserted, these low level routines have no way of
knowing that the subsidiary volumes that were mounted on the original disk are no
longer presen t. Doing a UNITWRITE to absent subsidiary volumes under these
circumstances will overwrite data on the disk presently occupying the disk drive.

II-19

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

When the p-System is booted, all of the on-line disks are searched for .SVOL files.
All of the corresponding subsidiary volumes are then mounted. The same process
occurs whenever the p-System is I(nitialized.
The booting or initializing process will mount as many subsidiary volumes as it
finds as long as there is room in the p-System unit table. (see Chapter IV under
SETUP for the maximum number of subsidiary volumes.) If the unit table becomes
full, no more subsidiary volumes will be mounted, and no warning is given.
If, after booting or initializing, the user places a new physical disk on-line, any
subsidiary volumes contained on it must be manually mounted if they are to be
accessed.
In order to mount or dismount subsidiary volumes, the filer has a new command:
O(nline/offline. From the main filer prompt type "0" and the following will
appear:
Subsidiary Volume: M(ount, D(ismount
To mount a subsidiary volume, the user can type ''M'' and receive the following
promp.
Mount what vol ?
To dismount a subsidiary volume, the user can type "0" and receive the following
prompt.
Dismount what vol ?
Suppose that a principal volume, P_VOL:, contains the following files:
P VOL:
FILEl.TEXT
FILEl.CODE
VOLl.SVOL
FILE2.TEXT
FILE2.CODE
DOCl.SVOL
-FUN-.SVOL

1I-20

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

To mount subsidiary volumes on P VOL:, the user can respond to the mount prompt
with the file name as in the following examples.
Mount
_Mount
Mount
Mount

what
what
what
what

vol ?
vol ?
vol?
vol ?

VOL1.SVOL 
VOL1.SVOL,-FUN-.SVOL 
P VOL:= 
115: = 

The first example mounts VaLl:, the second mounts VaLl: and -FUN-:, the third
mounts all three subsidiary volumes on P VOL:, an d the fourth example moun ts all
subsidiary volumes on the disk in drive 115:.
To dismount any of these volumes, the user can respond to the dismount prompt
with the VOLUME 10 as in the following examples:
Dismount what vol ? 1114:
Dismount what vol ? VOLl:
Dismount what vol ? VOLl:, DOC1:, -FUN-:
The first example dismounts the subsidiary volume associated with the device
number 14. The second example dismounts VaLl:, and the third example
dismoun ts three. subsidiary volumes.

n.3.1.3

Installation Information

It is very simple to install the subsidiary volume facility into a Version IV system

if the user employs SETUP (described in Chapter IV of this supplement) to set
MAX NUMBER OF SUBSIDIARY VOLS to the smallest convenient value. This will
be the maximum number of subsidiary volumes that will be allowed to be mounted
at one time. (Each additional subsidiary volume requires a few extra bytes within
the p-System's unit table.) When this has been done, the subsidiary volume facility
will be available.

11.3.2

User-Defined Serial Devices

The user-defined serial device facility is a new feature that allows the user to
take advantage of serial I/O hardware capabilities. This facility, along with the
standard serial I/O capabilities (CONSOLE:, REMIN:, and REMOUT:) can be used on
machines with special serial I/O hardware.
The user may have up to 16 devices in addition to a print, console and a remote.
User-defined serial devices may include additional printer ports, additional consoles,
communication lines between users in a multi-user environment, etc.

II-21

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

This feature will not be available through the adaptable system BIOSes. See
Chapter IV of this supplement under SETUP to configure the system to omit or to
accommodate user-defined serial devices.

D.3.3

The Flip Swap/Lock Command

The following command is a new item on the filer prompt line.
F (lip swap/lock
This command can facilitate use of the filer on systems that have enough memory.
The Pascal code that makes up the filer is divided into several segments. Not all
of the segments are needed at the same time. By removing unneccessary
segments from memory, more memory space is available for the filer to perform
its tasks.
F or example, a T(ransfer will work much more efficiently if there is a
large buffer area available in memory. Furthermore, on some machines, there is
simply not enough memory space to contain the entire filer.
However, allowing the filer to have nonresident segments requires that the disk
con taining SYSTEM.FILER be accessed whenever a non-resident segment is needed.
This can be inconvenient on most two-drive systems. It would be more convenient
to en ter the filer, remove the system disk if desired, and perform any combination
of L Osting, disk to disk T(ransferring, K(runching, etc., without having to replace
the system disk at frequent intervals.
In the first mode, the filer segments are memswapped, and in the second mode,
they are memlocked. The F(lip swap/lock command allows the user to make the
choice of which mode the filer will use. The initial state upon entering the filer is
always memswapped. Pressing IF" acts as a toggle between the memswapped and
memlocked states. For example, if you entered the filer and pressed IF" twice,
you would receive two prompts similar to the following:
Filer segments memlocked [9845 words]
Filer segments swappable [13918 words]
The number of available 16-bit words is given so that you will have an idea of
how much space is left for the filer to perform its functions. There is usually
less space available in the memlocked mode. If the machine does not have enough
space to memlock the filer segments, the user will receive a message indicating
th at lack of space. (If there is not at least 1500 extra words available, the filer
will not allow the memlock option.)

II-22

Users' Manual Supplement, Version IV
New and Upgrade.d Standard Facilities

ll.3.4

The V(olumes Command

Some additional information has been added to the V(olumes display. The sizes of
on-line disk volumes are now given. In the following example, three volumes are
on-Une. Typing '''''' from the main filer prompt causes the display:
Vols on-line:
CONSOLE:
1
2
SYSTERM:
4 II WNCHSTR: [12000]
5 II FLOPPY1: [ 494]
6
PRINTER:
12 II FLOPPY2: [ 500]
Root vol is - WNCHSTR:
Prefix is
- FLOPPY2:
A fter each disk volume, the number of 512-byte blocks that it contains is given in
square brackets. This can be useful if the system uses disks of varying storage
capaci ties. In the preceding example, the Winchester Disk on-line in drive 114:
contains 12000 blocks of storage capacity, and the floppies on-line in drives 115:
and 1112: contain 494 and 500 blocks respectively.

The V(olumes command also displays the mounted subsidiary volumes. The name of
the principal volume and the name of the starting block are given for each
subsidiary volume listed. The following listing is an example.
Vols on - 1 in e :
CXNSQE:
1
SYSTERIv1:
2
4 /I 'AN:HSTR:
5 /I FLOPPY1 :
PRINTER:
6
12 /I FLOPPY2:
13 II co::S:
14 II PRcn=. Thus, the words trout, salmon, and tuna are acceptable substitutions
for the meta-word . The following expression is an example of the the
substitution.


=

trout I salmon I tuna

II-25

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

The equal sign indicates that the meta-word on the left side can be substituted
with the word on the right side. The bar (I) separates possible choices for
substitution. The preceding example indicates that trout, salmon, or tuna can be
substi tuted for .
An item enclosed in square brackets [ ] may be substituted into a textual
expression. For example, [micro]computer can represent the text strings computer
and microcomputer.
An item enclosed in braces { } can be substituted zero or more times into a
textual expression. The following expression represents responses to jokes
possessing varying degrees of humor.


= {hal

Literal occurrences of characters or strings of characters are delimited by quotes
to avoid confusing them with notational definitions
F or example:

left-bracket

= n<" I "" I

'tr'

The terminology used in describing the file system is defined in the Users Manual,
Version IV.O. The term  is used throughout this document; it is a
gen eric term encompassing serial and disk volumes, disk files, and unused areas of
disk volumes.

11.3.6.1.2

Wild Cards

Most DIR INFO routines allow  in their file name arguments. A
description of wild card facilities and operation is given in the WILD UNIT
definition.

II-26

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

".3.6.1.3

File Name Arguments

Most OIR INFO routines accept file name arguments. The file name specifies the
volume and/or file to be accessed by the routine. See the Users Manual, Version
IV.O for a complete description of UCSO p-System files and file names.
File name syntax:


:

[volume-IO]

(file-IO]



:

[ "II" uni t-number ":"1
volume-name n: "I

":" I ''* n I ''*: " ]



:

[ti tIe suffix specifier]



:

'p'number',]" I 'P'*',]"

Volume names and file titles may contain wild cards. Unit numbers and colons
separating volume IDs and file IDs must appear literally; they must be independent
of any wild card.
All OIR INFO routines except 0 Scan Title ignore file length specifiers. File name
conven tions in DIR INFO differ slightly from UCSO
p-System file name
conventions in some cases:
OIR INFO considers an empty file name argument to specify the prefix volume;
i.e.,- < file-I 0> is empty (implying a volume reference), and  is empty
(implying the prefixed volume). An empty string is not a valid file name in the
p-System.
OIR INFO in terprets wild card file names of the form :: to be valid
volume specifiers. This is consistent with OIR INFO's definition of the n=" wild
card, but inconsistent with the UCSD p-System Filer's interpretation of the n:"
wild card; the filer does not accept file names of this form as volume
specifiers.

II.3.6.1.4

File Type Selection

Some OIR INFO routines accept a  pax:ameter (named 0 SELECT) which
is used to- specify the file objects to be accessed.
(File objects include volumes,
unused areas on disk volumes, temporary files, text files, code files, and data
files.) The file type parameter is necessary because file names are not sufficient
to completely specify all types of file objects (e.g. unused disk areas). The routines
which generate directory information use both the file name argument and the
o SELECT parameter to determine the file objects on which to return information.
II-27

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

OIR INFO defines a scalar type, which is used to specify file objects. 0 SELECT
is declared as a set of this type; a file object is selected by including its
corresponding scalar in 0 _SELECT.
F He object types:

O_NameType

o

Choice

= (D_Vol, O_Code, O_Text,
= Set Of D_ NameType;

O_Oata, O_SVol, O_Temp, OJree);

The scalar values are defined as follows:

o Vol--Select all volumes matching the file name argument. Note that while
vOlume names may contain wild cards, unit numbers must be specified literally.

o F re e--Select all unused areas of disk space on the
name argument.

volumes matching the file

o Temp--Select all temporary files matching the file name argument. Files are
considered temporary if they have been opened (but not yet locked) by a
program.
0_Text--Select all text files matching the file name argument.
0_Code--Select all code files matching the file name argument.
0_Oata--Select all data files matching the file name argument.

o SVol--Select
11.3.6.1.5

all svol files matching the file name argument.

File Dates

Disk files and disk volumes are assigned . File dates are stored in
records of type D_Oate_Rec and are accessed and modified by the OIR INFO
routines D_Oir_List and O_Change_Oate.

o Date Rec is declared as follows:

o

II-28

DateRec

= Packed

Record
Month : 0•• 12;
Day
: 0 •• 31;
Year : 0 •• 100;
End~ D_DateRec }

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

A year value of 100 in a file date record indicates that the object is a temporary
disk file. (This is a UCSO p':'System file system convention.)

0.3.6.1.6

Error Results

All OIR INFO routines which access file system information return a value
reflecting the result of the file system operation. This result indicates either that
the routine finished without errors or that an error occurred; valid information is
not returned when routines return a result value indicating the occurrence of an
error.
Error causing conditions include:
The specified files, volumes, or unused spaces can not be found in the disk
directory.
The specified unit is off-line.
The file name argument has improper syntax.
The specified file name conflicts with an existing file.
In no cases can an error cause abnormal termination of a function; errors which
cannot be identified explicitly by the routine are flagged by retuming a result
indicating that an unknown error has occurred.
OIR INFO defines a scalar type to describe the possible errors encountered:
Type

0 Result=

(0 Okay,

o Not Found,
O-Exists,
O-Name Error,
O-Off LTne,
D=Other);

Details on error results and the status of the retumed directory information in the
presence of an error can be found in the descriptions of each of the unit
procedures.

II-29

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

11.3.6.1.7

DIR INFO Interface

Interface
uses
(*$UWILD.CODE*)
wild;
Type

o

DateRec = Packed Record
Month : 0 •• 12;
Day
: 0•• 31;
Year : 0 •• 100;
End;
o NameType = (0 Vol, O_Code, D_Text, O_Oata, O_SVol,
-0 Temp, 0 Free),
o Choice = Set of 0 NameType;
O-ListP = "'0 List; O-List = Record
0_Un it: In teger;
0_Volume : String[7];
o VPat : 0 PatRecP;
O-NextEntry : 0 ListP;
Case 0 IsBlkd : Boolean Of
True -: (0 5 tart,
-O_Length : Integer;
Case 0 Kind : 0 NameType Of
o VaT;
O-Temp,
O-Code,
O-Text,
a-Data,
O-SVol:
-(0 Title : S6rWg[15];
o FPat : _ atRecP;
O-Oate : 0 OateRec;
Case 0 NameType of
0_Vol:(O_ NumF iles:Integer)));
End;

II-30

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o

Result

= (0

Okay,
-0 Not Found,
O-Exists,
O-Name Error,
O-Off Line,
O=Other);

Function O_Oir_List(O_Name : String;
o Select : Choice;
Var 0 Ptr : -0 ListP;
O_PlniO : Boolean): O_Result;

°

Function O_Scan_Title{O_Name : String;
Var 0 VoIIO,O TitleIO : String;
Var O-Type : 0 NameType;
Var O=Segs : Integer)
: O_Result;
Function 0 Change Name(D OldName,
D_NewName: String~
RemOld : Boolean
: D_Result;

°

Function O_Change_Date(O_Name : String;
NewOate : 0 OateRec;
O_Seiect : O_Choice) : O_Result;

°

Function O_Rem_Files (O_Name : String;
Select

°

O_Choice)

O_Result;

Procedure 0 Loc~
Procedure O=Release;
Function O_Krunch (D_Unit:integer; D_Block:integer): O_Result;
Function 0 Mount (0 File Name:String): 0 Result;
Function O-OisMount-(O_Vol_Name:String):-O_Result;

II-31

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

D.3.6.1.8

Detailed Descript,ior:l of Functions

Function D_Krunch (D_Unit:integer; D_Block:integer) D_Result;
This function will move the files on the volume specified by 0 Unit. The block
indicated by 0 Block will be inclu,ded in the resulting unused disk space area.
Files located befure 0 Block will be moved forward (toward the directory) and files
after it will be moved-backward (toward the last track).
NOTE: Using 0 Krunch on a volume that contains an executing or open file
(including the operating system) may destroy the files. If Function D_Krunch
changes the location of an open or executing file, the system will return data to
the previous, not present location of the file.

The 0 File Name parameter identifies a subsidiary volume that is to be mounted.
Wild cards may be used. The volume will be mounted unless 0 Result indicates
otherwise.

Function 0 DisMount (D_Vol_Name:String):O_Result;
The subsidiary volume identified by the 0 Vol Name parameter is dismounted.
volume must be a subsidiary volume.
--

This

Function 0 Scan Title(D NAME:String; Var 0 VOLUME,
D_TITLE: String;Var D_TYPE: D_NameType; Var D_SEGS: Integer):D_Result;

o Scan Title parses the UCSO p-System file name passed in 0 NAME, and returns
the file name's volume 10, file title, file type, and file length specifier. The
function result indicates the validity of the file name argument. 0 Scan Title does
not determine whether or not 0 Name actually exists.
Parameters and Function Results:
0_Scan_Title accepts the following parameters.
O_NAME--A string containing a UCSO p-System file name.

o

VOLUME--A string which returns the volume 10 contained in 0 NAME. If
O-NAME contains no volume 10 or if the volume 10 is ':', 0 VOLUME is
assigned the system's default volume name. If the volume 10 is '*" or '*':',
o VOLUME is assigned the system's boot volume name. Volume names assigned
to 0 VOLUME contain only upper case characters, and do not contain blank
characters.

11-32

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o

TITLE--A string which returns the file title contained in 0 NAME. If
O-NAME does not contain a file title, 0 TITLE is assigned the empty string.
File titles assigned to 0 TITLE contain oni'Y upper case characters, and do not
contain blank characters.-

o TYPE--A scalar which returns a value indicating the file type of the file
name contained in 0 NAME.
Definition of 0 TYPE's scalar type:
OYJameType

= CD_Vol,

D_Code, D_Text, O_SVol, D_Oata, D_Temp, D_Free,);

D TYPE is set to 0 Vol if the file title in D NAME is empty. 0 TYPE is set
to D Code if the fii'e title is terminated by 't:CODE" or to 0 Text if the file
ti tIe IS terminated by ".TEXT" or ".BACK". 0 TYPE is set to' D SVOL if the
file title ends with .SVOL (a subsidiary volumeJ. If none of the- above holds
true, D TYPE is set to D Data. Only the suffix of a file is used for
determine what type it is. -For example, the file name SYSTEM.COMPILER
is returned as a data file because it's suffix is not .COOE •
D SEGS--An integer that is assigned a value indicating the presence of a file
length specifier in D_NAME. The value returned in 0 SEGS is assigned as follows:
LENGTH SPECIFIER

D SEGS VALUE

[]



[*]
 0 Then
Wrifeln(' Segment flag
, Seg_Flag);
end;
d name e.rror:writeln(' Name error');
end; Writeln;
Write('Continue? ');
Read(Ch);
wrrteln;
Until Ch In ('n', 'N1;
End. { Scan_Test}
.
11-34

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Function 0 Dir List (0 NAME:String;
-

-

-

DSREcr
Var 0 PTR

o

PINFO

: 0 Choice;
: DListP;
: Boolean) : O_Result;

o Oir List creates a list of records containing directory information on volumes
and disk files. This information includes volume names and unit numbers of
blocked and unblocked on-line units, number of files on blocked units, lengths and
starting blocks of disk files and unused disk spaces, file names and types, and file
dates. The function result value indicates invalid file name arguments, off-line
volumes, or not-found files.
o Oir List optionally provides information describing how the wild card file name
argument matched files and/or volumes.
Parameters and Function Results:

o

Oir List accepts a set specifying the file types on which to return
and a- string containing a file name. 0 Oir List returns a pointer to
of directory information records. Each record contains the name
volume which matches the file name argument and also is one
specified in the file type set.

information,
a linked list
of a file or
of the types

o NAME--The 0 NAME parameter contains a file name which may contain wild
cards.
o SELECT --The 0 SELECT parameter is a set specifying the directory objects
for which information is to be returned by 0 Oir List. See the file type
selection for more information on directory object selection.
o PTR--The 0 PTR parameter is assigned a pointer to a linked list of records
con taining directory information for all specified file objects. In order to have
information returned describing it, a file object must meet the following
criteria:
It must reside on a volume which matches the volume 10 in 0 NAME.
If the object is a disk file, it must match the file 10 in 0 NAME.
It must belong to one of the types included in 0 SELECT.

II-35

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

The linked list contains one record for each file object matcheQ. The records
are defined as follows:

o ListP = AD List;
D-List = Record
0_Unit : Integer;
0_Volume : S tri 9[7];
o VPat : 0 Pat ecP;
O-NextEntry : 0 ListP;
Case 0 IsBlkd : Boolean Of
True -: (0 Start,
--O_Length: Integer;
Case 0 Kind : 0 NameType Of
OVal,
O-Temp,
O-Code,
O-Text,
O-Oata,
O-SVol:

R

(0 Title : String[15];
o FPat : 0 PatRecP;
O-Oate : D-OateRec;
Case 0 NameType of
0_Vol:(b_ NumFiles:Integer)));
End;

The fields in the 0 List record return the following information for each file
object in the 0 ytr liSt:

o

Unit returns the unit number of the unit containing the object.

O_Volume returns the name of the volume containing the object.

o

VPat is a pointer to
volumes to the volume
pattern matching info).
not requested.

pattern matching information collected while comparing
10 in 0 NAME (see the wild card UNIT for details on
0 VPat is set to NIL if pattern matching information is
-

o NextEn try is a pointer to the next directory information record in the list.
It-is set to NIL if the current record is the last record in the list.
o IsBlkd is set to TRUE if the file object is (or resides on) a block-structured
unit. Records describing serial volumes have DIsBlked set to FALSE; the
remaining fields are undefined.

II-36

Users' Manual Supple men t, Version IV
New and Upgraded Standard Facilities

The following fields exist only in records describing file objects stored on disk
units (i.e. O_IsBlkd is TRLE):

o Start contains the starting block number of the file object. If the object is
of type 0 Vol, this value is interpreted as the block number of the first block
on the volume (e.g. 0 for disk volume).
o Length contains the length (in blocks) of the file object. If the object is of
type 0 Vol, this value is interpreted as the total number of blocks on the
volume 1e.g. 494 for single density 8" floppy disk).

o Kind

indicates the type of the file object described by the current record.

The following fields exist only in records describing disk file objects other than
unused disk areas (i.e. 0 Kind in [0 Vol, 0 Temp, 0 Code, 0 Text, 0 Data,
o_SVol]):
o Title can tains the file title of the object.
fi"eld contains the empty string.

F or objects of type 0_Vol, this

o FPat is a pointer to pattem matching information collected while comparing
fiTe n ames to the file 10 in 0 NAME (see wild card UNIT for details on pattern
matching info). 0 FPat is set NIL if pattern matching information is not
requested or if the file 10 in 0 NAME is empty.
0_Date contains the file date for the current object.

o NumFiles is valid only for objects of type 0 Vol; it contains the number of
files in the volume's directory.
NOTE: An .SVol file (which contains a subsidiary volume) appears as any other
file on the principal volume. This means that 0 NumFiles does not correspond
to an .SVol file. However, the actual subsidiary-volume, when accessed by its
volume 10, will return with a valid O_NumFiles entry.

II-37

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

File information is returned (in a linked list accessed
order:

by D_Ptr) in the following

1. Volume on highest numbered unit which matches 0 NAME (if 0 Vol is in
D_SELECT)
2. Files in directory of this volume which match 0 NAME and are of one of
the types in D_SELECT (if a file type is in D_SELECT)
Last file on volume
First file on volume
3. Unused spaces on this volume (if 0 Free is in 0_SELECT)
Last free space on volume
First free space on volume
4. Volume on lowest numbered unit which matches 0 NAME (if 0 Vol is in
D_SELECT)
5. Files in directory of this volume which match 0 NAME and are of one of
the types in D_SELECT Of a file type is in D_SELECT)
Last file on volume
First file on volume
6. Unused spaces on this volume (if 0 Free is in D_SELECT)
Last free space on volume

.

First free space on volume

II-38

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o

PINFO

When set to TRUE, the 0 PINFO parameter indicates that pattern matching
information should be returned in a linked list accessed by 0 PTR. This
information is collected by the 0 WILD MA TCH function in the process of
comparing volume and fileIO's, and is useful for determining how the wild cards in
o NAME were expanded. Information is retumed in two pointers; one for volume
names matched (named O_VPat) and one for file lo's matched (named DY-Pat).
Example of pattern record lists:
D_NAME is set to ' = :TEST{1-9} ='
Two volumes contain files which match 0 NAME:
BOOT contains TEST5.COCE
WORK contains TEST 5. TEXT
For BOOT:TEST5.CODE, D Volume is 1300T', 0 Title
o_VPat retums a pointer to -the following information:
1.

is IEST5.CODE', and

WildPos is 1, WHdLen is 1
CompPos is 1, CompLen is 4
(' =' matches 1300T')

oJPat

retums a pointer to the following information:

1.

WildPos is 1, WildLen is 4
CompPos is 1, CompLen is 4
(lEST' matches lEST')

2.

WildPos is 5, WHelLen is 5
ComRPos is 5, CompLen is 1
('{1-9}' matches '5')

3.

WildPos is 10, WildLen is 1
CompPos is 6, CompPos is 5
(' =' matches '.CODE')

A similar list is retumed for WORK:TEST5.TEXT.
NOTE: If the volume 10 in 0 NAME consists of a unit number (e.g. "115"), the
volume assigned to the unit is defined to match the volume 10 in D NAME. The
Pas and Len pointers are set as in the following example:
-

ll-39

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o NAME

is set to "115:"

A disk volume named 'FOONtt resides in un it 5.
1.

WildPos is 1, WildLen is 2
CompPos is 1, CompPos is 4
('/15' matches rOON,)

NOTE: 0 FPat and 0 VPat never contain invalid information. If information is
unavailable -or has not been requested, the pointers are set to NIL.

Function Result

o Dir List returns a value of type 0 Result. 0 Dir List can return all scalar values
defined in O_Result except O_Exists; the values-have the following meanings:
0_Okay--No error.

All 0 Ptr information is valid.

o Not Found--No such file/volume found.
D-Oir List sets D Ptr to NIL.

-

No match found for D NAME.

-

O_Name_Error--Illegal syntax in 0 NAME.

0 Dir List sets 0 Ptr to NIL.

DOff Line--Volume/unit off-line. The volume specified by 0 NAME was not online. - This error occurs only when the volume 10 in 0 NAME does not contain
wild cards (i.e. a single volume is specified, and it is off-line). If the volume
name in 0 NAME contains wild cards but does not match anyon-line volumes,
o Dir List returns 0 Not Found. 0 Ptr is set to NIL.

-

-

-

o Other--Unknown error. 0 Dir encountered an error it could not identify, but
which interrupted normal execution of the function. 0 Ptr is set to NIL.
Example Program:
The following program is a general purpose directory lister; it accepts a string
containing wild cards and creates a list of matching files and (if requested) pattern
matching information for the files. Note that the program uses the MARK and
RELEASE intrinsics to remove the 0 Dir List information from the heap after the
information has been used.

Il-40

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Program Listtest;

Uses
(*$UWILD.CODE*)
wild,
C*$UDIR.INFO.CODE* )
Dirinfo;
Var

Select : 0 Choice;
Want Pattems : Boolean;
Heap=Ptr : "'Integer;
Segs : Integer;
Typ : 0_NameType;
Volume, Title, Match : String;
Result : 0 Result;
Ch : Char;
Ptr : 0_ListP;
Procedure GiveChoice(Choice
Var
Ch : Char;

String; Kind

0_Choice);

Begin
Write('
',Choice,' ? ');
Read(Ch); Writeln;
If Ch In ['y', 'Y1 Then Select : = Select + Kind;
End; { GiveChoice }
Procedure Print_Pattems(PatPtr

o

PatRecP;
- Camp, Wild

String);

Var

Count :

Inte~er;

Begin { Print Pattems }
Count := -1;
Writeln('type  for patterns');
Readln; Writeln;
Repeat
Writeln('Pattern " Count, ' :');
With PatPtr'" Do

Begin
Writeln(' Comp:', Comp);
If CampLen <> a Then
Write(''''':(CampPos + 9));
If CampLen > 1 Then Write(''''':(CompLen - 1));
ll-41

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

Writeln;
Writeln(' Wild:', Wild);
Write('" ':(WildPos + 9));
If WildLen > 1 Then Write('''' ':(WildLen - 1));
Writeln; Writeln;
-End;
P atPtr : = PatPtr'" .Next;
Count: = Count + 1;
Until PatPtr = Nil
End; { Print_Patterns }

Procedure Print_Info(Ptr

D_ListP);

Begin { Prin t In fo }
Repeat With Ptr'" Do
Begin
If 0 IsBlkd Then
Case 0 Kind Of
o Free : Write('Free space on ');
O-Vol : Write('Volume ');
D-Temp : Write('Temporary file on ');
D-Text : Write('Text file on ');
D-Code : Write('Code file on ');
D-Oata : Write('Data file on ');
D-SVol : Write('SVol file on ');
End { Cases} - Else
Write('Unblocked volume ');
WrTEeiii(D Volume);
If Want Patterns And (0 VPat <> Nil) Then
Begin
Writeln;
Writeln('
Volume patterns:');
Print Patterns(D VPat, D Volume, Volume);
End;
Writeln('
Unit number ••••••• " 0 Unit);
If 0 IsBlkd Then
Begin
If Not (D Kind In (0 Vol, D Free]) Then
Writeinr
File name .:....... " 0 Title);
If D Kind <> 0 Free Then
Begin
If Want Patterns And (0 FPat <> Nil) Then
Begin
Writeln('
File name patterns:');
U-42

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

Print Patterns(D FPat, 0_Title, Title);
End; With 0 Date Do
WriteIn('
File date ••••••••• "
Month, '1', Day, '1', Year);
End; { If 0 Kind}
If 0 Kind = 0 Vol Then
Writeln(' Files on volume ••• " 0 NumFiles);
Writeln('
Starting block .... " O-Start);
Writeln('
File length ••••••• " 0 Length);
End; { If 0 IsBlkd }
End; { With Ptr
A

}

Writeln;
Write(Iype  for rest of list');
"Re8din; Wri teln;
Ptr : = Ptr .0 NextEntry;
Until Ptr = Nil End; { Print_Info }
A

Begin { 0 Test}
Repeat
Mark(Heap Ptr);
Select : = "0;
Writeln('Oirectory Lister --');
Write('Volume andlor file name to match: ');
"Re8din(Match);
Write('Retum pattern matching information? [yIn] ');
Read(Ch); Writeln;
Want Patterns : = Ch In ['y', 'Y1;
If Want Pattems Then
Result : = 0 ScanTitle(Match, Volume, Title, Typ, Segs);
Writeln(Iypes [yIn ] : ');
GiveChoice('oirectories', [0 Vo!]);
GiveChoice(Iext Files " [DText]);
GiveChoice('Code Files " [[) Code];
GiveChoice('oata Files " [o-Oata]);
GiveChoice(Iemp Files " [15 Temp]);
GiveChoice('Free Space " [O-Free]);
GiveChoice('SVol Files " [0 5Vol];
Result : = 0 OirList(Match, Select, Ptr, Want_Patterns);
Writeln;
If Ptr <> Nil Then
Print Info(Ptr)
Else
Case Result Of
o Name Error Writeln('
Error in file name');
II-43

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o

Volume off line');
Off Line : Writeln('
O-NotFound : Writeln('
File not found');
O-Other : Writeln('
Miscellaneous error~);
End; Tcases}
Writeln;
Repeat
Write('Continue ? ');
Read(Ch); Writeln;
Until Ch In ['n','N','y', 'Y'];
Writeln;
Release(Heap Ptr);
Until Ch In ['n';- 'N1;
End. { listtest }

Function D Change Name (0 OLD NAME,
- 0 NEW NAME :String;
D-REMOLD
: Boolean) : D_Result;

o

Change Name searches for the volume or file designated by the file name
contained- in 0 OLD NAME and changes its name to the fHe name contained in
D NEW NAME. -

-

-

o

Change Name only changes one file name at a time, and thus does not accept
fiTe names containing wild cards; however, it can be combined with other Oir Info
and wild card routines to create user~efined file name changing routines which
accept wild cards.

Parameters and Function Results:
0_Change_Name accepts the following parameters:
DOLO NAME--A string containing the name of the file to be changed. If the file
name is invalid, 0 Change Name returns D Name Error. Note that wild card
characters are treated literally.
--

o

NEW NAME--A string containing the replacement file name. If the file name is
invalid,-D Change Name returns 0 Name Error. Note that wild card characters are
treated literally. --

If 0 OLD NAME contains an empty file title, 0 Change Name changes the name of
the volume specified by 0 OLD NAME to the volume name in 0 NEW NAME; any
file title in 0 NEW NAME-is ignored. If 0 OLD NAME contains an nonempty file
ti tIe, 0 Change Name changes the name of the dTsk file specified by 0 OLD NAME
to the file title in 0 NEW NAME; any volume name in 0 \'-JEW NAME is ignored. If
the file 10 in 0 NEW-NAME is empty, O_Change_Name returns -D~ame_Error.
II-44

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

D REMOLD--If set to TR UE, 0 REMOLD indicates that an existing file or volume
designated by the file name in -0 NEW NAME may be removed in order to change
the file name. If set to F ALSE;- the presence of an existing file or volume with
the same name as D NEW NAME aborts the name change, and 0 Change Name
returns 0 Exists as a function- result.
-

o

Change Name retums a value of type 0 Result. 0 Change Name can retum all
sCEdar values defined in 0_Result; the values have the following meanings:
D_Okay--No elTor.

D_OLD~AME

was found and its name changed.

o Not Found--No such file/volume found.
No change made.

No match found for 0 OLD NAME.

o

Exists--The name change was blocked by the presence of an existing file with
the same name as D~EW~AME. No change made.

D Name Error--Illegal file name syntax in D OLD NAME or 0 NEW NAME.
change made.
DOff L ine--Volume/unit off-line.
not on-=line. No change made.

o Other--Unknown.

No

No

Volume/unit specified by 0 OLD NAME was

D_Change_Name encountered an eITor it could not identify.

change made.

Programming Example:
The following program demonstrates the use of 0_Change_Name.

Program chngtest;
Uses
C*$UWILD.CODE*)
wild,
C*$UDIR.INFO.CODE* )
Dirlnfo;
Var
RemOld: Boolean;
Old, New : String;
Ch : Char;
Rslt : 0_Result;
Begin { chngtest}
Writeln('D_ChangeName Test --');
II-45

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Repeat
Writeln;
Write('Name to change ');
Re'8ciln(Old);
Write('New name : ');
Re'8ciln(New);
Write('Rernove existing files (if any) of that name? [yIn] );
Read(Ch); Writeln;
RemOld : = Ch In ['y', 'Y1;
Case 0_ChangeName(Old,New ,RemOld) Of
o Okay : Writeln('
No error');
O-Off Line : Writeln('
Volume off line');
O-Name Error : Writeln{'
Error in file name');
O-Not Found : Writeln('
File not found');
O-Other : Writeln(,
Miscellaneous error');
End; { cases }
Writeln;
Write('Continue ? ');
Read(Ch); Writeln;
Until Ch In ['n', 'N1;
End. { chngtest }
Wild Card File Name Replacement

o Change Name does not accept wild card file name arguments; however, it can be
combined- with the pattern matching information returned by 0 Dir List to
implement a wild card, file name changing routine. (Note that this routine must
use directory locks in multi-tasking environments.)
F or example, assume that the user has the following files:
TESTI.TEXT
TEST I2.CODE
TEST.DATA
The user would like to change them to:
OLDIA.TEXT
OLDI2A.CODE
OLDA.DATA

II-46

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

This can be performed by using 0 Dir List to search for the file name lEST =. ='.
The pattern matching information- returned by D Dir List can be used to create
ne w file ti tIes; in this case, lEST' is replaced with- 'OLD', and the first ' =' is
replaced with the catenation of the pattern matched by the ' =' and the literal
string 'A'. The part of each file title matched by the period and the second
n=" wild card is unchanged. D Change Name is called with the modified file title
for each file matched by 0_Dir_List.
Programming Example:
The following program demonstrates the use of 0 Change Name and 0 Dir List in
the construction of a specialized file name changing utilitY: The program accepts a
file name argument containing two ' =' wildcards; for each file which matches the
argumen t, the file title is changed by swapping the string patterns matched by the
two "=" wildcards.

Program WildChng;
Uses
(*$UWILD.CODE*)
wild,
(*$UDIR.INFO.CODE*)
DirInfo;

Var
Heap_Ptr : "Integer;
Typ : 0 NameType;
Segs : Integer;
Select : 0 Choice;
Volume, Name, Match: String;
Result: 0 Result;
Ch : Char;
Ptr : D_ListP;
Procedure GiveChoice(Choice
Var
Ch : Char;

String; Kind

0_Choice);

Begin
Write('
',Choice,' ? ');
Read(Ch); Writeln;
If Ch In ['y', 'Y1 Then Select : = Select + Kind;
End; { GiveChoice }
Procedure Printyattems(PatPtr

0 _PatRecP;

U-47

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Comp, \Vild : String);
Var
Count : Integer;

Begin { Print Patterns }

Count := 1;
Writeln('type  for patterns');
Readln; Writeln;
Repeat
Writeln{'Pattern " Count, ' :);
With PatPtr Do
A

Begin
Writeln(' Comp:', Comp);
If CompLen <> a Then
Write('''' ':(CompPos + 9»;
If CompLen > 1 Then Write(''''':(CompLen - 1»;
Writeln;
-Writeln(' Wild:', Wild);
Write('''' ':(WildPos + 9»;
If WildLen > 1 Then Write(''''':(WildLen - 1»;
Writeln; Writeln;
--

End;

PatPtr : = PatPtr'" .Next;
Count := Count + 1;
Until PatPtr = Nil
. End; { Print_Patterns }

Procedure Print_Info(Ptr

O_ListP; Want Patterns: Boolean;
- Volume, Name : String);

Begin { Print Info }
Repeat Writeln('MA TCHEO FILE --');
With Ptr Do
A

Begin
Write(O Volume, ':);
If 0 IsBikd Then
If-Leng(h(O_Title) > a Then
Write 0 Title);
Write~ If Want Patterns And (0 VPat <> Nil) Then

Begin

-

Writeln;
Writeln('
Volume patterns:');
Print Pattems(O VPat, 0_Volume, Volume);
End; If 0 IsB lkd Then
II-48

Users' Manual Suppiemen t, Version IV
New and Upgraded Standard Facilities

If Want Patterns And (0 FPat <> Nil) Then
Begin
Writeln('
File name patterns:');
Print Patterns(D FPat, 0_Title, Name);
End; End; { With Ptr" }
Writeln;
Write(Iype  for rest of list');
Read'in; Writeln;
Ptr : = Ptr".D NextEntry;
Until Ptr = NilEnd; { Print_Info }
Procedure Change(Ptr : O_ListP; Name: String);
Var
I, Posl, Lenl, Pos2, Len2, Last_Pas,
Mid_Pas, Las~Equal : Integer;
Patl, Pat2, Title, New : String;
Procedure Find_Equal(D_Title, Name : String;
Var PatPtr : 0 PatRecP;
Var Pat : String;
Var Pas, Len : Integer);
Begin { Find Equal}
While (Name(PatPtr". WildPos] <> ' =') And
(PatPtr" .Next <> Nil) Do
PatPtr : = PatPtr" .Next;
With PatPtr" Do
Begin
If CompLen = 0 Then Pat :=
Else Pat := ~(D_Title, CompPos, CompLen);
Pas := CompPos;
Len : = CompLen;
End;
End; { Find_Equal }
Begin { Change }
With Ptr" Do
Begin
Find Equal(D Title, Name, 0 _FPat, Patl, Posl, Lenl);
If O-FPat <> Nil Then
Begin
o FPat : = 0 FPat" .Next;
Find Equal(D Title, Name, 0 _FPat, Pat2, Pos2, Len2);
New-:= D_Tltle;
11-49

Users' Manual Supplement, Version IV
New and Upgraded Standard F acUities

Last Pos := Pos2 + Len2;
Mid Pas ::: Posl + Len2;
Last Equal ::: Last Pas - Len1;
For 1 ::: Posl To Mid Pas - 1 Do { 1st '::' }
New[I] := PatZ[I - Posl + 1];
F or I := Mid Pas To Last Equal - 1 Do
New[I] := is Title(I - Len2 + Lenl];
For 1:= Last Equal To Last Pos - 1 Do { 2nd '='}
New(I] := P-atl[I - Last Equal + I);
NeW:; Cancat(D Volume,-':', New);
Title ::: Concat(DVolume, ':', 0 Title);
Result: = 0 ChangeName(Title, New, True);
Write(Title, 7 __ ) " New);
-- -Case Result Of - o Name Error : Write(' Error in file name');
O-Off Line : Wri~ Volume off line');
O-Not-Found : Write(' File not found');
O-Other : Writer---Miscellaneous error');
End;{cases} - Writeln;
End; { if 0 FPat }
End; { with}
End; { Change }

Function Display(S, Match, Volume, Name : String;
Select: D_Choice) : D_ListP;
Var

Ch : Char;
Ptr : DDstp;
Want Patterns : Boolean;
ResuIi : D_Result;

Begin { Display }
Writeln; Writeln(S);
Write('
Display pattern matching information ? ');
Read(Ch); Writeln;
Want Patterns : = Ch In ['y', 'Y'];
Resun. : = D DirList(Match, Select, Ptr, True);
If Ptr <> Nil Then
Print Info(Ptr, Want Patterns, Volume, Name)

Else Case Result Of

-

o Name Error : Writeln('

Error in file name');
O-Off LIne : Writeln('
Volume off line);
D-Not-Found : Writeln('
File not found');
D-Other : Writeln('
Miscellaneous error');

II-50

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

End; {cases}
Oisflay : = Ptr;
End; Display}
Begin { WildChange }
Writeln;
Repeat

Mark(Heap Ptr);

"Sei'9ct : = "0;

Write('File title to match (must contain two "= "): J;
"Readin(Match);
Result : = 0 ScanTitle(Match, Volume, Name, Typ, Segs);
Writeln('Types [ yIn] : ');
GiveChoice('Directories', [0 Vo!]);
GiveChoice('Text Files " [0 Text]);
GiveChoice('Code Files " [0 Code]);
GiveChoice('Oata Files " [O-Oata]);
GiveChoice('SVol Files " [OSVol]);
Ptr : = Oisplay('Old Files :';- Match, Volume, Name, Select);
If Ptr <> Nil Then
Begin
Repeat

Change(Ptr, Name);
Ptr := PtrA.O NextEntry;
Until Ptr = Nil;
Write('Redisplay files? ');
Read(Ch); Writeln;
If Ch In ['y', 'Y1 Then
Ptr : = Oisplay(~ew Files :', Match,
Volume, Name, Select);

End;
Writeln;
Repeat

Write('Continue ? ');
Read(Ch); Writeln;
Until Ch In ['n', ~','y", 'Y1;
Writeln;
Release(Heap Ptr);
Until Ch In ['n', ~1;
End. { WildChng }

II-51

Users' Manual Supplement, Version TV
New and Upgraded Standard Facilities

Function O_Change_Date (0 NAME

: String;

-0 NEWDATE : 0 DateRec;
O:SELECT : D_Choice) : D_Result;

o

Change Date changes the file date of volumes and files whose names match the
fiTe name- argument contained in 0 NAME. 0 Change Date accepts wild cards in its
file name argument. If a volume date is changed, only the disk is updated. The
disk must be re-booted if the new date is to be used. In order to change the
internal date (which will appear when D(ate is used in the filer) use the date
access procedures within the SYS.INFO unit.

Parameters and Function Results:
0_Change_Date accepts the following parameters:

o NAME--A string which contains a valid file name.
contain wild cards.

The file name may

o NEWDATE--A record of type 0 OateRec which contains the new date. A year
value of 100 is not accepted by O:Change_Date in a new date.
o SELECT --A set of file and/or volume types as described in section 2.2. All
sealar types exce·pt 0 Free and 0 Temp apply to 0 Change Date. Disk free
spaces identified by the 0 Free scalar do not contain file dates. Temporary
status for files is specified by a special value in the file date field. Thus,
oJree and 0_Temp are ig"'lored if they are included in 0_SELECT.
o Change Date retums a value of type 0 Result. D Change Date can retum all
scalar values defined in 0 Result except ~Exists; the values have the following
meanings:
o Okay--No error. D NAME was found, and 0 NEWOATE was written to the
directory for the specified file or disk volume. -

II-52

o Not Found-No such file/volume found.
change- made.

No match found for 0 NAME. No

0_Name_Error-Illegal syntax in 0 NAME.

No change made.

/
1\

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o Off Line-Volume/unit off-line.

Volume/unit specified by 0 NAME was not
on-line. No change made. This error occurs only if the volume 10 in
o NAME specifies a single volume which is off-line. If the volume name in
O-NAME contains wild cards and does not match anyon-line volumes,
O:Change_Oate retums O_N~t_Found.

o Other--Unknown error. No change made. 0 Change Date encountered an
unidentified error which. prevented successful corrPietion Of the operation.
Programming Example:
The following program demonstrates the use of 0_Change_Date.

Program Date Test;
Uses
(*$UW1LO.CODE*)
wild,
(*$UOIR.INFO.CODE* )
Dirlnfo;
Var
Result
Ch

: 0 Result;
: Char;
M, 0, Y : lri'te"Qer;
NewDate : 0 OateRec;
Select
: 0 Choice;
FileName : String;

Procedure GiveChoice(Choice String; Kind 0_Choice);
Var
Ch : Char;
Begin - Write('
, ,Choice,' ? ');
Read(Ch); Writeln;
If Ch In ['y', 'V'] Then Select : = Select + Kind;
End; { GiveChoice }
Begin {. Date Test }
Select := 0;
Writeln('D ChangeDate Test --');
Repeat Writeln;
Write(1="ile to change : '); Readln(FileName);
Wiitiln(1 ypes [ yIn ] : ');
GiveChoice("Directories', [0 Vol];
GiveChoice("Text Files 't [O:TextD;
II-53

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

GiveChoice('Code Files " [0 Code]);
GiveChoice('Oata Files " [O-Oata]);
GiveChoice('SVol Files " [OSVol]);
Writeln('New date : );
WriteC'Month [1 - 12] : '); Readln(M);
Write('Oay
[1 - 31] : ); Readln(O);
Write('Year [0 - 99] : ); Readln(Y);
With NewDate Do
Begin
Month := M;
Day := 0;
Year := Y;
End; { With NewDate }
Writeln;
Result : = 0 ChangeOate(FileName, NewOate, Select);
Case Result-Of
D Okay : Writeln('date changed');
O-Name Error : Writeln('error in file name');
O-Off Line : Writeln('volume off line');
O-NotFound : Writeln('file not found');
O-Other : Writeln('miscellaneous error);
End; { cases }
Writeln;
Write('Continue ? ');
Read(Ch); Writeln;
Until Ch In ['n', 'N1;
End. { Date_Test}

Function 0 Rem Files (0 NAME
: String;
0 SELECT
: D_Choice) : D_Result;
The 0 Rem Files function removes file objects whose names match the file name
argum-ent contained in 0 NAME and types match the elements included in
D SELECT. The file name argument may contain wild:!ards. Disk files are
permanently deleted from their directaies. Volumes are taken off-line, but not
altered in any way; off-line disk volumes may be brought back on-line merely by
referencing them, while off-line serial volumes remain inaa::essible until the
system is reinitialized.
Parameters and Function Result:
O_RemJiles accepts the following parameters.

o NAME--A string containing the name of the file(s) or volume(s) to be
removed.
II-54

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

o SELECT --A set of file objects to be removed. Removal of file objects is
subject to the criteria described in section 4.2.0.2. The definition of the set is
as follows:
DYJameType = CD_Vol, D_Code, D_Text, D_Data, O_SVol, D_Temp, DJree);
D Choice

= Set

Of D_NameType;

All scalar types except D_Free apply to D_Rem.files. Disk free space cannot be
removed from the directory; thus, DJree is ignored if it is included in D SELECT.

o Rem Files retums a value of type D Result. D Rem Files can retum all scalar
vilues-defined in D_Result except L>_Exists;-the -values have the following
meanings:
D Okay--No error. 0 NAME was found. If 0 Vol is included in 0 SELECT,
and a volume matches the file name argument in 0 NAME, the volume is
taken off-line. If 0 Text, 0 Code, 0 Data, 0 SVol, or-O Temp are included
in 0 SEL ECT, disk -files of those types which match 5 NAME are deleted
from -their directories.

o Not Found--No such file/volume found.
change- made.

No match found for 0 NAME. No

D_Name_Error--Illegal file name syntax in 0 NAME.

No change made.

0_Off_Line--Volume/unit off-line. The volume/unit specified by 0 NAME was
not on-line. No change made. This error occurs only if the vOlume id in
o NAME specifies a single volume which is off-line. If the volume id in
D-NAME contains wildcards, but does not match anyon-line volume,
O~emJiles returns D_NotJound.

D Other--Unknown error. No change made. D rem Files encountered an
urudentified error which prevented successful completion of the operation.
Programming Example:

Program Rem Test;
Uses
(*$ UWIL O.CODE*)
wild,
(*$UDIR.INFO.COO::* )
Dirinfo;

II-55

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Var

Result : 0 Result;
Select : 0 -Choice;
Ch : Char;
Remfile : String;
Procedure GiveChoice(Choice
Var

String; Kind

D_Choice);

Ch : Char;

Begin
Write('
',Choice,' ? ');
Read(Ch); Writeln;
If Ch In ['y', 'Y1 Then Select : = Select + Kind;
End; { GiveChoice }

Begin { Rem Test}

Select := "0;
Writeln('O RemFiles Test --');

Repeat

-

Wri te('F ile(s) to remove : ');
"Readin(Remfile);
Writeln(lypes [ y /n ] : ');
GiveChoice('Directories', [0 Vol];
GiveChoice(lemp Files " [5 Temp]);
GiveChoice(iext Files " [0 Text]);
GiveChoice('Code Files " [0 Code];
GiveChoice('Oata Files " (O-Oata]);
GiveChoice('SVol Files " [OSVol]);
Result : = 0 RemFiles(Remflle, Select);
Case Result-Of
o Okay : Writeln('files removed');
O-Name Error : Writeln('error in file name');
O-Off LIne : Writeln('volume off line');
O-NotFound : Writeln('file not found');
O-Other : Writeln('miscellaneous error');
End;- { cases }
Writeln;
Write('Continue ? ');
Read(Ch); Writeln;
Until Ch In ['n', 'N1;
End. { Rem_Test}

II-56

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Procedure D_Lock;

o Lock grants exclusive directory access rights to the task that executes it;
however, a task may have to wait until another task releases the directory lock
before it can continue execution past its call to 0_Lock.
NOTE: 0 Lock calls should always be matched with 0_Release calls to prevent
syste m deadlocks.
The Dir Info routines 0 Lock and 0 Release are provided for use in multi-tasking
environments.
When used properly, they ensure mutually exclusive access to
directory information.

Procedure 0 _Release;

o

Release releases exclusive access rights to the directory. Tasks already waiting
for directory access are automatically awakened when the directory becomes
available by a call to 0_Release.
Programming Example:
The following program demonstrates the use of 0 Lock and 0 Release.

Program Locktest;
Uses
(*$UWILD.CODE*)
wild,
(*$UDIR.INFO.CODE* )
DirInfo;

Const
Stack 5 ize

= 2000;

Var
Pid : Processid;
Old,
New : String;
Date : 0 DateRec;
M, 0, V -: Integer;
Ch : Char;

Process Change And Check(Old, New: String; Date
Var
Result: D_Result;

D_DateRec);

II-57

Users' Manual Supplement, Ver~ion IV
New and Upgraded Standard Facilities

Begin { Change And Check}
o Lock;
1 beginning of critical section }
Result := 0 ChangeOate(Old, Date, [0 Vol •• O SVol]);
I f Result =-0 Okay Then
-Result : = cr ChangeName(Old, New, True);
o Release; - { end of critical section)
End; { Change_ And_Check }
Begin { LockTest }
Repeat
Write('Old file name: ',');
R:eadin(Old);
Write('New file name: ');
R:eadin(New);
Writeln('New date:);
Write('
Month: ');
R:eadin(M);
Write('
Day: ');
R:eadin(O);
Write('
Year: ');
"Re8din(Y);
With Date Do
Begin
Month := M;
Day := 0;
Year := Y;
End;
Start(Change And Check(Old, New, Date), Pid,
Write('Start another? );
Read(Ch); Writeln;
Until Ch In ['n', 'N1;
End. {Locktest }
11.3.6.2

Stac~Size);

Wild Cards (WILD)

The unit WILD provides a wild card convention for pattern matching of string
variables. Wild cards are special character sequences in a character string; they
are named wild cards because of their ability to match whole classes" of character
sequences rather than a single character sequence. For instance, the string "a ="
matches all character strings starting with the letter "a" because n=" Is defined as
a wild card which matches any character sequence.

II-58

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Wild cards are useful in pattem matching situations where many character strings
are to be matched with a single request. The p-System Filer uses a set of wild
card facilities in its directory operations. Examples are given in the p-System
manual that describes the filer operation. Because of the extra functions provided
by this UNIT there is not a direct correspondence between the filer and this UNIT.
Where there are differences in the use of characters these are described.

D.'.6.2.1

Special Wild Card Characters

The following characters are defined as special characters:
question mark
equals sign
braces
comma
hyphen
tilde
percent sign

?

{ and}

%

Special characters may only be used as parts of wild cards; however, a literal
occurrence of a special character can be represented by a two character sequence
consisting of a percent sign followed by the special character. A percent sign
indicates that the following character is to appear literally in the character string;
for instance, "xx% =yy" is treated as the literal character string "xx =yy" rather
than a wild card string.
Examples of percent sign in wild cards:
"a bO/o?def"
"ab{ a-z, % =}deoA,%f"
"ab%-def"

matches
matches
matches

"ab?def"
flab =deDA, fIt
flab-def"

II-59

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

11.'.6.2.1.1

Question Mark Wild Card

A question mark matches any single character. In the filer the "'?" is treated as
an interactive query of an "=" wild card. This is one of the major differences in
use of characters between this UNIT and the filer.
Examples of ",?" wild card:
Pattem:

"ab?def"

Matches:

"abbdef"
"abrdef"

Nonmatch:

"abdef"
"abjkdef"
"abef"

11.'.6.2.1.2

Equals Sign Wild Card

An equals sign matches any sequence of characters, including the empty sequence.
This is the same as the filer except that more than one If=" can appear in a wild
card string.
Examples of

11 ..60

"="

wild card:

Pattem:

"ab = def = "

Matches:

"abcdefg"
"abdef"
"abcccdef"

Nonmatches:

"abcef"

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

11.3.6.2.1.3

Subrange Wild Card

The subrange wild card matches a single character from the character set specified
in the subrange. The following special characters are used to construct subrange
wild cards: comma, hyphen, tilde, and braces.
A subrange wild card consists of a character set delimited by braces.
set consists of a list of character-items separated by commas.

A character

A character-i tem is ei ther a character or a character range (two characters
separated by a hyphen). A character range implicitly specifies all characters lying
between the two characters. (Consult an ASCII table to determine the ordering of
characters.)
Character-items preceded by tildes are called negated-items and are specifically
excluded from the character set. A character range proceeded by a tilde is
entirely excluded from the character set. The list of character items is evaluated
left-to-right. Characters specified by non-negated items are included into the set;
characters specified by negated items are excluded from the set. Thus, a character
matches the subrange wild card if it matches one of the non-negated items, but
does not match any of the negated choices. For example, the subrange ',a-z,-r}"
represents the set of characters from "a" to "z", excluding "rlt.
NOTE: Blank characters within subrange wild cards are ignored. Wild Card
characters can be specified in character sets with the percent sign notation
described above.
Examples of subrange wild cards:
a,b,c}
a-d,j,w-z}
{a-z,-j,-x-y}
Syntax for subrange wild card:
wild-card
item-list
item
char-item
range
char

=

=

=
=
=
=

"" item-list ,~"
item < "," item)
[-] char-item
char / range
char "_" char
a printable ASCII character

Il-61

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Examples of subrange wild card:
Pattern:
Matches:

"abbdef"
"abrdef"

Nonmatches:

"abjdef"
"abkdef"
"abzdef"

11.3.6.2.2

Function 0 Wild Match (WILD, COMP: String; Var PPTR :
- 0 _PatRecP; PINFO
: Boolean) : Boolean;

D Wild Match serves as a general purpose pattern matcher for string variables
uSing the wild card conventions described above. The two main parameters are a
wild card string WILD and a literal string COMP. D Wild Match determines
whether the literal string matches the wild card string. If the strings match,
D Wild Match returns TRUE; otherwise, it returns FALSE. If PINFO is set to
T~UE, -D_Wild_Match returns information (accessed through PPTR) which describes
how the strings were matched.
D Wild Match Parameters and Function Result:
D Wild Match accepts the following parameters.
WILD--A string which may contain wild cards.
COMP--A literal text string.
PINFO--A Boolean. If set to TRUE, PINFO requests that pattem matching
information be returned.
PPTR--Pointer of type 0 PatRecP. Depending on the value passed in PINFO,
D Wild Match either sets-PPTR to NIL or points it at a linked list of records
containing pattern matching information.

11-62

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

ll.3.6.2.2.1

0_Wild_Match Pattern Matching Information

If PINFO is set to TRUE, 0 Wild Match retums pattern matching information in
PPTR. PPTR is a pointer (or type 0 PatRecP) to a linked list of records which
contain the starting positions and lengths of corresponding character pattems in
WILD and COMP.

o Pat RecP is defined as follows:
o PatRecP = AD_PatRec;
o PatRec = Record

CompPos,
CompLen,
WildPos,
WildLen:Integer;
Next:D PatRecP;
End; { -0_PatRec }

CompPos and WildPos are the starting positions of corresponding character patterns
in COMP and WILD, respectively. CompLen and WildLen are the pattern lengths.
Next points to the next pattern record in the list; it is set to NIL in the last
pattern record. The patterns occur in the list in the order in which they were
matched in the strings.
If the strings do not match, or the list was not requested (i.e. PINFO is set to
FALSE), PPTR is set to NIL.

11-63

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Example of pattern record list:
WILD contains:' =ab{a-m} =f?'
COMP contains:'abcdefg'
If PINFO is set to TRUE, pattern record list returned is-1. WildPos = 1, WildLen = 1
CompPos
1, CompLen = 0
(' =' matches the empty string)

=

2. WildPos = 2, WHdLen = 2
CompPos = 1, CompLen = 2
('ab' matches 'ab')
3. WildPos = 4, WHeLen = 5
CompPos = 3, CompLen = 1
(1a-m}' matches 'c')
4. WildPos = 9, WildLen = 1
CompPos = 4, CompLen = 2
(' =' matches 'de')

5. WUdPos = 10, WHeLen = 1
CompPos = 6, CompLen = 1
('f' matches 'f')

6. WildPos = 11, WildLen = 1
CompPos = 7, CompLen = 1
('?' matches 'g')
NOTE: When the "=" wild card in WILD matches an empty string in COMP,
CompLen is set to 0 and CompPos is set to the position of the next pattern in
COMP (i.e. the position where a nonempty pattern would have occurred). Be sure
to check the validity of CompPos indices before using them to reference
characters in COMP; otherwise, range errors may occur.

n-64

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Unit interface
unit wild;
interface
type
o PatRecP
D-PatRec

= AD PatRee;

= Record

CompPos,
CompLen,
WildPos,
WildLen:Integer;
Next:D PatRecP;
End; { 0 _~atRec }
function d_wild_match(wild,comp:string;
var pptr:d patrecp;
pinfo:boolean):boolean;
Sample Program:
The following program is an example of a string comparison routine which uses
o Wild Match. The program reads two str~~.,gs and prints the result of the
comparison; if requested, it also prints information describing how the pattems
matched.

Program WilcLTest;
Uses (*$UWILD.CODE*)
wild;

Var
W, C : String;
Ch : Char;
PatPtr : 0 PatRecP;
Want_Patterns : Boolean;

Procedure Print Pattems(PatPtr : 0 PatRecP;
-

C, Vi : 5 tring);

Var
Coun t : In teger;

Begin { Print Patterns}
Writeln('type  for pattems');
Readln; Wri teln;
Count := 1;
Repeat

II-65

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Writeln('Pattem " Count, ' :');
With PatPtr A Do
Begin
Writeln(' Comp:', C);
If CompLen <> a Then Write('''' ':(CompPos + 9));
If CompLen > 1 Then Write('A':(CompLen - 1));
Writeln;
-Writeln(' Wild:', W);
Write('''' ':(WildPos + 9));
If WildLen > 1 Then Write(''''':(WildLen - 1));
Writeln; Writeln;
-End;
PatPtr : = PatPtr"" .Next;
Count : = Count + 1;
Until PatPtr = Nil;
End; { Print_Pattems }

Begin { Wild Test}
Repeat Writeln{'--W ildCard Check-');
Write('Wild Card String
: ');
"R"eadin(W);
Write(,Comparison String :);
Readln(C);
Write('Do you want pattern matching information ? [yIn] ');
Read(Ch);
Want Patterns : = Ch In ['y', 'Y1;
WriteIn; Writeln;
If 0 Wild Match(W, C, PatPtr, Want Patterns) Then
Writeln1'A Match,)
E lae .Writeln('No Match');
If Want Patterns And (PatPtr <> Nil) Then
Print-Pattems{PatPtr, C, W);
Write('Continue ? [yIn] ');
Read(Ch);
"Wr'ffeln; Writeln;
Until Ch In ['n', 'N1;
End. { Wild_Test }

11-66

Users' Manual Supplement, Version rJ
New and Upgraded Standard Facilities

11.3.6.3

System Information (SYS.INFO)

Unit SYS.INFO provides an easy way to access some of the ~ystem global
information. SYS.INFO uses KERNEL.CODE in its implementation section.
Although it is possible to access KERNEL.CODE directly, there are many variables
that are normally not needed. If a user requires a different set, then another unit
similar to this one can be easily constructed for the particular situation.
In order to distinguish the variables defined by this unit, they have been prefixed
with 51.
This supplement has a description of each of the functions or procedures. The
uni t interface is then given, and finally an there is an example program showing
the various components of the unit in use.
Work Code File Name:
Procedure SI_Code_Vid (Var 51_Vol: String);
Procedure SI_Code_Tid (Var SI_Title : String);
The preceding procedures return the volume name (51_Vol) and the file name
(SI_Title) of the system work code file.
Work Text File Name:
Procedure 51_Text_Vid (Var 51_Vol : String);
Procedure SI_Text_Tid (Var 51_Title : String);
The preceding procedures return the volume name (51_Vol) and the file name
(51_Title) of the system work text file.
System Lklit:
Function SI_Sys_Unit : Integer;
The 51 Sys Unit function retums an integer function result.
the unit containing the system volume is retumed.

The unit number of

Procedure SI_Get_Sys_Vol (Var SI_Vol : String);
The preceding procedure retums the volume name (51_Vol) of the current system
volume.

II-67

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Prefixed Volume Name:
Procedure 51_Getyref_Vol (Var

S~Vol

: String);

Procedure SI_5et_Pref_Vol (51_Vol: String);
The preceding procedures allow the current prefix volume to be read and set.
System Date:
Procedure 51 Get Date (Var 51_Date : SI_Date_ Rec);
Procedure

S~Set_Date

(Var 51_Date : 51_Date_Rec);

The 51 Get Date and 51 Set Date procedures access and modify the system date.
The date is passed as a-record of type 51 Date Rec. Changing the date will not
change the date on the system disk. It win only change the date internally in the
operating system. To change the date on the disk, use function 0 Change Date
within the DIR.INFO unit.
51 Date Rec

= Packed

Record
Month : 0•• 12;
Day : 0 •• 31;
Year: 0 •• 99;

End;
This record is used in the operating system to store dates. It is a packed record
and only requires 16 bits. All date variables use this format.

II-68

!

\

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Unit interface:
Unit Sys Info;
Interface Type
51 Date Rae = Packed Record
Month : 0•• 12;
Day: 0 •• 31;
Year : 0•• 99;
End;

-

Procedure
Procedure
Procedure
Procedure
Function
Procedure
Procedure
Procedure
Procedure
Procedure

51 Code Vid (Var SI Vol : String);
SrCodelid (Var SrTitle : String);
51-Text \lid (Var SI\101 : String);
SI-Text-Tid (Var 51-Title : String);
51-Sys U,it : Integer,
51-Get5ys Vol (Var 51 Vol: String);
51-Ge"t-Pref Vol (Var Si Vol: String);
51-Set -Pref \I 01 (SI Vol -: String);
51-Get Date (Var 51 Date: 51 Date Rec);
SI::5et:Date (Var SI..'bate : SI])ate~ec);
.

,

~

"

Example Program:
Program 'Sys_Test;
Uses {$USys.lnfo.Code} Sys_Info;

Var
Ch : Char;
Date : 51 Date Rec;
Vol,
Title : String;
Begin
51 Code Vid(Vol);
51-Code-Tid (Title);
If-Length (Title) <> 0 Then
Writeln ('The Work Codefile is " Vol, ':', Title)

Else
Writeln ('There is no Work Codefile. ');
51 Text Vid (Vol);
SI-Text-Tid (Title);
If-Length (Title) <> 0 Then
Writeln ('The Work Textfile is " Vol, ':', Title)

Else
n-69

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Writeln ('There is no Work Textfile.');
Writeln;
51 Get 5ys Vol (Va!);
Writeln ('The System was booted on volume " Vol,
': on unit " 51 5ys Unit);
51 Get Pref Vol (Vol);
-Writeln;
Writeln ('The Prefix volume is " Vol, ':');
Write ('New Prefix: ');
Read'in (Va!);
Delete (Vol, Pas (':', Va!), 1);
If Length (Vomn [1..7] Then
Begin
51 Set Pref Vol (Va!);
SI-GetPrefVoi (Vol);
Writeln ('The Prefix volume is " Vol, ':');
End {Of If}
Else
Writeln ('No change made');
Writeln;
SI Get Date (Date);
Writel" ('The current date is "
Date.Month, -Date.Day, -Date. Year);
Repeat
Write ('Set for tomorrow"s date ? );
Read (Ch);
Until Ch In ['y', 'Y', 'n', 'N1;
Writeln;
If Ch In ['y', 'V'] Then
Begin
Date.Day : = Date.Day + 1;
If (Date.Month In [1, 3, 5, 7, 8, la, 12]) And (Date.Day = 32) Or
(Date. Month In [4, 6, 9, 11]) And (Date.Day = 31) Or
(Date.Month = 2) And (Date.Day = 29) Then
Begin
Date.Day : = 1;
If Date.Month = 12 Then
Begin
Date.Year := Date.Year + 1;
Date.Month : = 1;
End {Of If =12}
Else
Date.Month : = 1;
II-70

Users' Manual 5upplemen t, Version IV
New and Upgraded Standard Facilities

End {of If Date.Month};
51 5et Date (Date);
51-Get Date (Date);
Writel;; ('The new date is "
Date.Month, -Date. Day, -Date. Year);
End {of If Ch}
Else
Writeln (1'Jo change made');
End {of 5ys_Test}.

IL1.6.4

File Information

(F1LE.INFO)

This unit provides an easy way to access information in the file information block
(fib). It uses the system globals from KERNEL.CODE. Although it is possible for
a user to access this global data, it is easier to use this unit. In order to
distinguish the variable names in this unit they have all been prefixed with an F.
The types, functions and procedures defined by the unit are first described. The
. interface section is then given. Finally, there is an example program showing the
various procedures and functions.

B ec ause of a Pascal lang'uage restriction, it is necessary to declare files of type

(f_file_type) that are to passed on as parameters to these procedures.

Function F_Open (ver fId:

F_Flle_T ype):boole an;

This function should be called before any of the following are used. This enables
a check to be made on the status of a file. The function returns true if the file
is open and false if is not open. The following functions will not give the correct
values if the file is not open.

Function F _Length (Var Fid : F'_F'ile_Type) : Integer;
Returns the length (in blocks) of the file a,ttached to the Fid identifier. If the
file is not opened, the result is retumed as zero. This only has meaning for files
on blocked devices as the value retumed is the number of blocks allocated to the
file.

Function F_Unit_"umber (Var F'ld : F_File_Type) : int'egar;
Returns the unit containing the fUe attached to the Fid
fUe opened to the Fid, the function result is Zero ..

identifier.

If there is no

II-71

P

Users Manual Supplement, Version IV
New and Upgraded Standard Facilities

Procedure F Volume (Var Fid : F File Type;
Var File Volume : String);
Returns the name of the volume containing the file attached to the Fid identifier.
If the external file lacks a defined volume name, F Volume retums a volume 10
construe ted from a unit number (eg. 113:). If there is no file opened to the Fid,
the file_volume is set to a null string.

Procedure F File Title (Var Fid : F File Type;
Var File_Title : String);
Returns the title (with suffix) of the file attached to the Fid identifier. If there
is no file opened to Fid, or if the external file is a volume, then the File title
is set to a null string.

Function F_Start (Var Fid : F_File_Type) : integer;
Returns the block number of the first block of the file attached to the Fid
identifier. This only has meaning for files on block devices. If there is no file
opened to Fid, the function result is retumed is zero.

Returns a boolean that is TRUE if the file attached to the Fid identifier is
located on a block-structured unit. If there is no file opened for the Fid or if the
device is not block structured , the function result is set to false.

Procedure F Date (Var Fid : F File Type;
Var FITe_Date : F_Date_Ree);
Returns a record indicating the last access date for the file attached to the Fid
iden ti fier. If there is no file opened to Fid, the File Date is unchanged. The
definition of F_Date_ Rec type is
F Date Rec

= Packed Record

Month : 0 •• 12;
Day
: 0 •• 31;
Year : 0•• 100;
End;

II-72

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Unit interface
Unit FileInfo;
Interface
Type F File Type = file;
F Date-Rec - = Packed Record
Month : 0•• 12;
Day
: 0 •• 31;
Year : 0 •• 100;
End;
Function F Open (var fid: F File Type):boolean;
Function FL.ength (Var Fid
Flle Type) : Integer;
Function F-Unit number (Var Fid : FJile_Type) : integer;
Procedure F VoiUme (Var Fid : F File Type;
Var File Volume : -String);
Procedure F File Title (Var Fid : F File Type;
Var File Title -: String);
Function F Start (Var Fid : -F File Type) : integer;
Function F-is Blocked (Var Fid-: F FHe Type) : Boolean;
Procedure F' Date (Var Fid : F File Type;
Var File_Date -: F_Date_Rec);

:r:-

Example Program:

Program File_Demo;
Uses
(*$UFILE.INFO.CODE *)
File_Info;
Var Fid : File;
Name,
Title,
Volume : String;
Start,
Blocks,
Unit_Num : Integer;
Is Blocked : Boolean;
Date : F_Date_Rae;

Begin {of File Demo}

Write (rile -~Name ? ');
Readin (Name):
If Lenoth (Name) == 0 Then
rTxi~"(File_D~mo);
11-73

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

A fter a space is typed, the message line will be erased and the cursor will be
returned to its previous position when that is possible. If a program uses
UNITREADs or UNITWRITEs to the console, the previous cursor position may be
lost. Use of GOTOXY, (but not SC GOTOXY) may also cause loss of the previous
cursor posi tion. This is because- the p-System is not informed of the cursor
position after these kinds of low level I/O operations.

11.4.2

User Control of Error Messages

A program
also change
disk that is
file is on a

may change the line on which an error message is displayed. It may
the actual message displayed when a code segment is required from a
not present in the appropriate drive for blocked devices. If the code
subsidiary volume, set the message for the principal volume.

T he new ERRORHANDLING uni t
prov ides these facili ties.
The file
ERRORHAND.CODE on the utilities disk contains this unit. In order to use
ERRORHANDLING a Pascal program should have a declaration similar to the
following example.
{$U errorhand.code} errorhandling;
Also, ERRORHANDLING must be available at runtime, either in a library or
libraried into the using program's code file. For more information on units and
libraries, see The UCSD Pascal Handbook and the Users Manual, Version IV .0.
The following procedures are available within this unit:
PROCEDURE SET ERROR LINE (LINE:INTEGER)
PROCEDURE SET:=USER_MESSAGE (DRIVE:INTEGER; MESG:STRING);
A program may change the line on which p-System run-time error messages are to
be displayed by calling SET ERROR LINE with the desired line number as a
parameter LINE. After the call to SEt:"ERROR_LINE, any run-time error messages
will be displayed on that line until SET ERROR_LINE is used again to specify
another line.
The standard message for needed code segments on disks that are not present may
be changed by calling SET USER MESSAGE with parameter DRIVE set to the
physical device number and parameter MESG set to the desired message string.
WARNING: A user message will be destroyed if a MARK is called before a
SET_USER_MESSAGE.
NOTE: The physical device numbers are 4, 5, and 9 through the maximum number
for physical disk as configured in SETUP.

II-76

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

D.4

Error Messages

Execution error messages are displayed by the p-System under certain
circumstances. If a code segment is needed and the disk containing it is not in
the appropriate drive, the user is prompted to replace the disk and type  to
continue. If a program attempts to divide by zero, or access outside the bounds
of a Pascal array, a message indicates this and the user is prompted to type
, at which point the p-System is re-initialized. These and other execution
errors are listed in the Users Manual, Version IV .0.
It is now possible for a program to alter the message that is displayed when
certain errors occur. This should be useful for applications developers, especially
those whose customers speak languages other than English.
Also, the display format of p-System error messages has been changed in a way
that should assist applications developers.

D.4.1

Format of Error Messages

Formerly, error messages were displayed on three lines beginning at the current
cursor position. They are now displayed on one specified aD-column line. For
example, when a code segment is needed from a disk that is not present in the
appropriate drive, the following prompt is displayed.
Need segment SEGNAME:

Put volume VOLNAME in unit U then type 

This indicates that the segment SEGNAME was not found on volume VOLNAME in
device U. By placing the correct volume in the correct unit and typing space,
execution should continue normally.
The following example shows the error message that occurs when a user presses
the p-System BREAK key.
Program Interrupted by user--Seg PASCALIO PII 17 011 310  continues
A fter a space is typed, the p-System will be re-initialized ..
System error messages such as these will always appear at a fixed position on the
screen. The default posi tion is the bottom lin eo (Any line can be specified,
however.) A BEL character (audible beep) will be written to the console device
when the message is written out.

II-75

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

(*$1-*)
Reset (Fid, Name);
wrrteln(1oresult ',ioresult:6);
if f open(fid) then
Begin
F Volume (Fid, Volume);
Is-Blocked := F Is Blocked (Fid);
unit num : = F Dnltnumber (FId );
F File Title (Fid, Title);
F-Oate (Fid, Date);
BTocks : = F Length (Fid);
Start : = F Start (F id);
"'WrIteln; Write (Volume, ': (Unit " Unit Num);
If Is Blocked Then
Begin
Writeln (' blocked)');
Writeln (Title, Blocks:7,
Date.Month:4, -Date.Day, -Date. Year, Start:6);
End {of If Is Blocked}
--

Else

-

Writeln (' seria!)');
End {of If F Volume}

Else

-

Writeln ('No such file');
End {of File_Demo}.

11-74

Users' Manual Supplement, Version IV
New and Upgraded Facilities

Then, if a code segment is required from a mlsslng disk in the unit for which the
user program has designated a special error message, that message will be
displayed. The p-System will then wait for the user to enter a  whether
or not the message actually indicates that a  is needed. The message line
will subsequently be erased, the cursor will be returned to its former position if
possible, and execution will continue.
For other kinds of execution errors, a standard p-System message will be displayed
on the message line. A fatal error will always cause the p-System to fail. For
non-fatal errors, the p-System will wait for the user to enter a . The
message line will then be erased, the cursor will return to its former position, and
execution will continue (most likely the p-System will re-initialize itself).
To proceed from a non-fatal error, press .
WARNING: Escaping from a non-fatal error is a dangerous practice since system
data may be corrupted.
Error message values set by the user will remain in effect throughout the
execution of the program, but will be reset at program termination or whenever pSystem re-initialization occurs.
The user program may reset the error handling values to their default values at
any time if special output is no longer desired. The missing code segment
message can be reset by passing a null string to SET_USER_MESSAGE.
Unknown results may 'occur on console devices whose screen width is narrower than
the message to be displayed.

II-77

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

u.s

Pascal Compiler Enhancements

This section describes the· new enhancements to the Pascal Compiler and contains
examples of their use.
The first section describes an enhancement of the Pascal USES construct. It is now
possible to select, from within the client compilation unit, the constants, types,
variables, and routines that are needed from the unit. Compile-time symbol table
space will not be allocated for the rest of the unit's interface section. If the unit
has a Large interface section, and the host requires only a small portion of it, a
selective USES statement can eliminate the unnecessary symbols and increase the
available memory space, thereby increasing the size of a program or" unit that can
be co mpiled.
The last section describes enhancements to compiled listings, an additional compiler
promptline, and the significance of compiler version numbers in terms of the size
of real numbers.
ILS.l

Selective Uses

This enhancement allows users to select certain items from a unit's interface
section. The following diagram explains the syntax.

mIt
Identifier

'----' t
Icfent

IE------.-l:)

II-78

,(j) -po--o&-¥

I--..-......

Users' Manual Supplement, Version IV
New and Upgraded Facilities

Where ident can be a constant, type, variable, or procedure/process/function,
any constant or type used in a selected declaration must be included in the
selective USES list. If a selected declaration is not present in the interface
text, an error will result during compilation. Most identifiers must be named
explicitly in the identifier list if they are to be made available by the USES
statement. Some identifiers are available implicitly:

*

When an enumerated constant type is explicitly listed, all the
constant identifiers of the enumeration are implicitly available.

*

When a record type is explici tly listed, all its field names are
implicitly available (for example, see the following listing under unit
A, line 12, info_rec.)

F in all y, list only the name of a routine to make it available.
listing of parameters is needed.

No explicit

NOTE: The types and constants that these parameters use must be explicitly
included.
The first of the following compiled listings is unit A, which is selectively
used by units Band C, shown in the second and third compiled listing.
'

---------------------------------------------------------Pascal Compiler IV.l c5s-0

3/24/82

Page 1

=======~============================================== ====

2
3
4
5
6
7
8
9

2
2
2
2
2
2
2
2
2

l:d
l:d
l:d
l:d
l:d
l:d
l:d
l:d
l:d

1
1
1
1
1
1
1
1
1

10

2

l:d

1

11
12

2
2

l:d
l:d

1
1

1

un itA;
interface
const
maxnum=1000;
maxchar=7;
type
byte=0 •• 255;
codeblock=packed array
[0 •• maxn um] of byte;
alpha=packed array
[0 •• maxchar] of char;
ptr_ in fo rec= info rec·,
info rec;record
A

-

II-79

Users' Manual Supplement, Version IV
New and Upgraded Facilities

13
14
15
16
17
18
19
20
21

2
2
2
2
2
2
2
2
2

l:d
l:d
l:d
l:d
l:d
l:d
l:d
l:d
l:d

1
1
1
1
1
1
1
3
3

22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

2
2
2
2
2
2
2
2
2
2
2
2
2

l:d
l:d
l:d
1:d
2:0
2:1
2:2
2:3
2:3
2:4
2:3
2:4
2:2
1:0
1:0

1
1
1
1
0
0
3
3
12
22
22
27
30

2

2
2

:0

0
0
0

code:codeblock;
Ilink,rlink:ptr info rec;
end·,
-next=char;
var
first,last:byte;
function update(var info:ptr_ info rec)
: nex t;
implementation
function update;
begin
wi th info" do
begin
II ink:=rl ink;
i f rlink=llink then
update:='y'
else
update:='n';
end;
end;
end. {unit A}

End of Compilation.

----------------------------------------------------------

------------------~----------------------------------- ----

Pascal Compiler IV.l c5s-0

3/24/82

Page 2
I

---------~-------------------------------------------- -----------~------------------------------------------------

1
2
3
4

2
2
2

l:d
l:d
l:d
1:d

1
1
1
1

5

2

l:d

1

6

2

l:d

1

7

2

l:d

1

II-80

2

unit B;
interface
{$U a.code}
uses a( {canst} maxchar,
{include for type ALPHA}
{types} alpha,
{include for variable WHICH}
byte,
{include for FIRST and LAST}
{vars } first,
{include for proc CHANGE}

Users' Manual Supplement, Version IV
New and Upgraded Facilities

8

2

1:d

1

9

2

12
15
17

2

1:u
1:u
1:u
l:u

1
1
1
1

l:u
l:d
l:d
l:d
l:d
1:d
l:d
l:d

1
3
1
1
1
1

last
include for proc CHANGE}
Us i ng A

2

2

26

2

30

2

31

2
2
2
2
2

32
33
34
35
36
37
38
39

40
41
42

43

44
45
46
47
48
49
50

2
2
2
2
2

2

2:0
2:1

2:2
2:1
2:2

o
4

14
14
26

o
o
o

2
2
2
2
2

1:0
1:0

2

o
a
o
o
o
o
o

to

:0
:0

51

2
2

1:0
1:0
1:0
1:0
1:0

52

2

1:0

a

53

2

1:0

o

54

2

1:0

o

55

2

1:0

a

56

2

1:0

o

57

2

1:0

o

58

2

1:0

o

2
2

maxchar=7;
byte=0 •• 255;
alpha=packed array
[O •• maxchar] of char;
first,last:byte;
);

procedure change(which:alpha);
implementation
procedure change;
begin
if which='
last:=first
else
first:=last;
end;

, then

end; {unit B}
unit C;
interface
implementation
{$U a.code}
uses a( {canst} maxnun,
{include for type OODEBLOCK}
maxchar,
{include for type ALAHA}
byte,
tinclude for type OODEBLOCK}
{type} alpha,
{include for variable MINE}
info rec,
{include for PTR INFO REC}
ptr info rec,
{include for tunc-UPDATE}
codeblock,
{include for INFO REC}
next,
II-81

Users' Manual Supplement, Version IV
New and Upgraded Facilities

{include for func UPDATE}
Us i ng A
59
61
62
65
66

2
2
2
2
2

1:0
l:u
l:u
l:u
l:u

0
1

67

2

l:u

1

68
69
70
71
72

2
2
2
2
2

l:u
l:u
l:u
l:u
l:u

1
1
1
1
1

1

1
1

maxntm=lOOO;
maxchar=7;
byte=0 •• 255;
codeblock=packed array
[0 •• maxntm] of byte;
alpha=packed array
[0 •• maxchar] of char;
ptr info rec=Ainfo rec·,
i nfa rec;record
code:codeblock;
llink,rlink:ptr_info_rec;
end;

-

==========================================================
a.code

Pascal Compiler IV.1 c5s-0

3/24/82

Page 3

===================~================================== ====

73
78

2
2

1:u
l:u

1
1

79
80

2
2

1:u
1:d

3
3

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2

1:d
l:d
l:d
l:d
l:d
l:d
1:0
1:1
1:1
1:1
1:1
1:1
1:2
1:1
1:2
:0

End of Camp i 1 at i on.
II-82

next=charj
function update
(var info:ptr_info_rec):next;
{func}

update),

Us i ng B
b·,
var
info:ptr info - rec·,
mi ne: alpha;
0
0
0
7
16
22
30
39
59
61
0

begin
new( in f 0) ;
new(infoA.rlink);
infoA.llink:=nil;
mi ne: =' newsys tm' ;
i f update(info)='y' then
wr i tel n ( , in f a updated' )
else
change (mi ne) ;
end.

Users' Manual supplement, Version IV
New and Upgraded Facilities

The selective USES list feature will save space in memory during compilation time,
and it is good documentation. That is, it identifies all the data declarations that
are used for each unit. See chapter In for more information.
All programs that use a special modified version of the system KERNEL or any
other uni t that has been tailored in-Ii ne for a certain program should take
advantage of selective USES •

.ll.5.2

Enhancements to the Compiled Listing

The following items describe enhancements to the compiled listing.
1. The following prompt allows the user to name a listing file.
Output file for compiled listing? «ret> for none)
An 'L f compiler directives can override the file specified. If the user
ommits .text from the file name, the compiler will append .text to the
end of the file name. To exit the compiler, press .
2. The system date is now in the heading of a compiled listing.

3. The additional line 'USING ' will make interface sections from
a USED unit easily identifiable on a listing. Also, a 'u' in the line
heading (previously a 'd') signifies that the following line is an interface
text, not text in the compiled program.
4. Only the declarations chosen from a unit will be present in a compiled
listing. If one variable is chosen from a list of variables, the entire list
will be present in the compiled listing. For example, if an 'x' is chosen
out of the following list,
x,y,z,a,b,c,
d,e,f:boolean;

5. The compiled listing will include y,z,a,b,c,d,e, and f.
6. The Pascal Compiler version number is comprised of the version number and
the real-size default. For example, Pascal Compiler Version c5s-Z, means
version c5, symbolic degugging is available, and the real-size default is
two words. Use the following directives to override the default.

{$R2} and {$R4}

11-83

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

11.5.3

Pascal Compiler Back-End Errors

Compiler back-end errors can result from a variety of problems. Basically they
occur when the back end finds itself or the intermediate code file in an
unexpected state. (The intermediate code file is a file used by the compiler to
communicate between the front end and back end of the compiler. It consists of
compiler directives intermixed with actual P-code.) Back-end errors can be caused
by a corrupt intermediate code file, external forces (e.g. bad blocks in the
compiler), or source file information that is skipped by the' front end but used by
the back end.

II-84

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

The following table is a list of back-end errors and a possible explanation for the
error.
Error
Number

Comments

-1

While trying to generate the constant pool information for a
particular code segment, the back end tries to read one block from
the intermediate code file and the read fails.

1

I f the lexical procedure nesting is greater than 31, this error will
occur. Since the front end only allows nesting of seven procedures,
this error should theoretically never occur.

4

The intermediate code. file directives are bytes with values greater
than 252. If the back end reads a directive with a value that is
less than 253, error number 4 will result.

5

The current procedure number is greater than the maximum number
of procedures for that segment.

6

The operator (variable,constant,jump location) that the back end is
trying to remap is not in the scope of the compilation uni t.

7

The back end can not find the
resol ving jumps.

8

There are more than 400 jumps in the jump table while trying to
enter a site jump error. Try dividing each procedure with many
jumps into more than one procedure.

9

There are more than 400 jumps in the jump table while trying to
en ter a target jump. Try dividing each procedure with many jumps
in to more than one procedure.

11

The code pointer is less than 0 or greater than the length of the
intermediate code file while building a jump table.

12

A jump site can not be found in the jump table.

~arget

site to jump to while

II-as

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Error
Number

Comments

22

Unexpected end of input w'hile generating the LCO P-code
instruction.

23

Unexpected end of input while generating the LDC P-code
instruction.

24

The exi t for a certain procedure can not be found in the jump
table.

25

The code pointer is less than 0 or greater than the length of the
intermediate code file while generating p-code.

27

The code pointer is less than 0 before trying to read in more code
from the intermediate code file to the code buffer.

28

The codepointer is less than a after trying to read in more code
from the intermediate code file to the code buffer.

29

The current ,final output block number is greater than the block
number of the intermediate code file being processed.

30

The final ,code file size exceeds the intermediate code file size
before trying to write more final code.

31

The final code file size exceeds the intermediate code file size
after writing more final code.

41

The line length of a compiled listing exceeds 120 characters.
(Note: this error can occur on a pre.,.IV.1 compiler if there is an
illegal character after a DLE character.)

86

Could not find a particular segment in the intermediate code file.

99

The number of procedures does not match the number specified in
the procedure dictionary.

II-86

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

Recovery Options:
If a syntax error has occurred in the front end and a back·end error
occurs, fix the syntax error and try recompiling.
If there are bad blocks on any of the disks being used for the
compilation replace the bad disks with good ones and try recompiling.
If the bug persists and you purchased a fully adaptable system, please
report the problem to the p-System supplier.

II-87

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

11.6

Extended Memory

Extended memory is a new feature that allows the current release of the p-System
to run in environments of up to 128K of memory. This is accomplished by
dividing the p-System run time environment into two parts, each of which may
occupy as much as 64K bytes of memory.
The code pool is an area of memory where most code segments are executed by
the p-System. This code includes the operating system, filer, editor, etc., as well
as user programs. In non-extended memory systems, the code pool shares the
same space with the rest of the p-System (i.e. the interpreter, RSP, BIOS, SBIOS,
and the p-System stack and heap). The code pool resides between the stack and
heap on non-extended memory systems.
On extended memory systems, the code pool is placed in a separate area of
memory all together. Thus the code pool may occupy an entire 64K portion of
RAM, and the rest of the p-System may occupy another entire 64K area.
A major advantage of the extended memory feature is the additional memory space
available for executable code to use. This means that larger programs can be
compiled and executed.
Also, the code segments on extended memory systems may not need to be moved
or swapped as often as those on non-extended memory systems thereby producing
significant performance improvements.
Because there is more space for the p-System stack and heap to grow, the chances
of a stack overflow are reduced.

11-88

Users' Manual Supplement, Version IV
New and Upgraded Facilities

D.7

Echoed Characters

The user can now designate the character codes that the p-System will echo to the
screen. Previously, the system automatically echoed ASCII codes 13 and 32
through 126. Now, the user may select any subset of the character codes from a
through 255 (see SETUP in Chapter IV of this supplement under printable
characters).

ll-89

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

U.B
fLB.l

Editor Enhancements
Setting Tab Stops

The editor will now allow the user to set tab stops. From the E(dit command
prompt, press S(et, E(nvironment, and then press S(et tabstops. The system will
display the following interface prompt.
Set tabs: 

Ceoill

T(oggle tab



T----T ----T ----T----T --.-T----T ----T----T ----T ----T ----T----T ---Column/Il
The cursor will start at position one in the line of Ts and dashes (-). The line
'Column/II' indicates the positon of the cursor. To set or remove a tab, move the
cursor to the desired location using the right or left vector keys, or press 'c' and
enter the desired column number. Press.' to insert a tab or delete a tab.
Pressing . ' will change the indicator from a dash to T; pressing . ' again in the
same column will change the . ' back to a dash. The system displays the current
column number of the current cursor position and updates it each time a right/left
vector key or 'C(olumn' command is pressed.
The Version IV.I Editor is not compatible with existing IV.O Operating Systems. It
uses ei ther standard or ANSI SCREENOPS.

II.B.2

Editing Line in S(et E(nvironment Display

The following listing is an example of the S(et E(nvironment display showing a new
line above the date of file creation line. The new line identifies the file currently
being edited.

II-90

Users" Manual Supplement, Version IV
New and Upgraded Standard Facilities

>Environment:
{options}  to leave
A(uto indent
True
F(illing
False
L ( eft ma r 9 i, n
9
R(ight rrargin
70
P(ara ~rgin
9
C(omnand ch
S(et tabstops
T(oken def
true
3152 bytes used, 29612 available.
Editing: SCHEDLLE.TEXT
C rea ted Ma r chI 0, 1 9 8 2 ;

1a stu P d ate d Ma r c h 2 4 , 1 9 8 2 (r e vis ion

10)
Editor Version.
If the file has just been created but not named, the line will read-Editing:

11.8.3

unnamed

Byte-Sex Independent Environment Information

The en viron men t information in the first two blocks of a text file is no longer
byte-sex dependent. That is, the user can edit a file on a machine that has a
different byte sex than the machine on which the file was created, and the
environment information will be available.

1I.8.4

Editor Control Characters

The restrictions on the values for the following data fields in SYSTEM.MISCINFO
have been removed.
EDITOR
EDITOR
KEY TO
KEY TO
KEY TO
KEY TO
KEY TO
KEY TO

ACCEPT KEY
ESCAPE KEY
DELETE CHAR
DELETE LINE
MV CURS DOWN
MV CURS LEFT
MV CURS RGHT
MV CURS LP

The user can now use SETUP to designate which key or keys on the terminal will
control the 'corresponding editing function.
II-91

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

For example, to set up a function key whose value is  A, ,set up the Editor
Escape Key to be prefixed A.
If any functon key has the same value as the keyboard prefix, then the user must
indicate in SETUP that the key is prefixed and must press the key twice to make
it function.

II-92

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

11.9

The 8086 and 68000 Assemblers

This section contains information that is specific to the 8086 and 68000 versions of
the UCSD p-System Adaptable Assembler.

11.9.1

The 8086 Assembler

The UCSD p-System 8086/88/87 Assembler differs in some respects from the
standard Intel Assembler. These differences are listed in this section. Also, the
8086/88/87 specific assembler errors are listed.

D.9.1.1

Notational Conventions

The following paragraphs define the 8086 notational conventions.
Assembler Directives. None of the Intel Assembler directives or operators are
implemented. Instead, the assembler directives described in the Users Manual,
Version IV.O are available.
P aren theses. Index or base register references in a memory operand are enclosed
in parentheses, not square brackets, e.g., FIRST(BX) rather than FIRST(BX].
Immediate Byte. The following example shows how the ADD immediate byte to
memory operand is coded to distinguish it from the ADD memop, immedword,
which is the default.
ADDBIM

memop,immedbyte

Similarly, MOVBIM, ADCBIM, SUBBIM, SBBBIM, CMPBIM, ANDBIM, ORBIM,
XORBIM, and TESTBIM are added to the vocabulary.
Memory Byte. The following example shows how an INC memory byte is coded to
distinguish it from INC memory word, which is the default.
INCMB

memop

Similarly, DEeMB, MLLMB, IMLLMB, DIVMB, IDIVMB, NOTMB, NEGMB, ROLMB,
RORMB, RCLMB, RCRMB, SALMB, SHLMB, SHRM8, SARMB were added to the
vocabulary to specify memory byte operands.
MUL and DIY Byte. In MLL, IMLL, DIV, IDIV the single memory operand form
implies a word operation. For example,
MLL

memop
II-93

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

To specify a byte operation, either MLLMS memop or the following form may be
used.
MLL

AL,memop

The same is true for IMlJ.., DIV, IDIV.
NOTE: The DIV AL,memop is rather misleading because the actual operation
would be AX/memory-byte.)
MOV Substitute for LEA. F or LEA reg,label or LEA reg,labei+const the
assembler will substitute MOV reg,immed val for immed val : label or
label+const. This saves four clock times (4 vs. 8).
IN and OUT. The normal form of IN and OUT is IN ac,port or IN ac,DX and
OUT port,ac or OUT DX,ac where ac: AL denotes an 8-bit data path and
ac= AX denotes a 16-bit path. Since the accumulator is the only possible register
source/destination (DX specifies port: address in OX), single operand forms are also
provided: INS and OUTS for byte data, and INW and OUTW for 16-bit data. The
syntax is IN8 port or IN8 DX.
In the two-operand forms of IN and OUT, the order of the operands is not
important; thus OUT ac,DX or OUT ac,port will be acceptable.
String Operations. The mnemonics for the string operations are suffixed with S or
W to denote byte or word operations: thus MOVSB and MOVSW, CMPSS and
CMPSW, SCASB and SCASW, LOOSB and LODSW, and STOSB and STOSW are in
the vocabulary, but MOVS ••• STOS are not.
Segment Override. XLAT and the string instructions have implied memory
operands and no code is required in the operand field. However, in order to
permit the specification of a segment override prefix in the case of XLAT,
MOVSB/MOVSW, CMPSS/CMPSW, and LODSB/LODSW, the assembler permits
operand expressions for these instructioos.
NOTE: The only the default segment for 51, namely OS, can be overridden. The
segment for 01 is ES and cannot be overridden. A segment override prefix of OS
applied to 51 does not generate a segment override prefix.

11-94

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

If these operations were written with operands, they would have the following
syntax.
XLAT
tvOIS

OvPS
SCAS
LCDS
STOS

AL, (BX)
(01), [seg:] (51)
(OI),[seg:](SI)

BIW
BIW
BIW
B IW
BIW

(01 ) ,AX

AX, [ s eg : ] ( 5 I )
(01 ) ,AX

The string instructions may be prefixed by a REP (repeat) instruction of some
type. The assembler flags an error if both REP and a segment override are
specified.
In addition to the forms DS:memop, etc., a separate mnemonic SEG followed by a
segment register name may be written in a statement preceding the instruction
mnemonic.
Examples:
MOV

AX,ES:AVALUE

is equivalent to
SEG

ES

MOV

AX,AVALUE

Long Jumps, Calls, and Returns.
implemented as follows:

Intersegmen t CALL, RET, and JMP are

a.

The mnemonics CALLL, RETL, and JMPL specifically designate
intersegment operations.

b.

An indirect address (e.g., (reg) or (label)) is assembled in standard
fashion with a "mod op rim" effective address byte possibly
followed by displacement bytes. The memory location referenced
must hold the new IP, and the next higher location must hold the
new CS.

c.

The direct address form must have two absolute operands:
CALLL

expr 1 ,expr2

where exprl is the new IP and expr2 becomes the new CS.
Constan ts or extern al symbols (e.g., .. REF d,efinitions) qualify as
absolute operands.

II-95

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

8087 Mnemonics. Mnemonics for the 8087 floating point operations are standard
except for certain of the memory reference operations, where a letter suffix is
appended to denote the operand size:

o

short real or short integer (double word)

Q

long real or long integer (quad word)

W

integer word

T

temporary real (ten byte)

The 0 and Q suffixes apply to the following real ops:
FAOO, FCOM, FCOMP, FOIV, FDIVR, FMlL, FST, FSUB, FSUBR,
FLO, FSTP
e.g., F ADDD, F AOOQ, etc.
The T suffix applies only to FLO and FSTP.
The W and 0 suffixes apply to the following integer ops:
FIAOD, FICOM, FICOMP, FIOIV, FIOIVR, FIMUL, FIST, FISUB,
FISUBR, FILO, FISTP
The Q suffix for long integers applies only to FILO and FISTP.

11.9.1.2

8086/88/87 Assembler Error Messages

The following error messages are specific to the 8086/88/87 Assembler:
76
77
78
79
80
81
82
83
84
85
86
87
88
89
II-96

: Had label, open parenthesis then illegality
Expected absolute expression
Both operands connot be a segment register
Illegal pair of index registers
Have to use BX,BP,SI or 01
Illegal constant as first operand
The first operand is needed
: The second operand is needed
: Expected comma before 2nd operand
Registers stand alone except in indirect
: Only 2 registers per operand
: Expected label or absolute
Illegal to use BP indirect alone
: Close parenthesis expected

Users' Manual Supplemen t, Version IV
New and Upgraded Standard Facilities

90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
III
112
113
114
115
116
117
lIB
119
120
121
122
123
124

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

:
:
:

Cannot POP CS
Cannot have exchange of rB with r16
Segment registers not allowed
ESC external op on left must be const < 64
Only one of the operands can have segmen t override
Right operand must be a memory location
Left operand must be a 16-bit register
Left operand must be memory or register alone
Op cannot be a segment register or immediate
Coun t must be 1 or in CL
A byte constant operand is required
Operand must use () or be a label
LOCK followed by something illegal
REP precedes only string operations
Not implemented
Expected a label
.
Open parenthesis expected
Expected register alone as right operand
Segovpre then regalone, thats illegal
Only one operand allowed
.
Operands are AL,op2 for byte MLL, etc.
SP can only be used with the SS segment
MOVBIM only for immediate to memory
BIMs must be immediate bytes to memory
Seg override on repeated instruction not ok
Segment register expected
(BOB7) Invalid two-operand format
(8087) Invalid single operand format
(8087) Improper operand field
(8087) Instruction has no operands
No override of ES on string destination
Interseg needs 2 constant or external operands
I/O port must be immediate byte or OX
I/O source/dest register must be AL or AX

II-97

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

fi.9.1.3

Sharing Machine Resources with the Interpreter

11.9.1.3.1

CaUingand Retuming

The p-System Interpreter invokes an assembly routine using the call long (CALLL)
operator. Thus, the top of the stack contains a two-word return address when the
operating system enters the routine. To return from an assembly routine, use the
return long (RETL) operator, or pop the return address and use a jump long (JMPL)
operation.

11.9.1.3.2

Acceaing Parameters

To access parameters that are passed to an assembly routine, move the value of
register SP (which points to the P-machine stack) into BP. Access the parameters
by adding an offset of 4 bytes (to account for the two-word return address. The
first parameter (at the location 4 bytes above the top of the stack) is actually the
last declared parameter in the host routine (the parameters are pushed in the order
that they are declared).
I f a .FUNe assembly routine is to return a function value, place the function value
just above the last parameter using the same accessing scheme. The size of the
returned function value is either 1, 2 or 4 words.

Give the RETL operator an operand that indicates how many bytes to cut the
stack back after popping its two-word retum address. Use the size of the data
space occupied by the parameters. Thus, the user may access parameters and
make a clean return without using a specific POP or PUSH instruction.
The following listing is an example of the scheme of accessing parameters and
returning.

rvov
MOV

M:N

rvov

BP, SP
AX, (BP+4) ;Last Param
BX, (BP+6) ;Mi dd 1e Par am
ex, (BP + 8) ; Fir s t Par am

(BP+IO),RSLT ;Function return val
; (if .FLN:)
RETL

II-98

6

; Remove 3 par ams

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

0.9.1.3.3

Register Usage

A 11 of the 8086/88 registers are available for use by user assembly routines (the
interpreter saves and restores the register values that it needs).
55 and SP must be preserved by the user, however. (The user may create and use
a private stack if a minimum of 40 words are left available for stack expansion
during interrupts. This is a very dangerous procedure, however, and is not
recommended.)
NOTE: The integrity of the P-machine stack must be maintained. This is the
programmer's responsibility and if this is not done, the results are unpredictable.
When the operating system enters the assembly routine, 55 equals the P-machine
stack pointer (SP). Also, OS, ES, and CS are all equal to the base of the pSystem code segment.
Parameters that are passed as Pascal VAR variables are p-System pointers to
actual data. These pointers are relative to 55 •
•PRIV ATE and .PUBLIC variables are are also 55 relative •
•BYTE quantities, .WORD quantities, and .REF'f labels are relative to CS, OS, or
ES.

11.9.2

68000 Assembler Syntax Conventions

The 68000 Assembler follows Motorola standard syntax for opcode fields, register
names and address modes. The following list points out some restrictions of the pSystem Adaptable Assembler.
Only the absolute short address mode is available.
address cannot be generated by the assembler.

The absolute long

Labels may not be accessed with the absolute address mode.
References to labels with a .PROC or .FUNC generate the PC-relative
address mode.
An external label may only be accessed as a displacement from an
address register.
Immediates above FFFFH cannot be generated.
Opc'odes which have an optional suffix of A,I,M,Q or X must contain
II-99

Users' Manual Supplement, Version IV
New and Upgraded Standard F acili ties

that suffix explicitly.
Length qualifiers (.B, • W or .L) must be specified explicitly in those
instructions which have a choice of length. All other instructions must
not contain a length qualifier.
The following instructions must contain a length qualifier:
ADD, ADDA, ADoI, ADDQ, ADDX, AND, ANDI, ASL (register), ASR
(register), CLR, CMP, CMPA, CMPI, CMPM, EOR, EaRl, EXT, LSL
(register), LSR (register), MOVE (except special forms), MOVEA, MOVEM,
MOVEP, NEG, NEGX, NOT, OR, ORI, ROL (register), ROR (register),
ROXL (register), ROXR (register), SUB, SUBA, SUBI, SUBQ, SUBX, TST
The following instructions must not contain a length qualifier:
ABCD, ASL (memory), ASR (memory), BCHG, BCLR, BSET, BTST, CHK,
DBcc, DIVS, DIVU, EXG, JMP, JSR, LEA, LINK, LSL (memory), LSR
(memory), MOVE to CCR, MOVE to SR, MOVE from SR, MOVE USP,
MOVEQ, MULS, MULU, NeCD, NOP, PEA, RESET, ROL (memory),
ROR (memory), ROXL (memory) ROXR (memory), RTE, RSR, RTS,
SBCD, Scc, STOP, SWAP, T AS, TRAP, TRAPV, UNLK
The following instructions may contain an optional length qualifier of .S (generate
short forward branch):
Bcc, BRA, BSR
0.9.2.1

Miscellaneous

The 68000 processor is byte-addressed and word-oriented. The byte sex is mostsignificant byte first.
The default constant radix is decimal, and the default list radix is hexadecimal.
0.9.2.2

68000 Error Messages

The following error messages are specific to the 68000 Assembler:
76:
77:
78:
79:
80:
81:
82:
11 ... 100

unrecognizable address mode
address register expected
close paren ')' expected
displacement out of range
index register expected
illegal length qualifier
illegal source address mode

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

83:
84:
85:
86:
87:
88:
89:
90:

illegal destination address mode
comma',' expected
length qualifier required
length qualifier not allowed
data register expected
label expected
illegal register list
immediate operand expected

II-lOl

Users' Manual Supplement, Version IV
New and Upgraded F acili ties

D.lD
11.10.1

Tumkey Applications Facilities
SYSTEM.MENU

If an applications programmer wishes to design display prompts for a particular
application, he or she may write a program called *SYSTEM.MENU that will
display a menu for his or her particular applications environment. The main pSystem prompt line need never be displayed if the program chaining facilities are
used (see the Users Manual, Version IV.O).
The user must place the compiled code file called SYSTEM.MENU on the system
disk. The p-System will execute SY5TEM.fV1ENU each time the system prompt line
would normally appear.
SYSTEM.MENU works much like SYSTEM.STARTUP. If it is present, the system
will execute SYSTEM.MENU any time the user initializes the system.

11.10.2

Single-Use Tumkey System

S ingle-use tum key is a version of the p-System designed to package and execute a
single application program or series of related programs called via the p-System
chain mechanism. The package may contain SYSTEM.STARTUP, but must contain
an executable code file called SYSTEM.MENU. The facilities on the main system
prompt line such as the editor and the filer are not available.

II-I02

Users' Manual Supplement, Version IV
New and Upgraded Facilities

fi.lD.)

System Initialization

The following diagram illustrates the implementation and the flow of control within
the operating system.
SYSTEM INITIALIZATION

I

EXECUTE *SYSTEM.STARTUP
(IF POSSIBLE)

1

IS CHAIN OF PROGRAMS -------~) NO

EMPTY?

EXECUTE CHAINED
PROGRAM

YES

IS *SYSTEM. MENU

--------)~

EXECUTABLE?

1

YES

EXECUTE--------~

NO

*SYSTEM.MENU

I

SINCLE-USE
TURNKEY SYSTEM?

--~

----------~,

YES - - - . , . , HALT

I

NO

1

MAIN SYSTEM PROMPT

11-103

Users' Manual Supplement, Version IV
New and Upgraded Standard F aci li ties

fi.ll

Performance Monitor

The user can gain access to performance information by writing a unit called
PERFOPS and including it in the operating system. The p-System contains the
following interface for PERFOPS.
UNIT PERFOPS:
USES KERNEL;
PROCEDURE PM Fault;
PROCEDURE PM-Dump Seg CSegToDump : SIB P);
PROCEDURE PM-Prog Begin;
PROCEDURE PM-Prog-End;
PROCEDURE PM-StartStop (Start: BOOLEAN);
PROCEDURE PM-Interactive;
IMPLEMENT ATION With the exception of PM Start Stop and PM Interactive, the operating system calls
these procedures to indIcate -actions that the system is taking. Calls to these
procedures by the operating system will only be made if the boolean, Has PM,
located in the KERNEL interface section, is set to true.
The following paragraphs describe the procedures.
PM_Fault. The operating system calls this procedure each time it enters the
fault handler. (A fault occurs whenever a code segment is needed from disk,
when the stack is about to run into the code pool or the heap, when the heap is
about to run into the code pool or the stack, or if a pool fault occurs on
systems with extended memory.) This procedure must not· cause an additional
faul t; it must not c~ll any procedure that may not be in memory. Stack space
requirements must be minimized.
PM Dump Seg. The operating systems calls this procedure from the fault
handler. -PM_Dump_Seg indicates that SegToDump is being removed from the
code pool. This procedure must not cause an additional fault; it must not call
any procedure that may not be in memory. Stack space requirements must be
minimized.
.
PM Prog Begin. The operating system calls this procedure to indicate that a
program is about to start.
PM_Prog_End.
program.

·n-lq4

The operating system calls this procedure to mark the end of a

Users' Manual Supplement, Version IV
New and Upgraded Standard Facilities

P M_S tart_Stop. This entry point controls performance monitoring. This procedure
will memlock PERFOPS and set Has PM to true, or vice versa depending on the
value of parameter start. The user-must call this routine before PERFOPS can
be used. It should be called again to deactivate PERFOPS.
NOTE:

PERFOPS must be memlocked before setting Has_PM to true.

PM Interactive. The 'I' command in the debugger will call this procedure if
Has_PM is true. This routine will provide data gathered by the first four
procedures of PERFOPS. In this way, a user can use PERFOPS interactively
from the debugger.

11-105

Users' Manual Supplement, Version IV
New and Upgraded Facilities

D.12

REALCONV Utility

REALCONV is a utili ty that converts real constants in a IV.O code file from
canonical (compiled) form to native machine format. It eliminates the need to
convert real constan ts at segment load time, thus increasing the initial loading
speed of the program segments, as well as the overall run-time speed of the
program. This is especially important for programs that require frequent loading
of segments containing real constants.
The real constant conversion utility is a filter that works on code files, replacing
canonical reals by run-time reals in-place. Hence, when the source file is not
available, it is advisable to make a backup copy of the code file to be processed
before executing the utility program. This will avoid destroying the code file
while executing REALCONV (with an unsuccessful block write).
Because the conversion algorithm uses real arithmetic of the host processor, the
utili t y must be executed on the processor on which the output file will run. In
most cases, a code file produced by the utility will not run on another processor,
which reduces the portability of otherwise completely transportable code. The user
may choose to sacrifice portability for execution speed on a time-critical program.
To use the REALCONV, press X(ecute at the command level.
respond with the following prompt.

The system will

EXECLJrE WHAT FILE?
Enter REALCONV, then press .
following prompt.

The utility program will display the

ENTER FILE NAME:
Enter the name of the code file to be processed, and then press .
not necessary to include the suffix .code.

It is

If REALCONV cannot complete the conversion successfully, it will print a message
and stop. The following listing shows examples of possible messages.
t\()T EI\O...G-f tvEtvffiY

ERRCR IN READII\G ••• (The dots represent segment dictionaries,
first block, constant pool or segment as the case may be)
ERRCR IN v.E{ I T I f\G S EGvENT
TCO ~NY DICTIQ\JARIES

II-I06

Users' Manual Supplement, Version IV
New and Upgraded Facilities

The following paragraphs describe the error messages.
NOT ENOUGH MEMORY.
available memory space.
ERROR IN READING.

The segment to be processed is larger than the

Execute REALCONV again.

TOO MANY DICTIONARIES. . There are more than 80 segments in the file.
If REALCONV executes successfully, the system displays a dot on the console for
each segment converted, and once the conversion is completed, the system displays
the following message.
ENTER FILE NAME:
The user may enter the name of another file for processing or press  to
exit REALCONV and return to the command level prompt line.

II-I07

m
ID.I

NEW OPTIONAL F ACILmES

Nati ve Code Generator

Nati ve code generators (NCG) are utility programs that translate selected portions
of an executable P-code file' into native code (n-code). Using native code
directives inserted into the source code, the user indicates which portions of the
file are to be translated. The result of this procedure is an equivalent p-System
code file that contains P-code and n-code. The NCG will translate only valid
executable code files produced by a UCSD p-System compiler.
Because n-code generally executes faster than P-code, the NCG can be used to
speed up the execution of selected portions of P-code, for example, portions of
code where most of the run time is spent. However, P-code was designed for
compactness and consequently takes up less space in memory than n-code. To use
the NCG effectively, translate only those portions of P-code for which execution
time is cri tical. Misuse of the NCG can greatly increase the size of the code
file.
The user indicates that portions of code are to be translated by inserting native
code directi ves into the source file before compilati.on. The following compiletime swi tches are the native code directi ves.
$N+ and $NThe user inserts the first swi tch {$N+} where the translation should begin and
inserts the last switch {$N-} where the translation should end. When the compiler
encounters the first switch, it begins generating the additional P-code necessary for
n-code generation and stops generating when it encounters the last switch. The
default setting for this compiler option is {$N-}. (This notation applies to USSD
Pascal. Similar notations apply to other languages.)

ID.I.I Native Code Directives and Pascal
Because the NCG translates a Pascal code file on a procedure by procedure basis,
only a complete procedure (function or process as defined in UCSD Pascal) can be
translated. One set of native code directives may designate more than one
procedure; but the nati ve ca.de generation cannot begin within the body of a
procedure. The following example shows the use of the native code directives in
Pascal.
function
{$N+}
begin
if a
end;
{$N- }

~X

(a,b:

> b then

integer):
~X:=

a else

integer;
~:=

b;

III-l

Users' Manual Supplement, Version IV
New Optional Facilities

The object code file, produced by the compiler from source code containing native
code directives, is an executable P-code file that maintains its machine portability.
The only difference is that the native code directives slightly increase the size of
the object code file.

ID.I.2

Native Code Directives and BASIC

The native code directives ($N+ and $N-) can be inserted into the BASIC source
code file at any point within a procedure. The user can specify translation on a
statement by statement basis. The following example shows the use of native
code directives in BASIC.
1=3

OOSUB 100
1=4

ensue

100

STOP
{$N+}
100 REM

THE SUBROJT I NE

FCR J=l TO 100

i~TI

I' 5, I • • 5

ttXT J
RETLRN
EI\D

ID.I.l

Native Code Directives and FORTRAN

To designate code for translation in a FORTRAN source code file, the user must
place the native code directive {$NATIVE} before the first statement function or
executable statement in a procedure. The native code directive must begin in the
first column of the line. The translation directive still applies for the entire
procedure. The following example shows the use of native code directives in
FORTRAN.
FLN:T I ()\J fv\t\)( (I, J )
$NATIVE
fV\GJ(=I
IF (J .GT. I) fv\t\)(=J
RETlRN
EN)

11I-2

Users' Manual Supplement, Version IV
New Optional F acUities

m.l.4

Running the Native Code Generator (NeG)

The NeG is run by executing one of the following files, depending on the
processor.

*

Z80.NCG.CODE

*

aOaO.NCG.CODE

*

aOa6.NCG.CODE

*

9900.NCG.CODE

The NCG generates a prompt asking the user for an input code file and an output
code file. The output file must contain the suffix .CODE. Only executable code
files can be translated by the NCG (they must be already linked).
The NCG will produce a formatted listing of the code generated for each
procedure it transl ates. The NCG generates a prompt asking the user for the
name of a listing file. To produce a listing, enter a listing file name, for
example, Console:, Printer:, 115:List, List.Text. To eliminate the listing, press the
return key in response to the prompt.

IU-3

Users' Manual Supplement, Version IV
New Optional Facilities

The following listing is an example of function MAX translated on the Z80 NeG.
-------~---------------------------------------------- ------------------------------~-----------------------------

Final Z80 Code for segnent TEST
Segnent offset 30
Source Object
P-Code N-Code
(Dec. Offsets)

procedure 2

tvP

.RADIX

10

.EGlJ

BC

==========================================================
01
01

4:

9:

11:
13 :

\ 15:
15 :

IU-4

.vrnD

o I AS
11
41
71
101
131
141
151
181
191

005EOA
005609
006EOC
006600
7A

221

78

231
241
251
26
29
32
33
36
39
40
41
42
45
48
49
52
5
6
57
58
61
61

95
7A
9C
F24BOO
210EOO
09
005EOC
C05600
73
2C
72
C35800
210EOO
09
005EOA
C05609
73
2C
72
aJ4200

;P-code

LO

LD
XCR

AC

F23400
A2
C33800

9602

NATIVE
LD
LD
LD

JP
AI\O

Ll:

L2:

E, (IX+I0)
0, (IX+11)
L, (IX+ 12)
H, (IX+ 13)
A,O
H

P,L1

o

JP

L2

LD

A,E

SUB

L

LD

A,D

sec

JP

LD
ACD
LD
LD
LD

H

P,L3
H..,14

HL,BC

JP

E, ( IX+ 12)
0, (IX+ 13)
(H-) ,E
L
(J-t.) ,0
L4

LD

H..,14

/lCD

HL,BC

LD

E, (IX+I0)
0, (IX+ 11)
(H..) ,E
L
(H..) ,0
INTRP REL+66

Ir-.c

LD
L3:

91,-30

LO
LO

Ir-.c

LD
L4:
CALL
;exit code
;P-code RPU

2

Users' Manual Supplement, Version IV
New Optional Facilities

The following listing is an example of function
the 8086.

~X

translated on

----------------------------------------------------------

Final 8086 Code for segment TEST procedure 2
Segnent byte offset 30
Source Object
.RADIX
P-Code n-Code
.EGlJ
IVP
(Dec. Offsets)
.EGlJ
BASE

10
BP
OX

===========================================================

4:

9:

11:
13 :
15:
15:

01
01
01
11
31
61
91
III
121
141
161
191
221
241
271
301
341
341

.vrnD

A8
33CO

;p-code

385E02
7FOI
40
DIE8
7208
884604
894606
EB06
884602
894606
FFIE0400
9602

NATIVE
XCR

tvOv

8B5E~

Qvp

JG

If\!:

Ll :

SJ-R
JC

tvOv
NOV
JfvP

L2 :

34,0

NOV
NOV
L3:
CALL
;exit code
;p-code RPU

AX,AX
BX,4[BP]
BX,2[BP]
Ll
AX
AX,1
L2
AX,4[8P]
6[BP] ,AX
L3
AX,2[BP]
6 [BP] ,AX
4
2

III-5

Users' Manual Supplement, Version IV
New Optional Facilities

The following listing is an example of function MAX translated on the 8080.

----------------------------------------------------------

Final 8080 Code for segnent TEST
procedure 2
Segnent offset 30
Source Object
.RADIX
P-Code N-Code
(Dec. Offsets)
MP
.EQU

10
BC

==========================================================

o
o
4:

o

1
4
5
6

9:

11:
In-6

7
8
11
12
13
14
15
16
17
18
21
22
25
26
27
28
291
321
351
361
371
381
391
421
431
441
451
461

.'AtRD

A8
210AOO
09
5E
2C
56
210COO
09
7E
2C

;p-code

LD

E, (I-L)

IN:

L
0, (rL)

I-L,OC

LD

A, (I-L )
L
H, (I-L)

If\C

Ll:

L2:

HL,12

AOO

LD
LD
LD

9C

F24FOO
210COO
09
5E
2C
56
210EOO
09
73
2C
72
C35DOO

ACD

rL,,10
HL,BC

LD
LD

66

6F
7A
AC
F23700
A2
C33BOO
7B
95
7A

NATIVE
LD

96,-30

L,A
A,D

Xffi
JP

H

AN)

D

JP

L2
A,E

LD
SUB
LD
SOC
JP

LD
ACO

P,Ll

L

A,D
H

P,L3
HL,12
HL,BC

LD

E, (f-l. )

IN:

L

LD
LD

0, (I-L)

Aro

rL,14
HL,BC

LD

(I-L) ,E

IN:

LD

L
(H..) ,0

JP

L4

Users' Manual Supplement, Version IV
New Optional Facilities

13:

491
521
531
541
551
561
591
601
611
621
631
661
661

15:
15:

210AOO
09
5E
2C
56
210EOO
09
73
2C
72
0)4200

L3:

LD
Am

LD
II\C
LD
LD
AOO

LD
II\C
LD
L4:
CALL
;exit code
;p-code RPU

9602

HL,10
HL,BC
E, (HL)
L
0, (HL)

HL,14
HL,BC
(HL) ,E
L
(HL) ,0
INTRP REL+66
2

The following listing is an example of function MAX translated on the 9900.

---------------------------------------------------------

Final 9900 Code for Segment TEST
Segment byte offset 30
tvP

Source Object
P-Code n-Code
(Dec. Offsets)

SP
8K
SEG
BASE

Procedure 2
.RADIX
.EGU
.EGlJ
.EGU
.EQJ

.EGU

10
R9
RIO
R12
R13
R14

---------------------------------------------------------

4:

9:
11:
13:
15:
15:

01
01
01
11
21
sl
101
121
lsi
20 I
261
2s1
2s1

.'M:RD

AS
AS
SA69 OODC OOOA
1105
1304
CA69 OOOC OOOE
1003
CA69 OOOA OOOE
069C
9602

l\IATI VE
l\IATIVE
C
JLT
JEQ
tvOv
JtvP
tvOv
Ll :
L2 :
BL
;exit code
;p-code RPU

5S,0

;p-code
jp-code

@12 (NP) ,@10 (tvP)
Ll
Ll
@12 (rvp) ,@14 (rvP)
L2
@10 (rvp) ,@14 (tv1=?)
*BK
2

III.;;. 7

Users' Manual Supplement, Version IV
New Optional Facilities

The preceding listings show the hybrid mixture of P-code and n-code produced by
the NeG. Cooperation between the n-code code and the p-machine interpreter is
achieved using the following conventions:

*

NATIVE is the P-code that instructs the interpreter to start executing ncode. On the Z80, 8080, and 8086, execution starts on the byte following
the NATIVE instruction. On the 9900, execution begins on the first word
boundary following the NATIVE instruction.

*

The header lists the register conventions:
and processsor registers on the right.

*

The following reference points on each processor "listing indicate the
instruction that returns the processor from n-code to P-code.

P-machine registers on the left

Z80 Listing, line L4
8086 Listing, line L3
8080 Listing, line L4
9900 Listing, line L2

*

On the Z80 and 8080, global and external variables are referenced through
BASE relati ve relocation. On the 8086, global variables are referenced
through register OX, which contains Base. On the 9900, global variables
are referenced indexed from R14, which contains Base. On both the 8086
and the 9900, external variables are referenced via base relative
relocation.

On the whole, the listing looks very much like a listing created by the assembler.
The following notes may help interpret the differences.

*

P-code is preceded by the the notation, ;P-code (all other instructions are
n-code.)

*

The exi t code point of the procedure is marked by the notation, ;exit
code.

* The left-most column of numbers contains decimal byte offsets of
equi valent P-code in the original code file. These offsets should help
identify the source code by the offset in the compiler listing.

*

Ill-8

The second column contains decimal byte offsets into the final procedure
code generated by the NeG.

Users' Manual Supplement, Version IV
New Optional Facilities

lll.l.S

Limits of Native Code Generation

The NeG produces an object code file whose execution behavior is identical to the
P-code file, except for differences in execution speed.
In those instances in which the compiler emits calls to a run-time support routine,
the NeG leaves the P-code intact. Therefore, P-code is used in those places
where translation would generate excessi ve code.
Sequences of straight n-code (code between a NATIVE instruction and its matching
return instruction (See individual processor listings.) are treated by the p-machine
as a single P-code. This fact causes two problems. First, although the 
key may be recognized by the interpreter at any point, no further action is taken
until the next P-code boundary (i.e.,until the current P-code is completed and the
next P-code is encountered). Since there are no p-code boundaries in n-code, long
sequences of n-code cannot be terminated by pressing the  key. Second, pmachine events (interrupts), like the break key, are only acted upon at P-code
boundaries.
It is possible to work around these problems. The user may force a P-code
procedure call by calling an empty procedure. Since the procedure call P-codes
fall into the class of P-code that are never translated into n-code by the NeG,
long sequences of n-code can be broken into smaller sequences by a procedure call.
Since it is the procedure call i tsel f that breaks up the sequence, the called
procedure could be an empty shell.
Some unusual FORTRAN and Pascal contructs create code that the NeG will not
translate. For example, using the Pascal primitive, P Machine, to generate an RPU
instruction and in FORTRAN, using a construct called an assigned GOTO construct
will result in the error message: Undefined label.

III-9

Users' Manual Supplement, Version IV
New Optional Facilities

Ill.2

Print Spooling

The print spooler is a program that allows the user to queue and print files
concurrently with the normal execution of the p-System (while the console is
wai ting for input from the keyboard). The queue it creates is a file called
*SYSTEM.SPOOLER, and the files the user wishes to print must reside on volumes
that are on-line or an error will occur.
When SPOOLER is eX(ecuted, the following prompt line appears.
Spool: P(rint, D(elete, LOst, S(uspend, R(esume, A(bort, C(lear, Q(uit
The following paragraphs define the prompt line options.
P(rint.
Prompts for the name of a file to be printed. This name is then
added to the queue. If SYSTEM.SPOOLER does not already exist, it is created.
In the simplest case, P(rint may be used to send a single file to the printer.
Up to 21 files may be placed in the print queue.
D(elete. Prompts for a file name to be taken out of the print queue.
occurrences of that file name are taken out of the queue.
L(ist.

All

Displays the files currently in the queue.

S(uspend.

Temporarily halts printing of the current file.

R(esume. Continues printing the current file after a S(uspend. R(esume also
starts printing the next file in the queue after an error or an A(bort.
A(bort. Permanently stops the printing process of the current file and takes it
out of the queue.
C(lear.
Q(uit.

Deletes all file names from the queue.
Exits the spooler utility and starts transferring files to the printer.

If an error occurs (e.g., a nonexistent file is specified in the queue), the error
message appears only when the p-System is at the main system prompt line. If
necessary, the spooler waits until the user returns to the" outer level.

In-IO

Users' Manual Supplement, Version IV
New Optional Facilities

Program output to the printer may run concurrently with spooled output. The
spooler finishes the current file and then turns the printer over to the user
program. (The user program is suspended while it waits for the printer.) The user
program should only do Pascal (or other high-level) writes to the printer. If the
user program does printer output using unitwrite, the output is sent immediately
and appears randomly interspersed with the spooler output.
The utility SPOOLER.CODE uses the operating system unit SPOOLOPS. Within
this uni t is a process called spool task. Spooltask is started at boot time and runs
concurrently with the rest of the UCSD p-System. The print spooler automatically
restarts at boot time if *SYSTEM.SPOOLER is not empty. When the file
*SYSTEM .sPOOLER exists, spooltask prints the files that it names. Spooitask runs
as a background to the main operations of the p-System.
*SPOOLER.CODE interfaces with SPOOLOPS and uses routines within it to
generate and alter the print queue within *SYSTEM.SPOOLER.
To restart the print spooling process if SPOOLER.CODE is executing when the
system goes down, reboot the system, press X(ecute from the command prompt
line, enter *SPOOLER.CODE, and press . Then press R(esume.

III-lI

Users' Manual Supplement, Version IV
New Optional Facilities

111.3

CP 1M XenoFile

This product is meant for users of CP/M 2.0 and later editions, or users who wish
to access disks that contain a CP/M directory.
The p-System XenoFile package allows programs compiled on the p-System (in
either Pascal, BASIC, or FORTRAN) to use disks that contain a CP/M directory
To understand this chapter, read the CP/M Interface Guide, published by Digital
Research, Inc.
XenoFile consists of three units and two utility programs. The utility program
CPM CNFIG must be run in order to configure the package for your particular
system. CPM FILER is a simple filehandler that allows you to read CP/M
directories ana transfer files on CP/M format disks to and from p-System format
disks. Programs in UCSD Pascal may access CP/M disks by using CPM2_UNIT.
FCPM provides the same facilities for FORTRAN-77 programs, and BCPM is for
the use of BASIC programs.

ID.3.1

Configuring the XenoFile Package

The first thing you must do is X(ecute CPM CNFIG.
a series of questions about your disk configuration.

This utility presents you with

Your answers to these prompts are saved in a file called CPM CNFIG.OA TA.
Every time CPM2 UNIT is initialized it reads and uses the information in
CPM CNFIG.DATA.
Thus, every time you use XENOFILE, the file
CPM_~NFIG.DA T A must be on the prefixed disk.
CPM FILER, FCPM, and BCPM all use CPM2_UNIT, so they also require
CPM_L:NFIG.DAT A to be present on an on-line disk.

III-l 2

Users' Manual Supplement, Version IV
New Optional Facilities

The following listing is the console display from a sample run of CPM CNFIG (the
values shown are the default values, which apply to many hardware configurations).
a)
b)
c)
d)
e)
f)
g)
h)

maximum drive number starting with 0
highest physical track number
number of sectors per track
number of bytes per sector
number of CP/M blocks per disk minus one
maximum random record number starting with 0
buffer size minus one
maximum directory entries per disk
i) number of blocks allocated for directory
j) offset to first CPM track
k) number of records per block
1) number of directory entries per sector
m) maximum record count for an extent
n) maximum extent block index minus one
0) sector interleave (CPM skew factor)
CPM_CNFIG: Select letter ("aft to

"o'~

=3
= 76
= 26
= 128
= 242
= 4095
= 127
= 63
=2
=2
=8
=4
= 128
= 15
=6

of value to be changed,?

As the prompt shows, any of the values displayed may be changed in order to fit
your particular hardware. When all of the values match your system, type "Q" to
quit. When you type "Q", the bottom prompt line changes to:
QUIT: I(nstall changes, R(einstall defaults, E(xit without change
If you type ''I'', the values you chose are written to the file CPM CNFIG.DAT A (if
this file did not exist before, CPM CNFIG creates it). If you type ''R'', the
default values are written to CPM CNFIG.DAT A. Finally, if you type "E",
CPM CNFIG terminates without producing any output, unless there is no
CPM -CNFIG.DA T A file on-line. In this case, E(xit creates. a CPM CNFIG.DAT A
file that contains the default values.

111.3.2

The CP/M Filer

The CPMJILER program allows the user to perform four operations:

*
*
*
*

Display a CP /M directory.
Transfer a textfile from a CP/M disk to a p-System disk.
Transfer a text file from a p-System disk to a CP/M disk.
Display a CP/M directory including all deleted entries.

III-13

Users' Manual Supplement, Version IV
New Optional Facilities

When CPMJILER is X(ecuted, the following prompt line appears:
CP/M Filer: DOr list, C(P/M to Pascal, P(ascal to CP/M, ?
Typing ''?'' displays the remainder of the CP/M filer's prompts:
CP/M Filer: E(xtnd dir list, Q(uit, H(elp, ? , IV.O (a.4]
There are six commands in the CP/M filer:
D
C
P
E
H
Q

List a CP/M directory.
Transfer a CP/M textfile to a p-System textfile.
Transfer a p-System textfile to a CP/M textfile.
Display a CP/M directory, including deleted en tries.
Display some Help text.
Quit the CP/M filer and retum to the main prompt line.

The transfer commands (C and P) use prompts that are comparable to prompts in
the standard p-System Filer. They should be self-explanatory. If you have
problems, refer to the help file by typing "H n.

111.3.3

Using Xenofile CP/M Via UCSD Pascal

To use CP/M files directly from a program, the user must be fam iHar with the
material covered in the CP/M Interface Guide by Digital Research.
The file CPM CNFIG.DA T A must be present on an on-line disk whenever a program
uses CPM FILER, CPM2 UNIT, FCPM, or BCPM. This file is created by
CPM_CNFIG-:CODE, as in preceding paragraphs.
To use the routines that access CP/M format disks, a UCSD Pascal program must
contain the following declaration.

111.3.4

The File Control Block

The first thing we will describe is the Pascal version of the file control block
(FCB). The information it contains is identical to a CP/M FeB, but it is declared
in a manner that is easily used by Pascal programs. Here is the declaration of
the FCB taken from the interface section of the unit CPM2 UNIT:

t File control block and directory types }
fde kind
III-l 4

=

Users' Manual Supplement, Version IV
New Optional Facilities

(de_char, de_data, de_blks, de_cmpt);
frec num =
O::CPM rec max; {Random record number}
fbyte_mg -= 6:.15; {Dir entry byte index range}
fword mg = 0•• 7; {Dir entry word index range}
fblks - =

record
{ fil reserves space for byte fields: }
fil: array [fword_mg] of integer;
{ xbm contains the extent's block map: }
xbm: record case Boolean of
true:
-(s: packed array [0 •• 15] of byte);
false:
array [0 .. 7] of integer);

--u:

end;
end;

fdirentry = record case fde kind of
de_char: (c: packed array-[fbyte_mg] of char);
de_data: (d: packed array [fbyte_mg] of byte);
de blks: (b: fblks);
de-cmpt: (t: array [fword mg] of Boolean);

end;
fcb

=
de
cr

rr
ov
ro
dr

record
{ Copy of current dir entry for file }
:fdirentry;
{ Current file record (next rec to R/W) }
{ Set by caller prior to R/W operation }
{ Set by CPM ops sfirst and snext to DE }
{
number oT last match, may be set by }
caller prior to a snext op, snext
}
{
advances cr before search starts
}
{
:integer;
{ Record to random read or write}
:frec num;
- { Random record overflow, reset on Open}
:Boolean;
{ Read only file, (re)set during Open }
:Boolean;
{ CPM sys drive no, set by CPM_set_fname }
:byte;

end;
The FeB is divided into the following fields:
de

Directory entry
III-IS

Users' Manual Supplement, Version IV
New Optional Facilities

cr
rr
ov
ro
dr

Current record position in the current extent
Rdomor Record position
Overflow byte from random record
Read/Only Boolean
Drive number

de: fdirentry;
This is the directory entry field. It contains the same information as a CP/M
directory, but the Pascal type fdirentry is organized as a variant record so
that the programmer can deal with the various directory fields in a number of
ways.
This is how the bytes are allocated in a CP/M directory:
Byte 0:
Bytes 1..8:
Bytes 9 ••11:
Byte 12:
Bytes 13 •• 14:
Byte 15:
Bytes 16 •• 31:

User number, must be in the range 0•• 16
Filename (ASCII characters)
File type (ASCII characters)
In the file name and file type, each character also
contains a flag bit.
F Ue exten t.
If this is greater than zero, this record is an extension
of a previous FeB.
Unused; assumed to be zero
Extent size in records (0 •• 128)
Disk allocation map

These bytes may be accessed by a Pascal program in the following way.
Assume that F is a variable of type FCB:
F.DE.C[n]
F.DE.D(n]
F .DE.B[n]
F .DE.B.S[n]
F .DE.B.L[n]
F .DE.T[n]

Allows access to the first 16 bytes as characters
Allows access to the first 16 bytes as bytes
Allows access to the second 16 bytes as either
16 bytes or 7 integers. These second 16 bytes are
the blocks allocated to th is file.
F or the byte access
F or the integer access
Allow access to the first 16 bytes as Booleans

cr: in teger;
This integer is the current record position in this extent, and is used and
maintained by the 'read' and 'write' operations. In addition, 'search first' and
'search next' use this location for holding the current directory index.

III-16

Users' Manual Supplement, Version IV
New Optional Facilities

rr: integer;
This integer is used by 'read random', 'write random', 'compute file size', and
'set random record' to maintain the current position within the file.
ov: Boolean;
This Boolean is used to indicate an overflow in a random file access.
dr: byte;
This byte is the number of the drive that contains the file. It is set by
CPM_SET_FNAME. This field is not explicitly named in CP/M: it corresponds
to the first byte of the de field in a CP/M FCB.

111.3.5

File Control Block Intrinsics

While a Pascal program may use the FCB structures directly, CPM2 UNIT also
contains five routines for handling the FCB, which are described in this section:
Function CPM SET FNAME
Function CPM-GET-FNAME
Function CPM-GET-FLAG
Procedure CPM SET FLAG
Procedure CPM-CLR FLAG

-

-

First, a note about error conditions for the functions described in this section
(and also in the following section). Each of the functions in CPM2 UNIT retums
an ioresult value. If this is zero, the function was successful. 1f this is not
zero, some error occurred. The standard error numbers are shown in the Users
Manual, Version IV.O. Three new ioresults have also been introduced:
-32
33
34

Attempt to write to a read-only file
A random read from a nonexistent record
The current record is out of range

Since the CPM2_UNIT functions retum the ioresult value, the program does not
need to turn off I/O checking in order to determine whether a call was
successful.

III-17

Users' Manual Supplement, Version IV
New Optional Facilities

Function CPM SET FNAME
(var F: FCB; NAME: string): integer;
Stores NAME into the FCB and initializes the file for opening.
This function handles all valid CP/M wild card conventions and drive
specifications. If the file name is not valid, the function returns a result .of

7.
Examples:
{ use default drive: }
RSL T : = CPM SET FNAME(F ,DDT .COM);
{ use Drive A:JRSL T : = CPM SET FNAME(F ,A:SID.COM);
{ both types of wild cards: }
RSL T := CPM_SETYNAME(F,?:W?*);

Function CPM GET FNAME
(var F: FCB; var NAME: string): integer;
This function returns the name and extent fields of the FCB as a string.
result of the functioo is AL WA YS O.
Examples:
RSL T : = CPM SET FNAME(F, 'DDT .COM');
RSL T := CPM-GET-FNAME(F ,NAME);
.COM" }
{ NAME = 7'DDTRSL T := CPM SET FNAME(F,'A:SID.COM');
RSL T : = CPM-GET- FNAME(F ,NAME);
.COM' }
{ NAME = 7'510 RSL T := CPM SET FNAME(F ,"?:W? .*');
RSL T := CPM-GET-FNAME(F ~AME);
{ NAME = ~? .???' }

III-IS

The

Users' Manual Supplement, Version IV
New Optional Facilities

Function CPM GET FLAG
(var F: FCB; FLAG: integer): Boolean;
F or each of the 11 bytes that make up the file name and file extent, bit 7 is
an attribute flag. This function returns the value of that flag. The FLAG
parameter must be in the range 1•• 11, specifying one of the 11 bytes.
These are the current CP 1M interpretations of the various flags:
1••4
5•• 8
9
10
11

undefined
undefined but reserved
file is read only
file is a System file
(not displayed by the DIR command)
undefined but reserved

Procedure CPM SET FLAG
(var F: FeB; FLAG:integer);
This procedure allows the user to set one of the flags, and is used in
conjunction with the ATTRIBUTE function (which is described in the following
section).
Example:
CPM SET FLAG(F ,9); { set the read only bit }
RSL f := -CPM(F,CPM_ATTRIB);
Procedure CPM QR FLAG
(var F: FeB; F1.AG: integer);
This procedure allows the user to clear one of the flags, and is used in
conjunction with the ATTRIBUTE function (which is described in the following
section).
Example:
CPM CLR FLAG(F ,9); (* SET READ/ONLY BIT *)
RSL f := CPM(F,CPM_ATTRIB);

III-19

Users' Manual Supplement, Version IV
New Optional Facilities

111.3.6

CP/M Interface Entry Points

In addition to the routines described above, CPM2 UNIT provides a number of
routines that can be called in ways that correspond to the entry points of the
CP 1M Interface. This section describes the way to call each entry point, in the
order given in the CP 1M Interface Guide.
F or each CP 1M Interface entry point, we show the corresponding Pascal routine
call, and two examples: a typical call from CPIM assembly language, and a typical
call from a Pascal program.
Some of the Pascal calls to CPIM Interface entry points are individual procedures,
but many of them are calls to the one function CPM. A call to CPM specifies an
FCB, and a particular operation, for example:
result: = CPM(F, CPM OPEN); {opens a file}
result: = CPM(F, CPM:CLOSE); {closes a file}
The program examples use these conventions:
F is an FCB declared as:
F: FCB;
{in Pascal}
F:
OS
36

{••• or •••}
;in assembly language

RSL T is an integer defined as follows:
RSL T: integer;
RSLT:
DB

a

in Pascal}
;in assembly language

A mbiguous is a generic name for file names and file types that can be specified

by the CP 1M wild card characters. A question mark in certain FCB fields
in dicates that any value is valid at that location, and an asterisk in a file name or
file type specification causes the field to be filled with question marks. For
example:
CPM SET FNAME(F,'A:AFILE?COM');
{:. name and attribute set to: 'AFILE? COM'}
CPM SET FNAME(F,'*.*');
••• name an d a tt rleb u t e se t t 0: '???????????'}
e e ........ .
CPM SET FNAME(F,'FILE*.*');
{:. name and attribute set to: 'FILE???????'}
CPM SET F ANME(F ,'?:THEFILE.COM');
user to '?' for search first or next }

r.: r

III-20

Users' Manual Supplement, Version IV
New Optional Facilities

As we explained above, every function in CPM2 UNIT returns an ioresult value.
This equals zero if no error occurred. The meanings of ioresult values are listed
in the Users Manual, Version IV.O. There are also three new codes:
32
33
34

attempt to write to a read only file
attempt to read a nonexistent record
current record is out of range

Finally, CP/M uses the term "vector" to refer to an array of bits. In CPM2 UNIT,
a'l1 vectors are declared as sets. These include ORV VECTOR, RO VECTOR, and
the ALLOC_VECTOR. We will discuss them where necessary.
-

FUNCTION 12:

Retum the version number

Pascal definition:

Function CPM VER NUMBER: integer;
Returns the version number.
This returns the current version of CPM2 UNIT. To be
returns a value of greater than 020h (32 decimal)
Because this is compatible with version 2.x, it means
random access.
Note that currently all of the
implemented except function 31: Get disk parameters.

compatible with CP/M, it
but less than 100h (256).
that CPM2 UNIT supports
CP/M 2.x -functions are

CP 1M Example:
;RETURN
;NUMBER
MVI
CALL
ST A

THE CPM VERSION
C,12
BOOS
VER$NUMBER

Pascal Example:

1II-21

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 13:

Res~t

the disk system

Pascal definition:

Procedure CPM_DSKJRESET;
This procedure resets CPM2_UNIT's values to a known state:
1) All disks are set to read/write
2) Drive A: becomes the default drive
3) The default buffer becomes the current buffer
CP /M example:
;RESET THE BOOS
MVI
C,13
CALL
BOOS
Pascal example:

FUNCTION 14:

Select disk

Pascal definition:

Function CPM_SELECT (DRIVE: integer): integer;
Returns the error status.
This function selects DRIVE as the new default drive.
All subsequent disk
operations where the dr field of the FCB is zero refer to this drive. Note that
this function DOES retum an error status, though CP/M itself does not.
CP /M example:
;SELECT A NEW DEF ALL T DRIVE
MVI
E,DRIVE
;E = NEW DRIVE
CALL
C,14
CALL
BOOS
;NO ERRORS

III-22

Users' Manual Supplement, Version IV
New Optional F acili ties

Pascal example:
RSL T : = CPM SELECT(ORIVE);
IF RSL T <> 0 THEN
(* error *)

FUNCTION 15:

Open file(s)

Pascal definition:
CPM (F, CPM_OPEN)
Returns the error status.
This function activates an existing file in the directory of the currently active
user. The file name and file type may be ambiguous ('?'). Normally there are no
question marks.
NOTE:

The directory code is not retumed as in CP 1M.

CP 1M example:

F:

LXI
MVI
CALL
CPI
JNZ

O,F
C,15
BOOS
OFFH

OK

DB
OS

O,"AFILE
20

;JUMP IF NO ERRORS
COM ",0,0,0,0

Pascal example:
RSL T : = CPM SET FNAME(F ,'AFILE.COM');
IF RSL T <> a THEN
(* BAD FILE NAME *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM OPEN);
THEN IF RSL T <>
(* FILE DOES NOT EXIST *)
END;

°

III-23

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 16:

Close file

Pascal definition:
CPM (F, CPM_QOSE)
Returns the error status.
This function closes a file that was previously opened by a CPM _OPEN or
CPM MAKE operation. The file name and type are matched as with CPM OPEN
(See preceding Pascal example).
Files opened only for reading do not need to be closed, but a file that was also
written must be closed in order to update the directory.
NOTE:

The directory index is not retumed, as it would be under CP 1M.

CP1M example:

D,F

LXI
MVI
CALL
CPI
JNZ
DB

F:

C,16
BOOS
OFFH
OK
O,"AFILE

;JUMP IF NO ERRORS
COM",O,O,O,O

Pascal example:
RSL T : = CPM(F ,CPM CLOSE);
IF RSL T <>
THEN (* COLLO NOT CLOSE *)

°

FUNCTION 17:

Search for first

Pascal definition:
CPM (F, CPM_SFIRST)
Retums the error status.
This function searches the directory for a file that matches the FeB. If a match
is found, the directory entry is retumed in CPM_F, a global FeB used by search
first and search next for the purpose of retuming directory entries.

III-24

Users' Manual Supplement, Version IV
New Optional Facilities

NOTE: This is very different from the way CP/M operates, but the net result is
the same.
The FCB may contain ambiguous references as in open, but in addition byte zero
of the FCB may be a question mark ('?' = 63). If byte zero is a question mark,
then the auto select function is disabled, the default disk is searched and every
directory en try is checked, regardless of whether it is deleted or not, or which
user number it belongs to.
NOTE: Byte zero may be set to a question mark by using CPM SET FNAME with
the drive specification a question mark, as in the example below. This allows a
program to interrogate every directory entry when used in conjunction with
function 18, search next.
CP/M example: look at each of the entries in the directory.
;SET DMA ADDRESS
LXI
D,DIRBUF
MVI
C,26
CALL
BOOS
;LOOK FOR FIRST ENTRY
LXI
D,F
MVI
C,17
CALL
BOOS
CPI
OFFH
JZ
NOMATCH

;SET DMA ADDRESS
; TO DIRBLF

;JUMP IF NO ENTRY

;LOOK AT ENTRY WHICH IS IN DIRBUF[A*32] ••••
LOOK:
;SEARCH
LXI
MVI
CALL
CPI
JNZ

THE NEXT ENTRY
D,F
C,18
BOOS
OFFH
LOOK

;JUMP IF FOUND

NOMATCH:
;EXIT

F:

DB
OS
DIRBUF:

'?','???????????', '?', '?', '?',O
20
OS
128

III-25

Users' Manual Supplement, Version IV
New Optional Facilities

Pascal example:
RSL T := CPM SET FNAME('?:*.*);
(* USER AND NAME AND TYPE
IF RSL T <> 0 THEN
(* ERROR *)
ELSE
BEGIN
FOR I : = 12 TO 14 DO
FCB.DE.Cn] : = '?'; (* SET EX,SI,S2 TO '?' *)
RSL T := CPM(F,CPM SFIRST);
WHILE RSL T = 0 00BEGIN
(* LOOK AT DIRECTORY IN CPM F *)
FOR I : = 1 TO 8 DO
WRITE(CPM F .DE.C[I]);
WRITE('.');
FOR I : = 9 TO 11 00
WRITELN(CPM_F .DE.C[I];

= '?'

*)

(* SEARCH FOR THE NEXT MATCH *)
RSL T : = CPM(F ,CPM SNEXT);
END;
END;
FUNCTION 18:

Search for next

Pascal definition:
CPM (F, CPM_SNEXT)
Returns the error status.
This function searches the directory for a file that matches the FCB, starting from
the directory entry in F .CR + 1. Normally, the cr field is set by search first as
in the preceding example. search next is simply a continuation of search first,
and operates in the same manner. If a match is found, the directory entry is
returned in CPM F as in search first.
Please refer to search first (function 17) for an example.

III-26

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 19:

Delete file

Pascal definition:
CPM (F, CPM_DELETE)
Returns the error status.
This function deletes a file entry from the directory.
ambiguous.

The name or type may be

CP 1M example:
D,F
JOE = FCB ADDRESS
C,19
SDOS
;DELETE THE FILE
OFFH
NOT$DELETED
;JUMP IF UNSUCCESSFlL
0, "AFILE
COM ",0,0,0,0

LXI
MVI
CALL
CPI

F:

JZ

DB

Pascal example:
RSL T : = CPM SET FNAME(F,'AFILE.COM');
IF RSL T <> THEN
(* ERROR *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM DELETE);
IF RSL T <> 0 THEN (* ERROR *)
END;

°

FUNCTION 20:

Read a file sequentially

Pascal definition:
CPM (F, CPM_ROSEQ)
Returns the error status.
This function reads one record from the file, at the position defined by F .CR, into
the buffer pointed to by CPM BLFF. The CR field is then incremented. If the
CR field overflows, the next extent in the directory is automatically opened and
the CR field is set to O.

111-27

Users' Manual Supplement, Version IV
New Optional Facilities

NOTE: If an attempt is made to read past the end of the file, the function returns
an ioresult of 33 (record does not exist) to signify end of file.
CP/M example: Read the contents of a file.
;OPEN THE FILE
LXI
O,F
MVI
C,lS
CALL
SOOS
CPI
OFFH
JZ
ERROR
;SET THE
LXI
MVI
CALL

;JUMP IF UNABLE TO OPEN

OMA ADDRESS
O,BLFFER
C,26
BOOS

;REAO THE FILE
ROLOOP:
.
O,F
LXI
MVI
C,20
CALL
BOOS
CPI
a
JNZ
ERROR

;REAO NEXT RECORD
;JUMP IF END OF FILE

;00 SOMETHING
JMP
DB

F:

RDLOOP
O,"AFILE

",0,0,0,0

Pascal example:
RSL T : = CPM SET FNAME(F,' AFILE');
IF RSL T <> a THEN
(* ERROR *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM OPEN);
IF RSL T <> a THEN (* ERROR *)
ELSE
BEGIN
NEW(CPM BLFF); (* ALLOCATE A BLFFER *)
REPEAT RSL T : = CPM(F ,CPM RDSEQ);
IF RSL T <>
THEN -

°

1II-28

Users' Manual Supplement, Version IV
New Optional Facilities

(* ERROR *)
ELSE
(* DO SOMETHING *)
UNTIL RSL T <> 0;
END;

END;

FUNCTION 21:

Write a file sequentially

Pascal definition:
CPM (F, CPM_ WRSEQ)
Retums the error status.
This function writes one record to the file, at the position defined by F .CR, from
the buffer pointed to by CPM BLFF. The CR field is then incremented. If the
CR field overflows, the next extent in the directory is automatically opened, or
made, and the CR field is set to O.
CP 1M example: Write a record to a new file
;OPEN THE FILE
LXI
D,F
MVI
C,22
CALL
BOOS
CPI
OFFH
JZ
ERROR
;SET THE
LXI
MVI
. CALL

;JUMP IF UNABLE TO MAKE

DMA ADDRESS
D,BLFFER
C,26
BOOS

;WRITE TO THE FILE
LXI
O,F
MVI
C,21
CALL
BOOS
CPI
0
JNZ
ERROR

;WRITE THE RECORD
;JUMP IF ERROR

;CLOSE THE FILE
LXI
D,F
MVI
C,16
CALL
BOOS
1II-29

Users' Manual Supplement, Version IV
New Optional Facilities

CPI

OFFH
ERROR
O,'NEWFILE

JZ
08

F:

;JUMP IF ERROR
",0,0,0,0

Pascal example:
RSL T : = CPM SET FNAME(F, 'NEWFILE");
IF RSL T <> THEN
(* ERROR *)
ELSE
BEGIN
RSL T := CPM(F,CPM MAKE);
THEN IF RSL T <>
(* ERROR *)
ELSE
BEGIN
NEW(CPM BLFF); (* ALLOCA TEA BUFFER *)
RSL T := CPM(F,CPM WRSEQ);
IF RSL T <> 0 THEN (* ERROR *)
RSL T : = CPM(F ,CPM CLOSE);
IF RSL T <>
THEN (* ERROR *)
END;
END;

°

°

°

FUNCTION 22:

Make a new file

Pascal definition:
CPM (F, CPM_MAKE)

Returns the error status.
This function creates a new file entry in the directory, and opens the file. The
file name must be unambiguous, and cannot already be in use. The program may
ensure this by performing an open operation before the make.
CP1M example:
;CHECK OPEN TO CHECK FOR DUPLICATE FILE
LXI
D,F
MVI
C,lS
CALL
800S
;OPEN
CPI
OFFH
III-30

Users' Manual Supplement, Version IV
New Optional Facilities

F:

JNZ

MAKEIT

;JUMP IF DOES NOT EXIST

;DELETE
LXI
MVI
CALL
CPI
JZ

O,F
C,19
BOOS
OFFH
ERROR

;DELETE

;MAKE THE FILE
MAKEIT:
LXI
D,F
MVI
C,22
BOOS
CALL
CPI
OFFH
JZ
ERROR
DB
O,'NEWFILE

;SHOlLO NOT HAPPEN
; UNLESS MEDIA ERROR

;MAKE
",0,0,0,0

Pascal example:
RSL T : = CPM SET FNAME(F, 'NEWFILE');
IF RSL T <> a THEN
(* ERROR *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM OPEN);
IF RSL T <> a THEN (* ERROR *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM DELETE);
THEN IF RSL T <>
EXITC); (* ERROR bomb off *)
END;
RSL T := CPM(F,CPM MAKE);
IF RSL T <>
THEN (* ERROR *)
END;

°

°

111-31

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 23:

Rename file

Pascal definition:

Function CPM RENAME (F, S: string):integer;
Returns the error status.
This function renames a file in the directory. The names are assumed to be
unambiguous. To rename a file, first use CPM SET FNAME to set up F with the
old name, then call CPM RENAME with the new-name.
CP/M example:
LXI
MVI
CALL
JZ

O,F
C,23
BOOS
OFFH
ERROR

.DB
.DB

O,"OLOFILE
0, ''NEWFILE

cpr

F:

;RENAME
;JUMP IF ERROR

",0,0,0,0
",0,0,0,0

Pascal example:
RSL T := CPM SET FNAME(F,'OLDFILE');
IF RSL T <> THEN
(* ERROR *)
ELSE
BEGIN
RSL T := CPM RENAME(F,'NEWFILE');
IF RSL T <> THEN
(* ERROR *)
END

°

°

111-32

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 24:

Return login vector

Pascal definition:

Procedure CPM GET DRIVES
(var DRV_VECTOR: BIT_VEC);
This procedure returns in DRV _VECTOR a set of 16 elements numbered 0 •• 15.
Each element corresponds to one of the 16 possible drives and is in the set if that
drive is currently logged in.
CP/M example: Is drive a logged in?
MVI
CALL
MOV
RRC
JCC

C,24
BOOS
A,L
NOT$LOGGED

;MOVE BIT a TO CARRY
;JUMP IF NOT LOGGED IN

Pascal example:
CPM GET DRIVES(DRV VECTOR);
IF OIN D-RV VECTOR THEN
(* DO SO METHING *)

FUNCTION 25:

Return curren t disk

Pascal definition:

Function CPM GET OS K: in teger;
Returns the current disk number.
This function returns the number of the currently selected disk.
When an
operation is done and F .DR equals zero, then the currently selected disk is the one
that the operation affects.
The number returned is in the range 0•• 15, corresponding to the drive names A: ••
P:.
CP /M example:
MVI
CALL

C,25
BOOS

111-33

Users' Manual Supplement, Version IV
New Optional Facilities

STA

CUR$DSK

Pascal example:

FUNCTION 26:

Set DMA address

Pascal definition:
CPM BLFF := CPM_BUFFP;
This variable defined in the INTERFACE section of CPM2 UNIT is a pointer to a
buffer where the next file operation will take place. - At initialization time,
CPM BUFF points to a default buffer new'ed onto the heap. Also, CPM_BLFF is
set back to CPM_ BLFF_DFL T during CPM_RESET.
NOTE: CPM BUFF DFL T is also a variable defined in the interface section of
CPM2_LNIT, and the user may set CPM_BLFF equal to it at any time.
CP 1M example:
LXI
MVI
CALL

D,NEWBLFFER
C,26
BOOS

Pascal example:
NEW(NEWBUFFER);
CPM BLFF := NEWBUFFER;

FUNCTION 27:

Get allocation vector

Pascal definition:

procedure CPM_GET~LLOC
(var ALLOC_VECTOR: BLK_VEC);
This procedure returns a set that contains all currently available blocks on the
disk.

III-34

Users' Manual Supplement, Version IV
New Optional Facilities

NOT E: I f the currently selected disk is write protected, then the allocation map is
invalid. This procedure is not normally used by applications programs.
CP /M example:
MVI
CALL
SHLD

C,27
BOOS
ALLOC$ADR

;STORE ADDRESS OF VECTOR

Pascal example:

FUNCTION 28:

'Write protect disk

Pascal definition:
procedure CPM_ WP (DRIVE: integer);
This procedure write protects the specified drive. The number passed must be in
the range 0 •• 15. All subsequent attempts to write to that disk cause the function
to return an ioresult of 16.
CP/M example: write protect drive B:
;SELECT DRIVE B
MVI
E,l
MVI
C,14
BOOS
CALL
MVI
C,28
BOOS
CALL

;SELECT DRIVE B
;WRITE PROTECT

Pascal example:

1II-35

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 29:

Get read/only vector

Pascal definition:

This procedure returns a set with 16 (0 •• 15) elements: these indicate which disk
dri ves are currently marked as read-only. A file may be write protected explicitly
by a call to CPM_WP, or CPM2_UNIT may automatically declare a drive as write
protected if the medium was changed without the drive being logged in.
CP/M example: Is drive A: read only?
MVI
CALL
MOV
RRC
JNC

C,29
BOOS
A,L
NOT$RO

;BIT 0 TO CARRY
;JUMP IF BIT = 0

Pascal example:
CPM GET RO(oRV VECTOR);
IF OIN O-RV VECTOR THEN
(* IS READ ONLY *)

FUNCTION 30:

Set file attributes

Pascal definition:
CPM (F, CPM_A TTRIB)
Returns the error result.
T his fun c t ion i sus e d 'w it h the new pro c e d u res C P M SET F LAG and
CPM CL R FL AG described above. They allow the programmer to alter the bit
flags- maintained in bit 7 of the 11 file name and file type bytes in a directory
entry. The file name and file type must not be ambiguous.
CP/M example: Set a file to read-only

III-36

LXI
LXI
DAD

o,F
H,9

MOV

A,M

o

;HL POINTS AT THE
; TYPE BYTE

Users' Manual Supplement, Version IV
New Optional Facilities

F:

ORI
MOV
MVI
CALL

080H
M,A
C,30
BOOS

DB

O,'AFILE
20

DB

;SET BIT 7 OF TYPE BYTE 1
;CALL BOOS TO SET
; THE ATTRIBUTE
',0,0,0,0

Pascal example:
RSL T := CPM SET FNAME(F,'AFILE');
IF RSL T <> THEN
(* ERROR *)
ELSE
BEGIN
CPM SET FLAG(F ,9);
RSL f : =-CPM(F ,CPM ATTRIB);
IF RSL T <> 0 THEN (* ERROR *)
END;

°

FUNCTION 31:

Get disk parameters

NOT IMPLEMENTED

FUNCTION 32:

Set/get user code

Pascal definition:

This is a variable defined in the interface section of CPM2 UNIT. This variable
defines which user is currently valid when searching the directory for matches to
an FCB.
.
CP 1M example: Set the user code to 15
MVI
MVI
CALL

E,15
C,32
BOOS

IU-37

Users' Manual Supplement, Version IV
New Optional Facilities

Pascal example:
CPM USER : = 15;
CP 1M example: Get the current user code
MVI
MVI
CALL
STA

E,OFFH
C,32
BOOS
CURR$USER

Pasc al example:
CURR USER : = CPM_USER;

FUNCTION 33:

Read random

Pascal definition:
CPM (F, CPM_RORNO)
Returns the error result.
This function reads a random record from a file. The RR field in the FCB must
have been set to the desired record number. If the data is in the file, the result
returned is zero, and the data are stored at the current OMA address pointed to
by CPM_BLFF. If there is currently no data at that position, the function returns
a 33.
If upon returning from the function the OV field of the FCB is true, then the RR
field was too large and the function returns a result of 8.
NOTE: Sequential reads may be commenced from this point, but since random
reading does not automatically increment the RC field in the FCB, the current
record is reread. The user may simulate sequential reading by simply incrementing
the RR field and calling this function.
CP 1M example: Read record 1000.
;ASSUME THE FILE IS ALREADY OPEN
;SET RO,Rl,R2 TO 1000
LXI
H,F
LXI
0,33
DAD
0
;HL POINTS TO RO
LXI
0,1000
III-38

Users' Manual Supplement, Version IV
New Optional Facilities

MOV
INX
MOV
INX
MVI

M,E

;STORE RO

H

M,O

;STORE Rl

H

M,O

;ZERO R2

;SET DMA ADDRESS
LXI
O,BUFFER
MVI
C,26
CALL
BOOS
;REAO THE RECORD
LXI
O,F
MVI
C,33
BOOS
CALL
CPI
a
JNZ
ERROR

;JUMP IF ERROR

Pascal example:
F .RR : = 1000;

CPM BLFF := BLFFER;
RSL f : = CPM(F ,CPM RDRNO);
IF RsL T <> a THEN (* ERROR *)
FUNCTION 34:

Write random

Pascal definition:
CPM (F, CPM_WRRND)
Returns the error result.
This function writes a random record to a file. The RR field in the FCB must be
set to the desired record number. The file is automatically extended as
neccessary to accommodate this record, as long as there is room on the disk and
in the directory.
If upon returning from the function, the OV field of the FCB is true, then the RR
field was too large, and the function restums a result of 8.

III-39

Users' Manual Supplement, Version IV
New Optional F acili ties

NOTE: As in random reading, sequential writing is allowed following a random
wri te, but since the RR field is not incremented after a random write, the first
sequential write will be to the current position. Sequential writing may be
simulated by explicitly incrementing the RR field.
CP 1M example: Wri te record 1000.
;ASSUME THE FILE IS ALREADY OPEN
;SET RO,Rl,R2 TO 1000
LXI
H,F
LXI
0,33
DAD
0
;HL POINTS TO RO
LXI
0,1000
MOV
M,E
;STORE RO
INX
H
MOV
M,D
;STORE Rl
INX
H
MVI
M,O
;ZERO R2
;SET DMA ADDRESS
LXI
D,BLFFER
MVI
C,26
CALL
BOOS
;WRITE THE RECORD
LXI
O,F
MVI
C,34
CALL
BOOS
CPI
a
JNZ
ERROR
Pascal example:
F .RR : = 1000;
CPM BLFF := BUFFER;
RSL f : = CPM(F ,CPM WRRNo);
IF RSL T <> a THEN (* ERROR *)

III-40

;JUMP IF ERROR

Users' Manual Supplement, Version IV
New Optional Facilities

FUNCTION 35:

Compute file size

Pascal defintion:
CPM (F, CPMY-SIZE)
Returns the error result.
This function computes the size of a file and returns the size in the RR field of
the FCB. The file name and type must not be ambiguous. If the file is too large
then the OV field will be set to true, and the function returns an 8.
CP 1M example:

F:

LXI
MVI
CALL

D,F
C,35
BOOS

DB

0, "AFILE

;NO ERRORS IN CP/M THE
; BOOS BOMBS
",0,0,0,0

Pascal example:
RSL T := CPM SET FNAME(F,'AFILE');
IF RSL T <> THEN
(* ERROR *)
ELSE
BEGIN
RSL T : = CPM(F ,CPM FSIZE);
IF RSL T <>
THEN (* ERROR *)
END;

°

°

FUNCTION 36:

Set random record

Pascal defintion:
CPM (F, CPM_SETRR)
Returns the error result.
This function sets the RR field of the FCB to the current random record position
of a file which is already open. This allows the caller to save the current
posi t i on in the file for later access by a random read or write. If the file is too
large, then the OV field will be true, and the function returns an 8.

III-41

Users' Manual Supplement, Version IV
New Optional Facilities

CP1M example:
;ASSUME
LXI
MVI
CALL

THE FILE IS OPEN
O,F
C,36
BOOS

Pascal example:
(* ASSUME THE FILE IS OPEN *)
RSL T : = CPM(F ,CPM SETRR);
IF RSL T <> 0 THEN (* ERROR *)

111-42

;NO ERRORS

Users' Manual Supplement, Version IV
New Optional F acili ties

111.3.7

Summary: CP/M Interface -

Calls to CPM2_UNIT

The following table is a quick summary of the correspondence between CP/M
BOOS calls 12 through 36, and CPM2_UNIT calls:
Call /I

CP/M Call Seguence

12

;RETURN
;NUMBER
MVI
CALL
ST A

13

;RESET THE BOOS
MVI
C,13
BOOS
CALL

CPM_OSK_RESET;

14

;SELECT A NEW OEF AUL T
;ORIVE
MVI
E,ORIVE
C,14
CALL
CALL
BOOS

RSL T : = CPM_SELECT(ORIVE:INTEGER);

15

16

17

p-System Seguence

THE CPM VERSION
C,12
BOOS
VER$NUMBER

;FILE OPEN
LXI
O,F
MVI
C,15
CALL
BOOS
;FILE CLOSE
LXI
O,F
MVI
C,16
CALL
BOOS
;SEARCH FOR FIRST
;OCCURRENCE OF FILE(s)
O,F
LXI
MVI
C,17
CALL
BOOS

VER NUMBER := CPM_VER_NUMBER;

RSL T : = CPM(F ,CPM_OPEN);

RSL T : = CPM(F ,CPM_CLOSE);

RSL T : = CPM(F ,CPM.fIRST);

1II-43

Users' Manual Supplement, Version IV
New Optional F acili ties

18

19

20

21

22

23

24

In-44

;SEARCH FOR NEXT
;OCCURRENCE OF FILE(s)
O,F
LXI
MVI
C,18
CALL
BOOS
;FILE DELETE
LXI
O,F
MVI
C,19
BOOS
CALL
;REAO SEQUENTIAL
LXI
O,F
MVI
C,20
CALL
SOOS
;WRITE SEQUENTIAL
LXI
O,F
MVI
C,21
CALL
8005
;FILE MAKE
D,F
LXI
MVI
C,22
CALL
BOOS
;FILE RENAME
O,F
LXI
MVI
C,23
CALL
SOOS
;RETURN
MVI
CALL
SHLO

LOGIN VECTOR
C,24
BOOS
LOGIN

RSL T : = CPM(F ,CPMYJEXT);

RSL T : = CPM(F ,CPM_OELETE);

RSLT := CPM(F,CPM_ROSEQ);

RSLT : = CPM(F ,CPM_WRSEQ);

RSL T : = CPM(F ,CPM_MAKE);

RSL T : = CPM(F ,CPM_RENAME);

CPM_ GET_ ORIVES(LOGIN);

Users' Manual Supplement, Version IV
New Optional Facilities

25

;RETURN CURRENT OISK
MVI
C,25
CALL
BOOS
STA
CURR$OISK

CURR DISK: = CPM_GET_DSK;

26

;SET ADDRESS OF NEXT I/O
;OPERATION
LXI
D,BUFF
NEW(CPM_BUFF);
MVI
C,26
or
CALL
BOOS
CPM BUFF : = BUFF~DDRESS;

27

;GET THE ALLOCATION MAP FOR
;THE CURRENT DEFAULT DISK
MVI
C,27
CPM GET ALLOC(ALLOC);
CALL
BOOS
AtLOC$ADR
SHLD

28

29

30

;WRITE PROTECT CURRENT
;oISK
MVI
E,DISK
MVI
C,14
CALL
BOOS
MVI
C,28
CALL
BOOS
;GET READ/ONLY VECTOR
MVI
C,29
CALL
BOOS
SHLD
RO$oRIVES
;SET FILE ATTRIBUTES
MVI
C,30
CALL
BOOS

CPM_WP(DISK);

CPM_GET_RO(RO_ORIVES);

RSL T : = CPM(F ,CPM~ TTRIB);

III .. 45

Users' Manual Supplement, Version IV
New Optional F acili ties

31

;GET DISK PARMS
MVI
C,31
CALL
BOOS

NOT SUPPORTED

32

;SET/GET
;SET
MVI
MVI
CALL

E,15
C,32
BOOS

CPM USER := 15

; GET
MVI
MVI
CALL

E,CFFH
C,32
BOOS

USER := CPM USER

33

34

35

36

In-46

USER CODE

;READ RANDOM
LXI
D,F
MVI
C,33
BOOS
CALL
;WRITE RANDOM
LXI
D,F
MVI
C,34
BOOS
CALL
;COMPUTE FILE SIZE
LXI
D,F
MVI
C,35
BOOS
CALL
;SET RANDOM RECORD
LXI
D,F
MVI
C,36
BOOS
CALL

RSLT := CPM(F,CPM_RDRND);

RSL T : = CPM(F ,CPM_WRRND);

RSL T : = CPM(F ,CPMY-SIZE);

RSL T : = CPM(F ,CPM_SETRR);

Users' Manual Supplement, Version IV
New Optional Facilities

111.3.8

FORTRAN Interface to CP/M XenoFile

This section explains how p-System FORTRAN programs can access CP/M disks.
The user must be familiar with the information in this supplement and the CP/M
In terface Guide.
A FORTRAN program invokes XenoFile by using the unit FCPM. This unit should
be installed in *SYSTEM.LIBRARY so that it can be found during compilation and
execution. The FORTRAN program must then include the directive "$USES FCPM"
in order to use the routines provided by FCPM. Since all of the routines,
in cluding all of the integer functions in FCPM, start with the letter "C", it is also
desirable to include the statement ''IMPLICIT INTEGER (C)" in the FORTRAN
program.
A correspondence between CP /M BOOS calls 12 through 36 and FCPM calls
follows:
Call II

FORTRAN p-System sequence

Description

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

RSL T = CPM120
CALL CPM13
RSLT = CPM14(DRIVE)
RSLT = CPMI(F,15)
RSLT = CPMI(F,16)
RSLT = CPMI(F,17)
RSLT = CPMI(F,18)
RSLT = CPMI(F ,19)
RSLT = CPMI(F,20)
RSLT = CPMI(F,21)
RSLT = CPMI(F,22)
RSLT = CPM23(F ,NAME)
CALL CPM24(LOGVEC)
RSL T = CPM25()
CALL CPM26G(B)
CALL CPM26P(B)
CALL CPM27(ALL VEC)
CALL CPM28(DRIVE)
CALL CPM29(RODVEC)
RSL T = CPMI(F ,30)
NOT SUPPORTED
RSL T = CPM32GO
CALL CPM32S(USRNUM)
RSLT = CPMI(F ,33)
RSLT = CPMI(F,34)
RSLT = CPMI(F ,35)
RSLT = CPMI(F,36)

Return the version number
Reset the disk system
Select disk
Open file
Close file
Search for first
Search for next
Delete file
Read a file sequentially
Write a file sequentially
Make a new file
Rename file
Return login vector
Return curren t disk
Get CPM buffer
Put CPM buffer
Get allocation vector
Write protect disk
Get read/only vector
Set file attributes

27
28
29
30
31
32
33
34
35
36

Get user code
Set user code
Read random
Write random
Compute file size
Set random record
1II-47

Users' Manual Supplement, Version IV
New Optional Facilities

The following additional FORTRAN calls with no corresponding CP/M BOOS
function calls are also available through FCPM:
CALL
CALL
RSL T
CALL
CALL
CALL
RSL T
CALL
RSL T
CALL
RSL T
CALL
RSL T

CPMSFN(F ,NAME)
CPMGFN(F ,NAME)
= CPMGFL(F,FLAG)
CPMSFL(F ,FLAG)
CPMCFL(F ,FLAG)
CPMFCB(G)
= CPMGE(F)
CPMSE(F ,EXTENT)
= CPMGCR(F)
CPMSCR(F ,CRNUM)
= CPMGRR(F)
CPMSRR(F ,RRNUM)
CPMGB(B,BYTNUM)

=

CALL CPMSB(B,BYTNUM,VALUE)

Set file name
Get file name
Get attribute flag
Set attribute flag to 1
Clear attribute flag to 0
Get FCBfor calls 17 & 18
Get file extent number
Set file extent number
Get current record number
Set current record number
Get random record number
Set random record number
Get byte out of buffer
(Used after calling CPM26G)
Set byte in buffer
(Used before calling CPM26P)

The following items define the arguments for the preceding calls.
RSL T.
DRIVE.

An integer value returned by the function.
An integer (0 •• 15) corresponding to CP/M drives A•• P.

F. A 21-element integer array corresponding roughly to the CP/M FCB. F should
be initialized to zeros. The order of the fields in the FCB is irrelevant, since
routines are provided that can access the important fields.
NAME. A 14-element character array corresponding to a CP/M file name
specification (with or without wild cards).
LOGVEC. A 16-element integer array with values (0 or 1), where values of 1
correspond to the drives that have been logged in.
ALL VEC. An integer array with values (0 or 1), where values of 1 correspond to
blocks that have been allocated; the number of elements in the array correspond to
the number of blocks per disk.
RODVEC. A 16-element integer array with values (0 or 1) where values of 1
correspond to the drives that have been write protected (read only drives).
USRNUM.
care".
III-48

An integer with values 0 through 15, 63 for

"?", or 255 for "don't

Users' Manual Supplement, Version IV
New Optional Facilities

FLAG.
bitsei.
EXTENT.

An integer from 1 to 11 corresponding to one of the CP/M attribute
An integer with values 0 •• 255 or 63 for "?".

CRNUM. An integer corresponding to the desired current record number for a file
being accessed sequentially.
RRNUM. An integer corresponding to the desired random record number for a file
being accessed randomly.
B. An integer array large enough to contain the CP/M buffer (byte array); this
local buffer is necessary since the CPM buffer cannot be directly accessed from a
FORTRAN program.
B YTNUM. An integer from 1 to twice the local buffer size, which is the desired
byte index into the CP/M buffer.

VALUE.

An integer from 0 through 255 (i.e., a byte value).

G. A 21-element integer array corresponding roughly to a special CP/M FCB that
is used during directory searches; G should be initialized to zeros.

EXAMPLE -- FORTRAN Program Using FCPM
$L.JSES FCPM
PRCXR.AJv1 [ENG
INPLICIT INTEGER (C)
C
C This progrrun serves principally as a demonstration of how some of
C the more useful routines in the FCAM unit are inVOked.
CAt the same time, i t a c c amp lis he s the f a I 1 ow i n g :
1)
copies the first 10 records of FILEl to FILE2
C
C
using sequential reads and writes.
C
2)
closes and reopens FILE2 and co~utes its size so
C
that more records can be appended.
C
3)
sets the random record nu~er for FILEI to the current
C
record and copies the remainder of the records using
C
random reads and writes.
C NOTE:
In order to simplify the demonstration, very few
C
error checks are included.
C WARN I f\G : 1 f t h e s p e c i fie d 0 u t put f i 1e aIr e ad y e xis t s, i t i s
C
deleted by this demonstration program.
C
INTEGER RSLT1RRNUM,~
III-49

Users' Manual Supplement, Version IV
New Optional Facilities

F(21),F2(21)
INTEGER B(S12)
D-iARACTER* 14 NAIVE
C Initialize FCB arrays with zeros
00 1000 I = 1,21
F(I) = a
1000 F2(1) = a
\hR. I TE ( * , 100) , En t e r FILE 1 n arne :
READ ( *,200) NAtv'E
C Set FILE1 name specification in the FCB
RSLT = CPtv1SFN(F,NANE)
COpen FILE1
RSLT = CRMI(F,15)
WR.ITE(*,100) 'Enter FILE2 name: .
RtAD ( * , 2 a0) N.AlvE
C Set FILE2 name specification in the FCB
RSLT = CPNSFN(F2,NANE)
COpen FILE2 - delete it if it already exists
RSL T = CPMI (F2, IS)
IF (RSLT .NE. 0) GOTO 20
C Delete FILE2
'
RSLT = CRMI(F2,19)
C Make (create) FILE2
20 RSLT = CAM I (F2,22)
C Set current record numbers to zeros for FILEl & FILE2
CALL CPtv1SCR (F , 0)
CALL CPN5CR(F2,0)
00 2000 I = 1,10
C Read record from FILE1 sequentially
RSLT = CRMI(F,20)
IF (RSLT .NE. 0) GOTO 40
C Write record to FILE2 sequentially
2000 RSLT = CRMI(F2,21)
C Close and re-open FILE2
RSLT = CAM I (F2,16)
RSLT = CAMI(F2,15)
C Compute size of FILE2
RSLT = CPMI(F2,35)
C Save random record nurrber for FILE2
I~EGER

RRN..M2

C
C

RRN..M

C

= CRvrnR (F 2 )

.

Set random record nurrber for FILE1 to current record
RSLT = CRMI(F,36)
Save random record nurrber for FILE1

= CRvrnR ( F )

Read record from FILE1randomly
30 RSLT = CAMI(F,33)

III~SO

Users' Manual Supplement, Version IV
New Optional Facilities

IF (RSLT .NE. 0) GOTO 40
Get CAM buffer
CALL CPI'v126G(B)
CAt t his poi n t the b u f fer c 0 u 1 d bee x am i ned and mo d i fie d
C Put CAM buffer
CALL CAM26P(B)
C Write record to FILE2 randomly
RSLT = CAM I (F2,34)
RRJ\l...M = RRJ\l...M + 1
RRJ\l...Ml = RRJ\l...M2 + 1
C Set random record numbers for FILEI & FILE2 to next records
CALL CPMSRR (F , RRJ\l...M)
CALL CPfv1SRR(F2 ,RRJ\l...M2)
CDTO 30
C Close FILEI & FILE2
40 RSLT = CPMI(F,16)
RSLT
CAMI(F2,16)
100 F~T(A )
150 F~T(A)
200 F~T(A14)

C

=

999 END

111.3.9

BASIC Interface to CP/M XenoFile

This section explains how p-System BASIC programs access CP/M disks. The user
must have read and understood the preceding information in this manual as well
as the CP/M In terface Guide.
A BASIC program invokes XenoFile by using the unit BCPM. This unit should be
installed in *SYSTEM.LIBRARY so that it can be found during compilation and
execution. The BASIC program must then include the directive "USES BCPM" in
order to use the routines provided by BCPM.
NOTE: BCPM expects BASIC programs to pass only element one of an integer
array argumen t.

III-51

Users' Manual Supplement, Version IV
New Optional Facilities

The following listing is an example of correspondence between CP/M BOOS calls 12
through 36 and BCPM callsx.
Call 11

BASIC p-System sequence

Description

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

RSL T = CPM120
RSCALL CPM13
RSLT = CPM14(DRIVE)
RSLT = CPMI(F(I),15)
RSLT = CPMI(F(1),16)
RSLT = CPMI(F(I),17)
RSLT = CPMI(F(I),18)
RSLT = CPMI(F(1),19)
RSLT = CP MI(F (1 ),20)
RSLT = CPMI(F(I),21)
RSLT = CPMI(F(I),22)
RSLT = CPM23(F(I),NAME$)
CALL CPM24(LOGVEC(I))
RSL T = CPM250
CALL CPM26G(B(I))
CALL CPM26P(B(I))
CALL CPM27(ALL VEC(I))
CALL CPM28(DRIVE)
CALL CPM29(RODVEC(I))
RSL T = CPMI(F(I),30)
NOT SUPPORTED
RSL T = CPM32GO
CALL CPM32S(USRNUM)
RSLT = CPMI(F(I),33)
RSLT = CPMI(F(I),34)
RSLT = CPMI(F(I),35)
RSLT = CPMI(F(I),36)

Return the version number
Reset the disk system
Select disk
Open file
Close file
Search for first
Search for next
Delete file
Read a file sequentially
Write a file sequentially
Make a new file
Rename file
Return login vector .
Return current disk
Get CPM buffer
Put CPM buffer
Get allocation vector
Write protect disk
Get read-only vector
Set file attributes

27
28
29
30
31
32
33
34
35
36

III-52

Get user code
Set user code
Read random
Write random
<:ompute file size
Set random record

Users' Manual Supplement, Version IV
New Optional Facilities

The following additional BASIC calls with no corresponding CP/M BOOS function
calls are also available in BCPM:
Set file name
Get file name
Get attribute flag
Set attribute flag to 1
Clear attribute flag to 0
Get FCB for calls 17 & 18
Get file extent number
Set file extent number
Get current record number
Set current record number
Get random record number
Set random record number
Get byte out of buffer
(Used after calling CPM26G)
CALL CPMS8(8(1),BYTNUM,VALUE) Set byte in buffer
(Used before calling CPM26P)

CALL
CALL
RSL T
CALL
CALL
CALL
RSL T
CALL
RSL T
CALL
RSL T
CALL
RSL T

CPMSFN(F(l),NAME$)
CPMG="N(F(I),NAME$)
= CPMGFL(F(I),FLAG)
CPMSFL(F(l),FLAG)
CPMCFL(F(l),FLAG)
CPMFCB(G(I»
= CPMGE(F(l»
CPMSE(F(l),EXTENT)
= CPMGCR(F(l»
CPMSCR(F(l),CRNUM)
= CPMGRR(F(I»
CPMSRR(F(l),RRNUM)
= CPMGB(B(l),B YTNUM

The following paragraphs define the arguments to the preceding calls.
RSL T.
DRIVE.

An integer value returned by the function.
An integer (0 •• 15) corresponding to CP/M drives A•• P.

F. A 21-element integer array corresponding roughly to the CP/M FCB. F should
be in itialized to zeros. The order of the fields in the FCB is irrelevant, since
routines are provided that can access the important fields.
NAME. A 14-element character array corresponding to a CP/M file name
specification (with or without wild cards).
LOGVEC. A 16-element integer array with values (0 or 1), where values of 1
correspond to the drives that have been logged in.
ALL VEC. An integer array with values (0 or 1), where values of 1 correspond to
blocks that have been allocated; the number of elements in the array correspond to
the number of blocks per disk.
RODVEC. A 16-element integer array with values (0 or 1) where values of 1
correspond to the drives that have been write protected (read only drives).
USRNUM.
care".

An integer with values

a

through 15, 63 for ''?'', or 255 for "don't

III-53

Users' Manual Supplement, Version IV
New Optional Facilities

FLAG.

An integer from 1 to 11 correspo

EXTENT.

An integer with values

a •• 255 or 63 for ''?''.

CRNUM. An integer corresponding to the desired current record number for a file
being accessed sequentially.
RRNUM. An integer corresponding to the desired random record number for a file
being accessed randomly.
B. An integer array large enough to contain the CP/M buffer (byte array); this
local buffer is necessary since the CPM buffer cannot be directly accessed from a
FORTRAN program.
B YTNUM. An integer from 1 to twice the local buffer size, which is the desired
byte index into the CP/M buffer.
VALUE.

An integer from

a

through 255 (i.e., a byte value).

G. A 21-element integer array corresponding roughly to a special CP/M FCB that
is used during directory searches; G should be initialized to zeros.

III-54

Users' Manual Supplement, Version IV
New Optional Facilities

Example BASIC Program Using BCPM

USES Brnvt
REJv1
RaM This progrmn serves only as a demonstration of how some of
REM the more useful routines in the BCAM unit are invoked.
REJv1 At the same time, it accompl ishes the following:
REJv1
1) copies the first 10 records of FILEl to FILE2
REJv1
using sequential reads and writes.
REM
2) closes and reopens FILE2 and co~utes its size so
REJv1
that more records can be appended.
REM
3)
sets the random record nurrber for FILEI to the current
REJv1
record and copies the remainder of the records using
REJv1
random reads and writes.
REJv1 ~E:
In order to si~lify the demonstration, very few
REJv1
error checks are included.
REM WARN I I\G : 1ft h e s pee i fie d 0 u t put f i 1 e a Ire a dye xis t s, i tis
REJv1
deleted by this demonstration program.
RErvt

INTEGER RS LT ,RRf\l...M, RRf\l...M2
DIM INTEGER F(21)
DIM INTEGER F2(21)
DIM INTEGER 8(512)
DIM NANE$*14
REM Initialize FCB arrays with zeros
FOR I = 1 TO 21 :: F(I) = 0 :: F2(I) = 0 :: NEXT I
ACCEPT "Enter FILEI name: ":NAlvE$
REM Set FILEl name specification in the FCB
RSLT = CPNSFN(F(l),NAME$)
REM Open FILEI
RSLT = CAMI(F(1),15)
ACCEPT "Enter FILE2 name: ":I\LAJVE$
REM Set FILE2 name specification in the FCB
RSLT = CPN5FN(F2(1),NAME$)
RaM Open FILE2 - delete it if it already exists
RSLT = CPMI(F2(1),15)
IF RSLT <> 0 THEN GOTO 20
REJv1 Delete FILE2
RSLT = CRMI(F2(1),19)
REM Make (create) FILE2
20 RSLT = CAMI(F2(1),22)
REM Set current record numbers to zeros for FILEI & FILE2
CALL ~CR(F(l),O)
CALL CPMSCR(F2(1) ,0)
FCR I = 1 TO 10
REM Read record from FILEI sequentially
III-55

Users' Manual Supplement, Version IV
New Optional Facilities

RSLT = CAMI(F(1),20)
IF RSLT <> 0 THEN GOTO 40
REM Wr i te record to FILE2 seq'uent i ally
RSLT = CAMI(F2(1),21)
NEXT I

REM Close and re-open FILE2
RSLT = CPMI(F2(1),16)
RSLT = CRMI(F2(1),15)
R8M Corrpute size of FILE2
RSLT = CAMI(F2(1),35)
REM Save random record nurrber for FILE2
RANUM2 = CPMGRR(F2(1))
REM Set random record number for FILEI to current record
RSLT = CPMI(F(1),36)
REM Save random record nurrber for FILEI
RANUM = CPMGRR(F(l))
REM Read record from FILEI randomly
30 RSLT = CPMI(F(1),33)
IF RSLT <> 0 THEN CDTO 40
REM Get CPM buffer
CALL CAM26G(B(1))
REM At this point the buffer could be examined and modified
REM Put CAM buffer
CALL CAM26P(B(1))
REM Write record to FILE2 randomly
RSLT = CRMl(F2(1),34)
RANUM = RANUM + 1
RRNUv12 = RANUM2 + 1
REM Set random record numbers for FILEI & FILE2 to next records
CALL CPtv1SRR(F (1) ,RANUM)
CALL CPMSRR (F 2 ( 1 ) ,RANUM2 )
CDTO 30
REM Close FILEl & FILE2
40 RSLT = CPMI(F(1),16)
RSLT = CPMl(F2(1),16)
El\D

Ill-56

Users' Manual Supplement, Version IV
New Optional Facilities

In.4

Turtlegraphics

Turtlegraphics is a package of routines for creating and manipulating images on a
graphic display. These routines can be used to control the background of the
screen, draw figures, alter old figures, and display figures using viewports and
scaling. It also contains routines that allow the user to save figures in disk files
and retrieve them.
The simplest turtlegraphic routines are intentionally very easy to learn and use.
Once the user is familiar with these, more complicated features (such as scaling
and pixel addressing) should present no problem.
A pixel is a single picture element or point on the display.
Turtlegraphics allows the user to create a number of figures, or drawing areas.
One such figure is the display screen itself, and other figures can be saved in
memory. Each figure has a turtle of its own. The size of a figure may be set
by the user (it does not need to be the same size as the actual display).
The actual display is addressed in terms of a display scale, which may be set by
the programmer. This allows the user's own coordinates to be mapped into pixels
on the display. All other figures are scaled by the global display scale.
The programmer may also define a viewport, or window on the display.
limits all graphic activity to within that port.

This

Turtlegraphics is shipped in two ways. If the p-System with turtlegraphics is
adapted to a particular hardware configuration, then the graphic routines are
already tailored to the display. The unit Turtlegraphics is already installed in
*SYSTEM.LIBRARY, and a program may use its routines by including the following
declaration.
USES turtlegraphics; (or an equivalent declaration in BASIC or FORTRAN).
If turtlegraphics is purchased as a separate, configurable product, then the user
must write a number of assembly language routines that control the graphic
display_ These routines are called by the turtlegraphics unit and must be written
and tested before turtlegraphics may be used.
Turtlegraphics and its capabilities are accessible to BASIC. There are no
parameter type conflicts with BASIC. The only restriction is that BASIC must
refer to all turtlegraphics identifiers by their first eight characters. For example,
ReadPixel becomes ReadPixe.

III-57

Users' Manual Supplement, Version IV
New Optional Facilities

A special, user-written unit is required to interface FORTRAN programs to
turtlegraphics. The interface of this unit can contain only legal FORTRAN types,
for example, integer, real, or alpha. The unit should be structured to
use turtlegraphics in its implementation section.

In.4.1

Using Turtlegraphics

Each subsection below is divided into two parts. The first part is an overview of
the topic at hand, and the second part consists of descriptions of the relevant
turtlegraphics routines.
F or quick reference, the next-to-Iast subsection of Section III.4.1 contains a listing
of the interface part of the turtlegraphics unit.
The last subsection of Section III.4.1 contains a sample program that illustrates a
number of the turtlegraphics routines.

111.4.1.1

The Turtle

The turtle is an imaginary creature in the display screen that will draw lines as
the user moves it aroun d the display. The turtle can move in a straight line
(Move), move to a particular point on the display (Move to), tum relative to the
current direction (Turn), and tum to a particular direction (Tumto).
Thus, the turtle draws straight lines in some given direction. The color of the
lines it draws can be specified (Pen color), and so can the nature of the line drawn
(Pen_mode).
Wherever the turtle is located, its position and direction can be ascertained by
three functions: Turtle_x, Turtle_y, and Turtle_angle.
NOTE: The turtle may be moved anywhere; it is not limited by the size of the
figure or the size of the display. But, only movements within the figure will be
visible.
To use the turtle in a figure other than the actual display, the programmer may
call Activate_Turtle.

III-58

Users' Manual Supplement, Version IV
New Optional Facilities

The following paragraphs describe the routines that control the turtle.

Procedure Move (distance: real);
Moves the active turtle the specified distance along its current direction.
turtle leaves a tracing of its path (unless the drawing mode is 'nop').
distance is speci fied in the units of the current display scale (see below).
movement will be visible unless the current turtle is in a figure that is
currently on the display.

The
The
The
not

Procedure Moveto (x, y: real);
Moves the active turtle in a straight line from its current position to the specified
location. The turtle leaves a tracing of its path (unless the drawing mode is
'nop'). The x,y coordinates are specified in the units of the current display scale.

Procedure Tum (rotation: real);
Turns the active turtle by the amount specified (in degrees). A positive angle
turns the turtle counterclockwise, and a negative angle turns it clockwise.

Procedure Tumto (heading: real);
Sets the direction (the heading) of the active turtle to a specified angle. The
angle is given in degrees; zero (0) degrees faces the right side of the screen, and
ninety (90) degrees faces the top of the screen.

Procedure Pen_color (shade: integer);
Selects the color with which the active turtle traces its movements (unless the pen
mode is 'nop'). This color remains the same until Pen_color is called again.
The color of the pen depends on the way the video display is set. If your
turtlegraphics is already configured, the available colors are described in the
documen tation for your hardware. If you must configure turtlegraphics yourself,
then the assembly language routines you write will control the display color: see
Chapter IV of this supplement.
A sample set of colors might be:

o=
1
2
3

Wild card color

= Green
= Red

= Yellow

III-59

Users' Manual Supplemen t, Version IV
New Optional Facilities

Turtlegraphics uses a numeri'c designation for color instead of a symbolic
designation like the word blue or red to maintain the p-System language and
hardware compatibility. For example, while Pascal would allow the use of
symbolic color designations, BASIC and FORTRAN would not.
The term wild card refers to the standard background color of your display. This
depen ds on your display hardware, and might be called a ''hard'' background (you
mayor may not be able to change it from a program: this depends on your
hardware configuration). In turtlegraphics, each individual figure may have its own
"soft" background color, which we refer to simply as the "background color" (as in
the discussion below).
You may also use black and white graphics, in which case the colors might be
simply:

o = Black

1 = White

Procedure Pen_mode (mode: integer);
Sets the active turtle's drawing mode.
is called again.

This mode does not change until Pen mode

These are the possible modes:

o

= Nap - does not alter the figure.

1

= Substitute .. writes the
= Overwrite .. writes the
= Underwrite - writes

2

current pen color.
current pen color.

the current pen color. When the pen crosses a
3
pixel that is not of the background color, that figure is !l2l. overwritten.

=

4
Complemen t - the pen complements the color of each pixel that it
crosses. (The complement of a color is its opposite: the complement of the
complement of a color is the original color.)
Values greater than 4 are treated as Nap.
These descriptions apply to movements of the turtle. They have a more complex
meaning when a figure is copied onto a figure that is already displayed.

111-60

Users' Manual Supplement, Version IV
New Optional Facilities

Function Turtle_x : real;
Returns a real value that is the x-coordinate of the active turtle, in units of the
current Display_scale.

Function Turtle_y : real;
Returns a real value that is the y-coordinate of the active turtle, in units of the
curren t Display_scale.

F unction Turtle_angle : real;
Retums a real value that is the direction (in degrees) of the active turtle.

Procedure Activate_Turtle (screen: integer);
Specifies to which figure subsequent turtlegraphics commands are directed. Each
invocation of this procedure puts the previously active turtle to sleep and awakens
the turtle in the designated figure. When turtlegraphics is initialized, the turtle in
the actual display is awake. The initial position of the turtle is (0,0) or the
bottom left comor of the screen, ready to move right.

In.4.1.2

The Display

We refer to the initial background of the display as the wild card color. The wild
card color (color 0) depends on your hardware (or it may be possible for you to set
it from a program). The default is typically black. The background color of a
turtlegraphics figure may be changed by the programmer with a call to
Background. This "soft" background applies when drawing mode is used, as
indicated above.
A figure can be filled with a single color (not necessarily the background color) by
calling F illscreen.
NOTE: If you use turtlegraphics (or customized routines of your own) to alter the
settings of your display, it is a good idea to reset everything before your program
terminates. Usually it is not possible for the display to return to its original
state, and the p-System software has no knowledge of what that original state was.

1II-61

Users' Manual Supplement, Version IV
New Optional Facilities

Procedure Fillscreen (screen: integer;
shade: integer);
F ills the specified figure ("screen") with the specified color ("shade"). If screen =
0, which indicates the actual display screen, then only the current viewport is
shaded. For user-created figures, the entire figure is shaded.

Procedure Background (screen: integer;
shade: in teger);
Specifies the backgound color for a figure.
figures is the wild card color.

Ill.4.l.3

The initial background color of all

Labels

It is possible to draw legends, labels, and so forth on the display while using the
turtlegraphics unit. This is done by calling either WChar or WString. The
character or string appears at the location of the currently active turtle. The
text is displayed in the type font defined by the file *SYSTEM.FONT (See Chapter
IV of this supplement to find out how to define a font).

Procedure WChar (c: char; copymode, shade: integer);
Writes a single character at the position of the currently active turtle, using the
indicated pen mode and color. The character is always displayed horizontally,
regardless of the active turtle's direction.

Procedure WString (s: string; copymode, shade: integer);
Writes a string starting at the position of the currently active turtle, using the
indicated pen mode and color. The string is always displayed horizontally,
regardless of the active turtle's direction •

. m.4.1.4

Scaling

When a programmer wishes to display data without altering the input data itself, it
is possible to set scaling factors that translate data into locations on the display.
This is done with Display_scale. The display scale applies globally to all figures.
Because of the shape of the actual display, data for particular shapes (especially
curved figures) might become distorted when using a "straight" display scale. In
this case, the function Aspect_ratio can be used to preserve the "squareness" of
the figure.

III-62

Users' Manual Supple men t, Version IV
New Optional Facilities

Procedure Display scale
(min_x,minJ,max_x,maxJ: real);
Defines the range of input coordinate positions that are to be visible on the
display. Turtlegraphics maps the user's coordinates into pixel locations according
to the scale specified in Display_scale.
This procedure sets the viewport to encompass the whole display. The display
bounds apply to input data. For the actual display, these bounds can be any
values the user requires, but for user-created figures (0,0) is the lower left-hand
comer.
If your turtlegraphics package is tailored to your hardware, then the default display
sc ale is already supplied. If you purchased turtlegraphics as a separate,
configurable product, then you must supply the parameters for your own display
(these must be returned by the user-written procedure Query Environment. (See
Section III.4.1).
The following lines are an example of a default scale.
pixels on the F LJ..L display.

It is simply the array of

min x = 0, max x = 319
miny = 0, max=y = 199
As an example, if a user wishes to graph a financial chart from the years 1970 to
1980 along the x axis, and from 500,000 to 500,000,000 along the y axis, the
following call could be used.
Display_scale(1970, 5.0E5, 1980, 5.0E8)
A fter this, calls to turtle operations could be done using meaningful numbers rather
than quantities of pixels.

F unction Aspect_ratio : real;
Returns a real number that is the width/height ratio of the CRT. This can be
used to compute parameters for Display_Scale that provide square aspect ratios.
If an application is designed to show information where the aspect ratio of the
display is critical (e.g., circles, squares, pie-charts, etc.) it must insure that the
following ratio is the same as the aspect ratio of the physical screen upon which
the image is displayed.
(max_x - min_x) / (max_y - miny)

1II-63

Users' Manual Supplemen t, Versi'on IV
New Optional Facilities

When the turtlegraphics unit is initaliz'ed, min_x and miny are set to O. max_x is
initialized to the number of pixels in the x direction, and maxy is initialized to
the number of pixels in the y direction. In order to change to different units that
still have the same aspect ratio, a call similar to the following example can be
used.
Display_ scale(O, 0, 100* ASPECT_ RA TIO, 100);
This utilizes Function Aspect ratio described above, and makes the y axis 100 units
long.
Turtlegraphics always treats the turtle as being in a fixed pixel location. Changing
the scaling of the system with a call to this routine in the middle of a program
does not alter the pixel position of any of the turtles in the figures. However,
the values returned from Xyos and Yyos may change.

ID.4.1.5

Figures and the Port

The programmer can create and delete new figures, each with its own turtle.
When a new figure is created, it is assigned an integer, and this integer refers to
that figure in subsequent calls to turtlegraphics procedures. New figures can be
saved (Put.figure) or displayed on the screen (Getfigure).
The actual display is always referred to as figure

o.

The active portion of the display can be restricted by calling viewport,
creates a "window" on the screen in which all subsequent graphics activity
place. The user might create a figure, specify the port, then display that
(or a portion of it) within the port. Specifying a viewport does not restrict
activity, it merely restricts what is displayed on the screen.

which
takes
figure
turtle

User-created figures can be saved in p-System disk files.

Function Create_Figure (x_size,y_size: real): integer
Creates a new figure that is rectangular, and has the dimensions (x size, y size),
where (0,0) designates the lower left-hand comer. The dimensions are in unIts of
the current display scale. The figure is identified by the integer retumed by
Create_figure.
When a figure is created it contains its own turtle, which is located at the
in i tialization position or 0,0 and has a direction of
(it faces the right-hand side
of the figure). The turtle in a user-created figure can be used by calling
Activate_Turtle.

°

III-64

Users' Manual Supplement, Version IV
New Optional Facilities

Procedure Delete_figure (screen: integer);
Discards a previously created display figure area.
Though figures may be created and destroyed, indiscriminate use of these contructs
may rapidly exhaust the memory available in the p-System due to heap
fragmentation. For example, a figure may be created using Create Figure (or it
may be read in from disk using F unction Load Figure, described below). If
possible, after that figure is used (for example, with a Get Figure, Put Figure,
Load figure or Store Figure operation) it should be deleted before other figures are
created. If many figures are created, and randomly deleted, the heap
fragmentation problem may occur.

Procedure Get Figure (source screen: integer;
corner_x,corner_y: real; mode: integer);
Transfers a user-created figure (the source) to the display screen (the destination)
using the drawing mode specified. The figure is placed on the display such that
its lower left corner is at (corner x, corner y). The x and y positions are
speci fied in the units of the current -display scale. If the display scale has been
modified since the figure was created, the results of this procedure are
unpredictable.
The following items define the drawing mode numbers.

a

Nop.

1

Substitute. Each pixel in the source replaces the corresponding pixel in
the destination.

2

Overwrite. Each pixel in the source that is not of the source's background
color replaces the corresponding pixel in the destination.

3

Underwrite.
Each pixel in the source that is not of the source's
background color is copied to the corresponding pixel in the destination
only if the corresponding pixel is of the destination's background color.

4

Complement. For each pixel in the source that is not of the source's
background color, the corresponding pixel in the destination is
complemented.

Does not alter the destination.

Values greater than 4 are treated as Nap.
If a portion of the source figure falls outside the display or the window, it is set
to the source's background color.
III-65

Users' Manual Supplement, Version IV
New Optional Facilities

Procedure Put Figure (destination screen: integer;
corner_ x,corner_y: real; mode: integer);
Transfers a portion of the display screen to a user-created figure using the drawing
mode specified (see above). The portion transferred to the figure is the area of
the display that the figure covers when it is placed on the display with its lower
left-hand corner is at (corner x, corner y). If the display scale has been modified
since the figure was created, the results of this procedure are unpredictable.
NOTE: When a figure is moved to the display by Get Figure, further modifications
to the display do not affect the copy of the figure that is saved in memory. If
the user wishes to save the results of graphics work on the display, it is necessary
to call Put.!'igure.

Procedure Viewport (min_x,miOJ, max_x,ma"-.y: integer);
Defines the boundaries of a "window" that confines subsequent graphics activities.
The viewport procedure applies only to the actual display. When a window has
been defined, graphics activities outside 01 it are neither displayed nor retained in
any way. Therefore, lines, or portions thereof, that are drawn outside the window
are essentially lost and will not be displayed (this is true even if the window is
subsequently expanded to encompass a previously drawn line). The viewport"
boundaries are specified in the units of the current display scale. If the specified
size of the viewport is larger than the current range of the display, the Viewport
is truncated to the display limits.

ID.4.1.6

Pixels

It is possible to ascertain (ReadyixeI) or alter (Set_pixel) the color of an individual
pixel within a given figure. These routines are more specific than the turtlemoving routines. They are less straightforward to use, but give the programmer
greater control.

Function Read_pixel (screen: integer; x,y: real): integer;
Returns the value of the color of the pixel at the x,y location in the specified
figure. The x,y location is specified in the units of the current Display_scale.

Ill-66

Users' Manual Supplement, Version IV
New Optional Facilities

Procedure Setyixel (screen: integer; x,y: real; shade: integer);
Sets the pixel at the x,y location of the specified figure to the specified color.
The x,y location is specified in the units of the current Display_scale.

ID.4.1.7

F otofiles

The programmer may create disk files that contain turtlegraphics figures. New
figures may be written to a file, and old figures restored for viewing or
modification.
When figures are written to a file, they are written sequentially, and assigned an
'index' that is their location in the file. They may be retrieved "randomly" by
using this index value.
The p-System name for files of figures always contains the suffix '.FOTO'. It is
not necessary to use this suffix when calling Read_figure_file or Write_figure_file
(if absent, it will be supplied automatically).

Function Read_figure_file (title: string): integer;
Specifies the title of a file from which all subsequent figures will be loaded. If a
figure file is already open for reading when this function is called, it is closed
before the new file is opened. Only one figure file may be open for reading at a
single time. This function returns an integer value which is the ioresult of
opening the file.

Function Wri te_figure_file (ti tIe: string): integer;
Creates an output file into which user-created figures may be stored. If another
figure file is open for writing when this function is called, it is closed, with lock,
before the new file is created. Only one figure file may be open for writing at a
single time. This function returns an integer result which is the ioresult of the
.file creation.

Function Load_figure (index: integer): integer;
Loads the indexed figure from the current input figure file and assigns it a new,
unique, figure number. An automatic Create figure is performed. If the operation
fails for any reason, a Figure_number of zero-(0) is returned.

III-67

Users' Manual Supplement, Version IV
New Optional Facilities

Function Store_figure (figure: integer): integer;
Sequentially writes the designated figure to the output figure file. The function
returns an integer that is the figure's positional index in the current output figure
file. Posi tional indexes start at one (1). If the index returned equals zero (0),
turtlegraphics did not successfully store the figure.

111.4.1.8

Routine Parameters

The next page shows the interface section for the turtlegraphics unit, including the
parameters to all turtlegraphics routines:

1II-68

Users' Manual Supplement, Version IV
New Optional Facilities

unit turtlegraphics;
interface
procedure Display scale( min x, min y,

-

max

x,

max y: real);

function Aspect_ratio: reai;
--function Create figure( x size, y size:

real ) : Integer;

-

procedure Delete tigure[SCreen:

-

integer );

procedure Viewport( min x, min y, max x,

max_y : -real );procedure F illscreen( screen:

inte er- shade:
integer;
procedure Background( screen: integer;
shade : integer );
function Read pixel( screen: inte er:
x, y : real :integer;
procedure Set_pixel( screen:integer;
x,y:real; shade:color );
procedure GetJ"igure( source screen:
integer,
corner_x, corner y: real;
mode : integer J;
procedure PutJ"igure( destination screen:
integer,
corner_x, corner y: real;
mode : integer J;
function Read figure tHe( title : string ):
- inte erfunction Write figure file title: string ):
- integer;
function Load_figure( index : integer ):
integer;
function Store_figure( figure: integer):
integer;
procedure A cti vate T urtle( screen:
integer);
function Turtle_x: real;
function Turtle y : real;
function Turtle:angle : real;
procedure Move( distance : real );
procedure Moveto( x,y : reaTT,
procedure T urn( rotation : real );
III-69

Users' Manual Supplement, Version IV
New Optional Facilities

procedure
procedure
procedure
procedure
procedure
DI.4.1.9

Turnto( heading: real );
Pen_ mode( mode : iiite'ger );
Pen_color( shade : integer );
WChar( c: char; copymode, shade: integer );
WString( s: string; copymode, shade: integer);

Sample Program

Here is a sample program that illustrates a number of turtlegraphics routines:

program Spiraldemo;
uses Turtlegraphics;

const nop = 0;
substi tute = 1;
var I, J, Mode: integer;
C: char;
Color: integer;
Seed: intcrer;
LX, L Y,X, UY: real;
function Random (Range: integer): integer;
begin
Seed: = Seed *' 233 + 113;
Random: = Seed mod Range;
Seed: = Seed mod 256;
end;
procedure ClearBottom;
{clears bottom line of screen
for prompts}
begin
Penmode (nop);
Moveto (0, 0);
WString (,
end;

" substitute, 1);

begin
ClearBottom;
{variOUS initializations}
WString ('ENTER RANDOM NUMBER: " substitute, 1);
read(keyboard, Seed);
ClearBottom;
Display_Scale (0, 0, 200*Aspect_Ratio, 200),
Ill-70

Users' Manual Supplement, Version IV
New Optional Facilities

{Aspect R ati 0 used so
pattern will be round}
Color: = 0;
W5tring ('ENTER VIEWPORT LL CORNER: " substitute, 1);
read(keyboard, LX,L V);
ClearBottom;
W5tring ('ENTER VIEWPORT UR CORNER: " substitute, 1);
read(keyboard, UX,UY);
ClearBottom;
W5tring ('PENMODE = t, substitute, 1);
read(keyboard, MODE);
Palette (0);
{O = black, 1 =green, 2 =red, 3 =yellOW}
ViewPort (LX, L Y, UX, UY);
{create port}
PenMode (0);
{use blank pen while moving it}
Moveto (100*Aspect Ratio, 100);
{put turtle in center of port}
{Aspect Ratio ensures that it will be
correctly centered}
PenMode (Mode);
{set pen to selected COlor}
J: = Random(90)+90;
{angle by which turtle will move
note that turtle begins facing right
and will move counterclockwise
(J is positive)}
f or I: = 2 to 200 do
{draw spiral in 200 segments
of increasing length}
begin
.
{cycle through the cOlors}
Color: Color+I;
if Color > 3 then Color: = 1;
PenColor (Color);
Move(I);
Turn(J);
end;

=

I: = Create Figure (UX-LX, UY -L V);
{create-figure the size of the port}
PutFigure (I, LX, L Y, 1);
{save it; mode overwrites
old figure (if any)}

III-71

Users' Manual Supplement, Version IV
New Optional Facilities

ViewPort (0, 0, Aspect Ratio*200, 200);
{re-specify viewport in
the lower left corner}
GetFigure (I, 0, 0, 1);
{display finished spiral}
readln;
{clear user input bUffer}
end.

III-72

IV.

INST ALLA TION GUIDE SUPPLEMENT

This chapter covers information that you will need to know if you have purchased
the UCS D p-System as an adaptable system, or if you are going to upgrade a
running version IV adaptable system to the current release level. It describes how
the installation of adaptable ~ystems differs from the description given in the
UCSD p-System Installation Guide. The sections that are pertinent to your
particular system should be read before reading the Installation Guide.
Several other miscellaneous topics related to installing and configuring the pSystem are covered.
NOTE: Only the extended SBIOS is supported by the current release. If you wish
to use a non-extended SBIOS you must supply stub routines (which pop parameters
and return) for the extended SBIOS routines.
If you are only going to upgrade a running version IV adaptable system, you will
need to understand what is described in the following sections:
IV.1.1
IV.1.3
IV.1.4
IV.1.6

Release Disk Format
Required New SBIOS Routines: Quiet and Enable
New Definition for PRNSTAT and SETTRAK
Installing GOTOXY

If you wish to install print spooling, you will need the information in the following
sections:
IV.1.2
IV.1.4
IV.3

Installing Events
New Definition for PRNST AT and SETTRAK
Setup

If you have an American National Standards Institue (ANSI) terminal, or if you plan
to library or memlock the as unit SCREENOPS (regardless of the type of terminal
you have), or if you wish to accept three character code sequences from the
keyboard, you should read section:
IV.!. 7

p-System support for ANSI Terminals

The installation of the 8086 adaptable system is described in section:
IV.2

The 8086 Adaptable System

There are several new fields within SYSTEM.MlSCINFO in the current release. They
are related to extended memory, print spooling, subsidiary volumes, etc. These
fields are set using the utility SETUP described in section:
IV.3

Setup

In order to install an adaptable TURTLEGRAPHICS package, you should read:

IV-1

Users' Manual Supplement, Version IV
Installation Guide

IV.4

Installing TURTLEGRAPHICS

F inaliy, listings of the new adaptable system release disks are given for each
processor in section:
IV.5

1V.1

Adaptable System Release Disk Directories

Installation of Adaptable Systems

This section gives information which is pertinent to all adaptable systems with the
current p-System release.

IV.1.1

Release Disk Format

The release disks for the current adaptable systems are formatted into virtual
floppies, as with previous adaptable systems. However, there are now two (rather
than three) virtual floppies per disk. Each virtual floppy contains 240 blocks. The
following diagram illustrates the disk images of the virtual floppies:
Track:
o
1

37 38

39

75

76

18--T-----------------------T8--T-----------------------T-0-1
10
10

TI
rl
It a I
I cI
I kI

240 Block Virtual
Floppy
Dis k Vo I urne On e

10
10

TI
240 Block Virtual
I n
rl
Floppy
1 u
It a I
Dis k V0 I ume Tw 0
I s
I cl i e
I kI
I d

I
I

I
1
1

1--_1_--____ ----------______ 1___ ' __---------------------1 ___ 1
NOTE: Remember to back up the disks that you have received with the p-System
before you do anything with them.

IV .1.2

Installing Events

Events are discussed in Chapter II of this supplement. The SBIOS routines QUIET
and ENABLE (discussed in Section IV.l.3), and the BIOS routine EVENT (discussed
in this section) are pertinent to the new event handling facilities.
EVENT is a BIOS routine that may be called from the SBIOS. When an SBIOS
routine detects an event such as a hardware interrupt or a key pressed on the
console's keyboard, it may call EVENT with an appropriate event number. This
event number may be associated with a semaphore in a high-level language (in
UCSD Pascal, this is accomplished by the ATTACH intrinsic).

IV-2

Users' Manual Supplement, Version IV
Installation Guide

The even t numbers 0 •• 31 are reserved for the p-System's use, and the event
numbers 32 •• 63 are available for user definition. The events that you may choose
to signal, and what you choose to do with them, are entirely up to you.
The following table gives machine-specific information concerning calls to EVENT:
Processor

BIOS vector offset

Z80
8080
8086
6502

Par arne ter Qassed in register
HH01

6
6

4
6

on stack,

(SP)+2 and (SP)+3

EVENT will destroy the information in all of the microprocessor's working
registers. The SBIOS is responsible for saving all the necessary processor state
prior to calling EVENT and restoring it upon return.

IV.l.3

Required New SBIOS routines: QUIET and ENABLE

This section describes the two new SBIOS routines that you must provide in order
to bring up the current p-System. They are called QUIET and ENABLE.
QUIET must disable any P-machine events from occurring. After a call to QUIET,
no part of the SBIOS should call EVENT until the corresponding call to ENABLE
has been made. The simplest way to do this may be to disable all processor
in terrupts. If your hardware configuration does not allow you to do this, you must
devise some other scheme for disabling events. A software mechanism may be
required to implement QUIET. If you wish, you may write code to queue events
during times when QUIET is in effect.
ENABLE allows P-machine events to occur. This may be done by simply reenabling processor interrupts, or by a scheme that corresponds to the one used by
QUIET.
QUIET and ENABLE are always called in pairs by the p-System.
never nested.

These calls are

The following table gives the machine-specific SBIOS vector offsets for QUIET and
ENABLE:
Processor

zao
a080
8086
6502

GUIET

ENABLE

54
54
38
54

57
57
3A
57

hex
hex
hex
hex

hex
hex
hex
hex
IV-3

Users' Manual Supplement, Version IV
Installation Guide

These vector offsets follow' the offsets for the extended SBIOS routines. The
extended SBIOS routines are not required to be fully implemented (they may be
stub routines which pop the parameters and return, signalling offline), but QUIET
and ENABLE must be implemented.

IV.1.4

New Definition for PRNST AT and SETTRAK

Definitions for the two SBIOS routines PRNST AT and SETTRAK have been modified
for this release. PRNST AT ~ be upgraded in order to run the current pSystem.
The SBIOS routine PRNST A T (described in the Installation Guide) now has an
additional parameter. This parameter is an I/O direction flag.
When the I/O direction flag is non-zero, it indicates input and PRNST AT should
behave as in previous versions.
When the I/O direction flag is 0, it indicates output and the following information
should be returned by PRNST AT:
The online/offline status of the printer is returned as the first parameter
in the same manner as before.
The second parameter retums:
a if the printer is not busy (i.e. can accept a character)
FF if the printer is busy
The new I/O direction flag is passed as follows:
Processor
Z80
8080
8086
6502

I/O Direction Parameter Passed in Register

c
C
-AX
A

As long as the printer is busy the print spooler will not send any characters.
NOTE: This routine must be upgraded for print spooling to work.
The SETTRAK routine is compatible with earlier versions. It should be written,
however, to accept a 16 bit track number if that is possible (i.e. if you are using
disks that have more than 256 tracks).
On 8086 systems, the track number is passed in AX (as described in Section V.2.2).
IV-4

Users' Manual Supplement, Version IV
Installation Guide

On 8080 and Z80 systems, the track number is passed in BC. Previously, this
parameter was passed only in register C. If you only require 8 bits to specify
track numbers, you may ignore register B which contains the most significant byte.
On 6502 systems, this parameter is passed in XA. Previously, this parameter was
passed only in register A. If you only require 8 bits to specify track numbers, you
may ignore register X which contains the most significant byte.

IV .1.5

Floating Point Number Configuration

The p-System can be configured to use no real numbers, two word real numbers, or
four word real numbers. If the floating point package is not used, more memory
and disk space is available for other purposes. Two word reals has been the
standard in the past. Four word (64 bit) real number representation significantly
improves the accuracy and power of floating point operations.
NOTE: SofTech Microsystems expects to discontinue support of the two word
floating point packages sometime in the future.
There are three components of the p-System which must be configured consistently
with respect to real number size. These are the Operating System, the
Interpreter, and the Compiler.
The Operating System is shipped with no REALOPS unit within it. If floating
poin t operations are to be performed, a REALOPS unit must be libraried into the
OS using the library utility (described in the Users' Manual). The four word and
two word REALOPS units are found in two code files named:
REALOPS.xx.CODE
The "xx" will vary for different types of floating point representations, but will
always contain a tt4" or a "2". For example:
REALOPS.2.CODE
REALOPS.Z2.CODE
REAlOPS.4.CODE
Choose the REALOPS unit with the desired real size (2 or 4), and library it into
the Operating System (named SYSTEM.PASCAL on the disk). Be sure that
KERNEL occupies slot a within the output file, and that USERPROG occupies slot
15. Rename the output file SYSTEM.PASCAL and place it on a boot disk.
NOTE: In addition to the general description of Library given in the Users' Manual,
there is also an example of installing GOTOXY into the OS using Library that is

IV-5

Users' Manual Supplemen t, Version IV
Installation Guide

given in the Installation Guide. This example may be useful to read if you are
not familiar with the Library utility. It does not matter what slot REALOPS
occupies, as long as KERNEL occupies slot 0 and USERPROG occupies slot 15.
The Interpreter is also shipped with no real number facilities bound into it. A
new Interpreter must be linked together with the appropriate floating point package
if real numbers are to be used. This is done using the Linker as described in the
Installation Guide under ''Reconfiguring the Interpreter". The files that you must
link together are slightly different, however.
On Z80 and 8080 systems you must choose from the following files when linking an
interpreter together:
80BO interpreter
interpreter

INTERP .B.CODE
INTERP .Z.CODE

zao

FPO.CODE
FP2.B.CODE
FP2.Z.CODE
FP4.CODE

no reals
2 word reals for 80BO
2 word reals for Z80
4 word reals for either

RSP.CODE

run time support package

BIOS.CODE
BIOS.C.CODE
BIOS.CR.CODE
BIOS.CRP .CODE

BIOS choices as described
in the Installation Guide

INTER.X.CODE
INTER.CPMl.CODE
INTER.CPM2.CODE
INTER.CPM4.CO DE

extended SBIOS interface
CP/M SBIOS interface, 1 disk drive
CP/M SBIOS interface, 2 disk drives
CP/M SBIOS interface, 4 disk drives

TERTBOOT .CODE

tertiary bootstrap

You must link exactly one file from each of the six groups just listed. For
example, to create a two word floating point Z80 interpreter with full BIOS
capabilities, you would choose the following files:
INTERP .Z.CODE
FP2.Z.CODE
RSP.CODE
BIOS.CRP .CODE
INTER.X.CODE
TERTBOOT.CODE

IV-6

Users' Manual Supplement, Version IV
Installation Guide

On 8086 adaptable systems, you will need to choose the files that make up the
interpreter from a similar group, as described in Section IV.2 of this supplement.
On 6502 systems the files that are linked together are the same as before, except
that there is only one Interpreter code file (INTERP .CODE) and one of the
following floating point packages must be included:
FPO.CODE
FP2.CODE
FP4.CODE

no reals
two word reals
four word reals

The Pascal Compiler will default to the real size of the interpreter that it is
running on. (This default may be overriden by the $R2 and $R4 Compiler options,
however.)
The BASIC and FORTRAN compilers are both shipped in two different versions;
one for each real size. Also, two versions of the corresponding runtime libraries
are Shipped.

IV.1.6

Installing GOTOXY

The standard GOTOXY contained in the Operating System runs on all machines.
You will probably want to write and install into the OS your own GOTOXY
because a machine-speci fic version of it will run faster than the generalized
version. This is described in the Installation Guide.
In the current version, the variables CUR X and CUR Y within the SCREENOPS
unit of the OS are now updated by GOTOXY. This anows the p-System to keep
track of the cursor position on the screen. You should make sure that this is
done by your machine-specific version of GOTOXY. The following sample
GOTOXY updates the sample given in the Installation Guide.

IV-7

Users' Manual Supplement, Version IV
Installation Guide

{$U-}
{ ALWAYS include this compiler directive. }
UNIT GOTOXY;
USES {$U SCREENOPS.CODE} SCREENOPS (SC TX PORT, SC PORT);
INTERF ACE
PROCEDURE AGOTOXY(X,Y: INTEGER);
IMPLEMENT A TION
PROCEDURE AGOTOXY;
TELL LENGTH MINUS 1 = 3,
OFFSET = 32;
{ You may have to change these, depending on your terminal. }
CONST

VAR

TELL: PACKED ARRAY [O ••TELL LENGTH MINUS 1]
OF 0•• 255;
-

BEGIN
IF X> 79 THEN X: = 79
ELSE IF X <0 THEN X: = 0;
IF Y>23 THEN Y:=23
ELSE IF Y






a
b
c
d
[ 1
[ 2

there would be no problem.

IV-IO

When the p-System receives a prefix character (in

Users' Manual Supplement, Version IV
Installation Guide

this case 






a
b
c
d
a 1
a 2

In this case, the FI key could not be used as a p-System key because it conflicts
with the left arrow.
NOTE: ANSI terminals can asynchronously send XON/XOFF sequences to delay
transmission when they are being overrun. They do this using the following
definitions:
XOFF
X(N

= CTRL-S
= CTRL-Q

CTRL-S is normally the p-System soft toggle for START/STOP (which does the
identical task as the ANSI predefined CTRL-S and CTRL-Q). It confuses the pSystem, however, if the terminal itself sends these same sequences.
If you have purchased the UCSD p-System as an adaptable system and you have an
A NSI terminal, it is recomended that KEY FOR STOP be set to some value other
than CTRL-S (using the SETUP utility) •. You should also implement XON/XOFF
support in your console I/O routines.

IV.2

The 8086 Adaptable System

The p-System will now operate on the 8086 processor.
is not described in the Installation Guide.

The 8086 Adaptable System

This section describes the bootstraps, SBIOS interface, and BIOS interface for the
8086. You should already be familiar with the adaptable system in general, as
IV-II

Users' Manual Supplement, Version IV
Installation Guide

described in the Installation Guide.
The user is responsible for supplying SBIOS routines, as described in the
Installation Guide and this supplement.
8086 systems that run version IV can take advan tage of extended memory.
Extended memory is described in Chapter 3 of this supplement.
The P-machine emulator ("interpreter") for the 8086 is broken into several modules.
These are:
1)

The main part of the Interpreter.

2)

Floating point emulation.

3)

The RSP (Runtime Support Package).

4)

The BIOS (Basic I/O Subsystem).

5)

The tertiary bootstrap routine.

The SYSTEM.INTERP supplied on the release disks contains no floating point
support or I/O character queuing (INTERPX.COOE, FPO.CODE, RSP.CODE,
BIOS.CODE, and TERTBOOT .CODE).
To link an 8086 Interpreter, the following modules (with their object code file
names to the right) must be linked together:
Interpreter

INTERPX.CODE

Floating Point

FPO.COOE or
FP2.CODE or
FP4.CODE

Run time Support Package

RSP.COOE

BIOS

BIOS .CODE or
BIOS.C.CODE or
BIOS .CR.CODE or
BIOS.CRP .CODE

Tertiary Bootstrap

TERTBOOT .CODE

The "0", "2", and "4" in the FP code files distinguish between no real number
support, two word, and four word floating point packages. FPO must be linked in
IV-12

Users' Manual Supplement, Version IV
Installation Guide

if no real number support is chosen. The Operating System must contain routines
that use the corresponding fleating point size (REALOPS unit in SYSTEM.PASCAL)
if real numbers are to be used.
The "C .. , "CR", and ''CRP'' in the BIOS code files indicate console, remote port,
and printer character input queuing, as stated in the Installation Guide.
A fter linking, the utility program COMPRESS (described in the Users' Manual) must
be run to form a memory image file of the Interpreter. The answers to the
questions asked by COMPRESS are: NO relocatable output, base address = 0, the
linker output file, and the desired filename (such as SYSTEM.INTERP).

IV.2.1

Bootstrapping the p-System

The steps necessary to get the Adaptable p-System started are described here.
Please note that all address values are to be set relative to the CS register (i.e.,
the Interpreter load point specified by the user).
1. Load the primary bootstrap (Track 0, Sectors 1 and 2) and the user
supplied SBIOS.

2. 5 et the 5 tack Pointer to any unused (but VALID) address value (such
as COO a). The SP register 'win be reset at the start of' the
TERTBOOT routine, so the value set here is not critical. Push the
Adaptable System parameters onto the Stack as indicated in the
Installation Guide. As previously stated, all address values are
relative to the Interpreter load point. (See below.)
3. Set the CS register to the desired base Ooad point) of the Interpreter.
4. Do a short (intrasegment) jump to the bootstrap address (8000H -- CSrelative). (The CS register may also be set by making a long
{intersegment} jump.) This invokes the primary bootstrap.
The primary bootstrap reads the secondary bootstrap from disk and jumps to it.
The secondary bootstrap finds the Interpreter, reads it in, and jumps to the
tertiary bootstrap (which is part of the Interpreter). Once the System is up and
running, a user may wish to simplify the bootstrapping mechanism (see the
Installation Guide).

IV .2.2

SBIOS Interface

The SBIOS routines are called from the BIOS through an address vector (NOT a
jump vector, as with other processors). The following table briefly defines this
interface. Addresses pointed to by the vector offsets are CS-relative.

IV-13

Users' Manual Supplement, Version IV
Installation Guide

Outputs

Routine

Vector offset

SYSINIT

00

SYSHALT

02

CONINIT

04

AH = ioresult

CONSTAT

06

AH = ioresult
AL = char present
(0 = False, FF = True)

CONREAD

08

AH = ioresult
AL = char

CONWRIT

OA

AL = char

SETDISK

OC

AL = current disk

SETTRAK

OE

AX = current track

SETSECT

10

AL = curren t sector

IV-14

InEuts
AX = pointer to
Interpreter
jump table

AH = ioresult

Users' Manual Supplement, Version IV
Installation Guide

Routine

Vector offset

SETBLFR

12

DSKREAD

14

AH

DSKWRIT

16

AH

DSKINIT

18

AH

DSKSTRT

1A

DSKSTOP

1C

PRNINIT

1E

PRNSTAT

20

PRNREAD

22

PRNWRIT

24

REMINIT

26

AH

REMSTAT

28

AH
AL

REMREAD

2A

AH
AL

REMWRIT

2C

AL

USRINIT

2E

CL

USRSTAT

30

TOS(SP)->retum
i/o toggle
·statrec
CL =device II

Inputs
AX

Outputs

= buffer

addr
(ES-relative)

AH
AX

= control

word

AH
AL
AH
AL

AL

= char

= char
= unit II

AH

AH
AH

= ioresult
= ioresult
= ioresult

= ioresult
= ioresult
= char present
ioresult
= char
=
= ioresult
= ioresult
= ioresult
= char present
= ioresult
= char
= ioresult
= ioresult
".

IV-15

Users' Manual Supplement, Version IV
Installation Guide

Routine

Vector offset

USRREAD

32

Outputs

Inputs
TOS(SP)->retum addr
bloc~

/I

byte count
Abuffer (OS-reI)
device /I
con trol word
USRWRIT

34

CLKREAO

36

QUIET

38

ENABLE

3A

TOS(SP)->retum addr
block /I
byte count
Abuffer (OS-reI)
device II
con trol word
AH
OX
CX

= ioresult
= high word
= low word

Notes on the 58105:

1. The 58105 must be assembled relative to zero (i.e., with no ORG
directive), and relocated to its load address (relative to the CS or OS
register) by using the COMPRESS utili ty.
2. The 58105 is responsible for ensuring that the 55, OS, and CS
registers are restored to the same state as at entry. All other
registers are available for use.
3. The SBIOS vector contains only addresses, not jump instructions.

4. All 58105 routines are CALLed indirectly from the BIOS through the
vector. To return to the BIOS, a RET instruction is all that is
needed (these calls and retums are short (intrasegment) CALLs and
RETs).
5. The 8086 Adaptable System requires an Extended SBIOS (all of the
above entry points). If user, remote, clock, or printers are not
present, the routine should simply retum an ioresult of 9 (offline).

IV-16

Users' Manual Supplement, Version IV
Installation Guide

6. QUIET and ENABLE are new entry points not documented in the
Installation Guide. QUIET contains the functions necessary to disable
P-machine "events" from occurring. ENABLE allows events to occur.
(See Section IV.1 for more information on QUIET and ENABLE.) In
most systems, the disable and enable interrupts functions (respectively)
are all that are necessary (a.. I and STI processor commands). A few
hardware configurations may not permit the global disabling of
processor interrupts, so some other scheme must be devised.

7. The routine vector passed to SYSINIT is described below.

IV .2.3

BIOS Routines Accessible to the SBIOS

The use of the new routine EVENT is described in Chapter II of this supplement,
which discusses interrupt handling.
To use print spqoling, use EVENT to signal a keys-ready interrupt (event number
19). See Chapter III of this supplement for more details.
Routine

Vector offset

POLLUNITS

00

DSKCHNG

02

Inputs

BX

= ... disk

descriptor block

(II tracks

IIsectors
sector size
interleaving
skew
first track)
EVENT

IV.2.4.

04

01

= event

II

The Primary Bootstrap

The primary bootstrap must be assembled relative to zero (i.e., without an ORG
directive), and' relocated to BOaOH by using the utility COMPRESS (described in the
Users' Manual).
The address of the Interpreter must be set to zero. The CS register must be set
to the desired Interpreter base (shifted right by 4 bits). The bootstrapping and
interpretation are relative to this CS value. The OS, ES, aod SS registers will be
set to the same value by the bootstrap. (ALL address values within the SBIaS
must be relative to this CS value.)

IV-17

Users' Manual Supplemen t, Version IV
Installation Guide

The following parameters must be on the stack:
TOS

-->

SBIOS tester parameter (ignored by primary boot)
address of Interpreter (CS-relative)
address of SBIOS
(CS-relative)
address of low word of contiguous memory (CS-relative)
address of high word of contiguous memory (CS-relative)
number of tracks on boot disk
number of sectors per track
number of bytes per sector
interleaving factor
first interleaved track
track-to-track skew
maximum number of sectors in table
maximum number of bytes per sector

The primary bootstrap must pop these values from the stack, load the S810S, and
c all the SBIOS SYSINIT routine. It must then read in the secondary bootstrap,
which is located on Track O.
Next, the primary bootstrap must push the following values onto the stack:
TOS

-->

address of Interpreter (relative to CS)
address of SBIOS
(CS-relative)
address of low word of contiguous memory (CS-relative)
address of high word of contiguous memory (CS-relative)
number of tracks on boot disk
number of sectors per track
number of bytes per sector
interleaving factor
first interleaved track
track-to-track skew
maximum number of sectors in table
maximum number of bytes per sector

NOTE: These values are the same as before, except that the SBIOS test
parameter is no longer present.
Finally, the primary bootstrap must jump to the secondary bootstrap.
IV.J

SETUP

The SETUP utility alters some new
fields are described in this section.
the fields within SYSTEM.MISCINFO
covered in the Installation Guide.
IV-IS

fields within SYSTEM.MISCINFO. These new
The use of SETUP itself, and descriptions of
that were already ~lterable by the utility, are
The current version of SETUP is compatible

Users' Manual Supplement, Version IV
Installation Guide

with earlier versions of SYSTEM.MISCINFO.
NOTE: SETUP can now be used to specify three code character sequences to be
input from the keyboard (as well as two code sequences). See Section IV .1.7, "pSystem Support F or ANSI Terminals", for information conceming this.
NOTE: In previous versions of the UCSD p-System there were only 6 blocked
devices (4, 5, 9 •• 12). The number of blocked devices is now configurable with
SETUP. After the highest numbered blocked device, subsidiary volumes are
allocated device numbers. (Subsidiary volumes are described in Chapter II of this
supplement.) The number of subsidiary volumes is also configurable. Above the
highest numbered device set aside for subsidiary volumes, user-defined serial
devices may be defined. (User-defined serial devices are also discussed in Chapter
II.) The maximum number of user-defined serial devices is 16. The highest unit
number allowed for any of these devices is 127. The allocation of these unit
numbers is taken care of by the following fields:
FIRST SU3SIDIARY VOL NUMBER
MAX NUMBER OF SUBSIDIARY VOLS
MAX NUMBER OF USER SERIAL VOLS
These fields are described below.
NOTE:
fields:

The memory update feature of Setup does not update any of the following

HAS SPOOLING
HAS EXTENDED MEMORY
CODE POOL SIZE
CODE POOL BASE[FIRST WORD]
COOC POOL BASE[SECOND WORD]
SEGMENT ALIGNMENT
FIRST SUBSIDIARY VOL NUMBER
MAX NUMBER OF SUBSIDIARY VOLS
MAX NUMBER OF USER SERIAL VOLS
In order to update these fields, it is necessary to create a new SYSTEM.MISCINFO
on the boot disk, and re-boot.

IV-19

Users' Manual Supplement, Version IV
Installation Guide

The following is a list of all the fields now modified by SETUP:
BACKSPACE
CODE POOL BASE[FIRST WORD]
CODE POOL BASE[SECOND WORD]
CODE POOL SIZE
EDITOR ACCEPT KEY
EDITOR ESCAPE KEY
EDITOR EXCHANGE-CELETE KEY
EDITOR EXCHANGE-INSERT KEY
ERASE LINE
ERASE SCREEN
ERASE TO END OF LINE
ERASE TO END OF SCREEN
FIRST SU3SIDIARY VOL NUMBER
HAS 8510A
HAS BYTE FLIPPED MACHINE
HAS CLOCK
HAS EXTENDED MEMORY
HAS LOWER CASE
HAS RANDOM CURSOR ADDRESSING
HAS SLOW TERMINAL
HAS SPOOLING
HAS WORD ORIENTED MACHINE
KEYBOARD INPUT MASK
KEY FOR BREAK
KEY FOR FLUSH
KEY FOR STOP
KEY TO ALPHA LOCK
KEY TO DELETE CHARACTER
KEY TO DELETE LINE
KEY TO END FILE
KEY TO MOVE CURSOR DOWN
KEY TO MOVE CURSOR LEFT
KEY TO MOVE CURSOR RIGHT
KEY TO MOVE CURSOR UP
LEAD IN FROM KEYBOARD
LEAD IN TO SCREEN
MAX NUMBER OF SU3SIDIARY VCLS
MAX NUMBER OF USER SERIAL VOLS
MOVE CURSOR HOME
MOVE CURSOR RIGHT
MOVE CURSOR UP
NON PRINTING CHARACTER
PREFIXED(DELETE CHA RACTER]
IV-20

Users' Manual Supplement, Version IV
Installation Guide

PREFIXED[EDITOR ACCEPT KEY]
PREFIXED[EDITOR ESCAPE. K~Y]
PREFIXED[EDITOR EXCHANGE-OCLETE KEY]
PREFIXED[EDITOR EXCHANGE-INSERT KEY]
PREFIXED[ERASE LINE]
PREFIXED[ERASE SCREEN]
PREFIXED[ERASE TO END OF LINE]
PREFIXED[ERASE TO END OF SCREEN]
PREFIXED[KEY TO OCLETE CHARACTER]
PREFIXED[KEY TO DELETE LINE]
PREFIXED[KEY TO MOVE CURSOR DOWN]
PREFIXED[KEY TO MOVE CURSOR LEFT]
PREFIXED[KEY TO MOVE CURSOR RIGHT]
PREFIXED[KEY TO MOVE CURSOR UP]
PREFIXED(MOVE CURSOR HOME]
PREFIXED[MOVE CURSOR RIGHT]
PREFIXED[MOVE CURSOR UP]
PREFIXED(NON PRINTING CHARACTER]
PRINT ABLE CHARACTERS
SCREEN HEIGHT
SCREEN WIDTH
SEGMENT ALIGNMENT
STUOCNT
VERTICAL MOVE DELAY
The following are the definitions of the new fields that are affected by SETUP:
CODE POQ BASE[FIRST WORD]
CODE POOL BASE[SECOND WORD]
These two entries are used to determine where the code pool resides on machines
which use extended memory.
On 8086 extended memory systems these two words, taken together, make up the
32 bi t address for the base of the external code pool. The FIRST WORD is the
most significant 16 bits, and the SECOND WORD is the least significant 16 bits.
The least significant four bits must always be 0 on 8086 systems. Depending upon
your memory configuration, you might set these values as follows for 8086 systems:
FIRST WORD = 1
SECOND WORD = 0
This indicates the binary value of 1 followed by 16 zeros (the start of the second
64K area).
IV-21

Users' Manual Supplement, Version IV
Installation Guide

On 9900 systems, the FIRST WORD is the 990/10 memory BIAS. (This is not a
straight memory address; see your hardware manual for more information
concerning 9900 BIAS.) It defines the start of the code pool area. The SECOND
WORD is not used. There is no error· checking done on this value anywhere
except the 9900 hardware.
NOTE: The PoolBase field in the Pooldes record within the OS will be set to the
value indicated by these two fields. If the code pool is intemal (i.e., you are not
using extended memory), both words must be set to O.
NOTE: .RELPROC and .RELFUNC assembly language routines may not be executed
on TI 9900 systems when an external code pool is being used. Attempting to
execute such a routine will result in runtime error number 11 (instruction not
implemented). Programmers should use .PROC and .FUNC which forces code to be
placed in the heap (instead of the external code poo!).
CODE POOL SIZE

If the code pool is external, this entry indicates the number of WORDS minus one
available for it to fill. The Poolsize field in Pooldes will be set to this value.
This value may be as great as 32767 (a 64K area). It may also be smaller, if
desired, but it should be at least 12287 (a 24K area). The base address of this
area is given by the two code pool base words. This value is ignored if you are
not using extended memory.
HAS EXTENDED MEMORY
Normally the code pool resides between the Stack and the Heap. If the code pool
is removed from that memory space and placed in a different area altogether, then
HAS EXTENDED MEMORY should be set to TRUE,otherwise it should be set to
FALSE. (An example of Extended Memory would be a 128K byte machine where
the stack and heap reside within one 64K area, and the code pool within the other
64K area.)
HAS SPOOLING
If the PRINT SPOOLER (see Section 5 of this document) is to be used, this must
be set to TR LE.

IV-22

Users' Manual Supplement, Version IV
Installation Guide

KEYBOARD INPUT MASK
Characters that are recieved from the Keyboard will be logically AND'ed with this
value. For th e typical ASClI Keyboard, this value should be set to 7F hex (which
throws away the eighth bit). For some keybords which generate eight bit
characters, the value FF hex should be used.
FIRST SUBSIDIARY VOL NUMBER
Subsidiary volumes are described in Chapter II of this supplement. This entry is
the first unit number to be used as a subsidiary volume. If, for example, it is set
to 14, the first subsidiary volume is device 1114:.
NOTE: In previous versions of the UCSD p-System, only 6 blocked devices were
allowed: 4, 5, 9•• 12. Now the number of blocked devices is configuarable. The
devices from 9 through 'First subsidiary vol number" - 1 are now standard blocked
devices. Subsidiary volumes start with the device number indicated by 'First
subsidiary vol number". The number of subsidiary volumes is determined by "Max
number of subsidiary vols". The highest device number allowed for subsidiary
volumes, or standard blocked devices, or user-defined serial volumes (described
below) is 127. (The device numbers 128 and above are reserved for user-defined
devices, as described under ''The Extended SBIOS" in the Installation Guide.)
WARNING: 'First subsidiary vol number" must be greater than 8 to allow space for
all of the standard system units.
MAX NUMBER OF SL8SIDIARY VOLS
This field indicates the maximum number of subsidiary volumes which may be
online at once. Because the p-System Unit Table expands a few bytes with each
additional subsidiary volume entry, this number should be set to the smallest
convenient value. (Also see FIRST SUBSIDIARY VOL NUMBER.)
The highest subsidiary volume will be 'First subsidiary vol number" + "Max number
of subsidiary vols" - 1. This expression must be less than or equal to 127, which
is the highest device number allowed for system units.

IV-23

Users' Manual Supplement, Version IV
Installation Guide

MAX NUMBER OF USER

SERIA~

VOLS

This entry is the total number of user-defined serial volumes desired. User-defined
serial volumes are described in Chapter II of this supplement. The first device
number assigned to a user-defined serial volume is ''First subsidiary vol number" +
"Max number of subsidiary vols" - 1.
F or example, if "First subsidiary vol number" is 12 (i.e. 1112:) and "Max number of
subsidiary vols" is 4, then the first user-defined serial volume would be device
1116:. If this entry, "Max number of user serial vols", is 2, then the user-defined
serial volumes would be 1116: and 1117:.
I f ''Max number of subsidiary vols" is 0, then the first user-defined serial volume
is equal to ''First subsidiary vol number". In this case, "Max number of user serial
vols" + "First subsidiary vol number" - 1 yields the highest numbered user-defined
serial volume.
NOTE: The largest value allowed for ''Max number of user serial vols" is 16. The
highest numbered user-defined serial volume must be less than or equal to 127.
NOTE: User-defined serial volumes are different from user-defined devices
(described under ''The Extended SBIOS" in the Installation Guide). User-defined
serial volumes are part of the system devices. These devices are allocated device
numbers 0 through 127. Device numbers 128 through 255 are allocated for true
user-defined devices. User-defined devices can only be accessed using unit I/O,
whereas the standard p-System file I/O capabilities can be used with system
devices such as user-defined serial volumes.
PRINTABLE CHARACTERS
This entry is used to determine which character codes will be echoed to the
console. Any code, from a to 255 may be defined as an echo able code.
SETUP requires input in the form of a list of decimal values separated by commas
or double periods. The values separated by commas correspond to the ASCII
characters that will be echoed to the console. The double periods indicate that all
values between the two indicated numbers are included (for example, 32 •• 126
includes the values 32, 126, and all values between them).
The typical values will be:
13, 32 •• 126
(13 is carriage retum, 32 •• 126 are the standard printable characters).
must always be present.

IV-24

The value 13

Users' Manual Supplement, Version IV
Installation Guide

SEGMENT ALIGNMENT
This value indicates a number of bytes. The p-System is instructed to load code
segments into memory starting at locations which are multiples of this number.
Most systems require no special segment alignment and the values 0 or 1 indicate
this. The 8086 based systems, for example, require a value of 16 here.

IV-25

Users' Manual Supplement, Version IV
Installation Guide

IV.4

Installing Turtlegraphica

IV .4.1

In troduction

Turtlegraphics has been designed to facilitate the development of portable graphics
applications. Turtlegraphics is distributed in two forms. Some systems are
distributed with Turtlegraphics already configured into the SYSTEM.LIBRARY and
ready to run. Turtlegraphics is also sold in an adaptable form. This document
describes how to install adaptable Turtlegraphics on your system.
The adaptable Turtlegraphics package is contained in the following 7 files:
GRAFIX2.CODE
GRAFIX4.CODE
USRGRAFS. TEXT
USRGRAFS.CODE
SYSTEM.FONT
EXERCISE2.CODE
EXERCISE4.CODE
EXERCISE.TEXT

{ A linkable Turtlegraphics Unit for
systems using 2-word real numbers }
{ A linkable Turtlegraphics Unit for
systems using 4-word real numbers}
{ A skeleton graphics initialization
unit}
{ A dummy graphics initialization unit
for systems with no special setup
requirements }
.
{ A data file containing the default
character font }
{ A test suite designed to exercise
your graphics I/O implementation
on systems using 2-word real numbers}
{ A test suite designed to exercise
your graphics I/O implementation
on systems using 4-word real numbers }
{ Source program for low level routine
test program }

To install Turtlegraphics on your p-System it is necessary to write a collection of
low-level graphics routines in assembly language and link them into one of the
GRAFIX files. These routines perform simple functions such as setting a point to
a specific color, or drawing a line segment. Turtlegraphics builds upon these
simple routines to provide higher level services to UCSD Pascal, BASIC, and
FORTRAN. If you are not already familiar with Turtlegraphics, you should stop
and read its description in Chapter III of this supplement for your particular
hardware. Section IV .4.2 below explains these low-level routines and the structures
they manage.· Section IV.4.2 also provides some implementation hints intended to
help you get the best performance from your system.
Some systems require special initialization prior to performing graphics I/O. For
example, it is often necessary to disable a hardware character generator on
memory-mapped displays before you can write to individual screen picture elements
IV-26

Users' Manual Supple men t, Version IV
Installation Guide

(pixels). Similarly, at the end of graphics I/O it is sometimes necessary to
perform special operations to restore the system display to normal operation.
Such initialization and termination is handled by the initialization and termination
code of the USERGRAPHICS unit. If your system requires some sort of graphics
initialization or finalization you will have to develop a custom USERGRAPHICS
unit. Section IV.4.3 describes how to tailor the supplied unit to suit your
requirements.
If your system requires no special configuration to perform
graphics I/O skip Section IV.4.3 and use the dummy unit supplied.
The file *SYSTEM.FONT contains a dot matrix character representation that is
used by the Turtlegraphics routines WChar and WString. Se.ctionIV.4.4 describes
the structure of SYSTEM.FONT and how to build a custom version. It is strongly
recommended that you do not replace the default file until the rest of
Turtlegraphics is working. The EXERCISE program and Turtlegraphics' error
handlers expect a valid font to be available!
Section IV.4.5 describes the ways Turtlegraphics may be libraried into a p-System.
It also describes the use of the EXERCISE program in debugging a Turtlegraphics
adaptation.

IV-27

Users' Manual Supplement, Version IV
Installation Guide

IV.4.2

Graphics I/O Routines

The Turtlegraphics unit is created by linking seven assembly code I/O routines into
either GRAFIX2.CODE or GRAFIX4.CODE. These routines interact not only with
the system display, but also with a collection of data structures that describe the
state of Turtlegraphics.
N one of the routines described in this section need to perform range-checking on
the parameters passed, EXCEPT for Draw Line. When any of these routines
(except Draw Line) are to be called, Turtlegraphics performs the appropriate rangechecking beforehand.
The following subsections describe the syntax and semantics of these routines:

Procedure Query Environment (val" OisplayOesc: OisplayRec);
Turtlegraphics uses this procedure to initialize the parameters that describe the
target con figuration. Query En vironment is passed a pointer to a record that
describes the machine-dependent aspects of the system. ALL the fields must be
filled by this routine. The Pascal description of the record below comes from
T urtlegraph ics.
DisplayRec =
record
XPixelCnt: integer; {number of pixels in the x direction
on the actual display}
YPixelCnt: integer; {number of pixels in the y direction
on the actual display}
MaxColor: integer; {maximum valid color number}
AspectX: integer;
AspectY: integer; {a pair of integers such that
the ratio: AspectX/AspectY, is the
aspect ratio of the actual physical
display}
CharHeight: integer;
CharWidth: integer; {specifies the height and width of
characters generated by SYSTEM.FONT
in pixels. For the SYSTEMFONT
shipped, the default is ax8}
TargetStamp: integer; {identifies the current target
machine configuration. Used as a
validity check by LOADFIGURE,
GETFIGURE, and PUTFIGURE }
end;

IV-28

Users' Manual Supplement, Version IV
Installation Guide

Function Figure Size (Screen: ScreenPtr): Integer;
This function tells Turtlegraphics the number of words required to store the figure
described by the indicated ScreenRec on the target machine. This function is
called by CREATE FIGURE when an application dynamically creates a figure. The
size of the figure -varies. Typically it is a function of the figure area times the
number of colors available.
The encoding of user-created figures is completely managed by the low-level
routines you are writing. You may elect to encode your figures for maximum data
compression if your applications store many figures.
You may encode for
maximum update efficiency, if you have a great deal of available storage.
On systems with large physical memory capacity, you may elect to store the first
several user figures outside of the Stack/Heap address space. In that situation,
the figure size can be zero.
The type ScreenPtr is a pointer to a Pascal record that describes the state of a
Turtlegraphics figure.
There is one screen description record for every
Turtlegraphics figure, including the actual display.
ScreenPtr
ScreenRec

record

= "ScreenRec;
=

Valid: ScreenPtr;

{pointer should always be a self
reference when figure is valid}
FigPtr: "'fig; {pointer to the figure's loen in memory;
a nil pointer indicates that the record
describes the actual display}
Color: integer; {current pen color}
Backgnd: integep {current turtle background color}
Mode: integer; current turtle drawing mode}
{the next four values delimit the viewport by pixel values:}
MinXPix: integer;
MinYPix: integer;
MaxXPix: integer;
MaxYPix: inte ere
XPix: integer; turtle pixel x position}
YPix: integer; turtle pixel y position}
TargetS tamp :in teger;
{target machine stamp which identifies the
machine configuration upon which the figure
was created; it is updated only by low-level
routines}
Size: integer; {size of the figure in words}
IV-29

Users' Manual Supplement, Version IV
Installation Guide

XPos: real; !turtle x posn in display scale unitsl
YPos: real; turtle y posn in display scale units}
Heading: real; {current orientation of the turtle}
ScaleS tamp: integer;
{Specifies the scale -generation value
for which XPos and YPos are valid}

end;
F unction Read Screen Pixel
(Pointer: -ScreenPtr;
XPixel, VPixel: Integer): Integer;
The Read Screen Pixel function returns the color of the pixel at the specified
location in figure. The XPixel and YPixel parameters give the pixel location.
Turtlegraphics checks the range on all calls to this routine. If the FigPtr in the
indicated screen record is nil, then the function should retum the state of the
actual display.
-

Procedure Set_Screen_Pixel (Pointer: ScreenPtr;
XPixel, VPixel: Integer;
Shade: Integer);
The Set_Screen_Pixel procedure sets the pixel at (XPixel, YPixel) to the designated
color. Shade specifies the color value. If the FigPtr in the indicated screen
record is nil, then the procedure should modify the actual display.

Procedure Comp Screen Pixel (Pointer: ScreenPtr;
XPixel, VPixel: Integer);
The Comp Screen Pixel procedure complemen ts the pixel at (XPixel, YPixel).
Shade specifies the color value.
If the FigPtr in the indicated screen record is
nil, then the procedure should modify the actual display.
The definition of complement is left to the discretion of the implementor for a
given target machine, given the following constraints: Complementing a pixel must
result in a different unique color, the complement of which is the original color.
This implies that a machine which supports Turtlegraphics must have an even
number of colors in its palette, or that only an even number can be used.

Procedure Fill Color (Screen: ScreenPtr; Shade: Integer);
This procedure fills a portion of the specified screen with the designated color
value. The contents of the screen record fields MaxXPix, MinXPix, MaxYPix, and
MinYPix describe the rectangular area that is filled. The FigPtr contains a
pain ter to the area of memory in which the figure is stpred. If FigPtr is nil, the
actual display (or a portion of it) should be filled.
IV-30

Users' Manual Supplement, Version IV
Installation Guide

Procedure Draw Line (Pointer: ScreenPtr;
StartX, StartV, EndX, EndV: Integer);
Draw_Line is the most complex routine to be written for Turtlegraphics. It must
draw a line segment in the specified screen.
The starting and ending points of
the lin e segmen t are described by (StartX, StartY), (EndX, EndY). Important:
T-urtlegraphics does no range checking on the line segment! The implementor is
respon sible for computing all the points in the line segment, and ONL Y plotting
those within the viewport. (The viewport is defined by the screen record fields
MaxXPixel, MaxYPixel, MinXPixel and MinYPixel). In addition, the points on the
line must be plotted using the PenColor and Mode specified in the screen record.
The valid mode values and their meanings are described below:

const

nap = 0;
substitute = 1;
overwrite = 2;
underwrite = 3;
complement
4;

=

If the current mode is nap, drawline is NOT called.
Substitute mode calls for every visible point on the line
unconditionally plotted.

segment to be

Overwrite, for the purposes of drawline, is the same as Substitute.
Underwrite mode indicates that visible points on the line segment are plotted only
if the pixel at that location is currently set to the Backgnd color, as described in
the screen record.
Complement mode indicates that the visible points on the line segment should be
co mple men ted using the definition of complement used by the Camp_Screen_Pixel
procedure.
The performance of Turtlegraphics is strongly influenced by the efficiency of these
routines. It is recommended that every effort be made to optimize their
operation. Computing the line trajectory and then only performing simple addition
to determine the locus of the next point is a good way to minimize computing. A
"psuedo-Pascal" procedure below outlines how Draw_Line might be structured:

IV-31

Users' Manual Supplement, Version IV
Installation Guide

procedure DrawL ine

- (Screen: ScreenPtr;
StartX, StartY, EndX, EndY: integer);
var Temp, X, Y, OeltaX, DeltaY, Cnt,

Xlnc, XResidue, XCorrecti on ,
YInc, YResidue, YCorrection: integer;
DXNeg, DYNeg: Boolean;
procedure exchange xy;

begin
Temp := StartX;
StartX := EndX;
EndX : = Temp;
DeltaX : = -OeltaX;
Temp := StartY;
StartY := EndY;
EndY : = Temp;
DeltaY := -OeltaY;
DXNeg := not DXNeg;
DYNeg : = not DYNeg;
end;
procedure updateyix (px, py: integer);

begin
with Screen'"
do begin

if (px) = MinXPix) and (px< = MaxXPix) and
(py) =MinYPix) and (py< =MaxYPix)
then
case mode of
substitute, overwrite:
set_screenyixel(Screen,px,py ,color);
underwrite:
if read_screenyixel(Screen,px,py) =backgnd
then set screen pixel(Screen,px,py,color);
complement:comp screen pixel(Screen,px,py);
end;
end;
end;
begin

Del taX : = EndX - S tartX;

IV-32

Users' Manual Supplement, Version IV
Installation Guide

DeltaY := EndY - StartY;
DXNeg : = Del taX (0;
DYNeg : = DeltaY (0;
if DeltaX = 0 then {vertical line}
begin
if DYNeg then exchange xy;
for Y:= StartY to EndY do updateyix (StartX, Y)
end
else if DeltaY = 0 then {horizontal line}
begin
if DXNeg then exchange xy;
for X: = 5 tartX to EndX do updateyix (X, StartY)
end
else if abs(DeltaY) > abs(DeltaX) then
{abs(slope» 45 degreeS!
-begin
if DYNeg then exchange xy;
{substitute for fractions:}YInc := abs«64 * DeltaY) div DeltaX);
{using binary fixed point arithmetic operations:}
YCorrection : = YInc mod 64 + 1;
YInc : = YInc div 64;
Y := StartY;
X := StartX;
YResidue : = 0;
Cnt := 0;
while Y (= EndY;
do begin
updateyix (X, V);
Y:= Y+l;
Cnt : = Cnt+ 1;
if Cnt= VIne then
if YResidue > 64 then
begin
Cnt := Cnt -1;
YResidue : = YResidue - 64
end
else
begin
YResidue : = YResidue + YCorrection;
Cnt := 0;
if DXNeg then X := X-I
else X := X + 1;
end;
IV-33

Users' Manual Supplemen t, Version IV
Installation Guide

end;
end
else {abs(slope)< = 45 degrees}
begin
if OXNeg then exchange;
{substitute for fractions:}
XInc: =abs«64 * OeltaX) div OeltaV);
{using binary fixed point arithmetic operations:}
XCorrection : = XInc mod 64 + 1;
XInc : = XInc div 64;
X := StartX;
V := StartV;
XResidue : = 0;
Cnt := 0;
while X <= EndX
do begin
update.J>ix (V, X);
X := X+l;
Cnt : = Cnt+l;
if Cnt= Xlnc then
if XResidue > 64 then
begin
Cnt : = Cnt -1;
XResidue : = XResidue - 64
end
else
begin
XResidue := XResidue + XCorrection;
Cnt := 0;
if OVNeg then V := V-I
else V : = V + 1;
end;
end;
end;
end;

IV-34

Users' Manual Supplement, Version IV
Installation Guide

IV .4.3

Graphics System Inl tialization

It is frequently necessary to perform some special operations to ready a system to
display graphic information. On some systems, for example, the display hardware
must be switched into a different mode. Similarly, at the termination of graphic
I/O, it is often necessary to perform some operations to restore the system to
normal operation.
Turtlegraphics addresses this situation by expecting a unit called USERGRAPHICS
to be in *SYSTEM.LIBRARY. This unit has one procedure,

procedure Hardware_config;
When Turtlegraphics is performing initialization it calls Hardware config. At the
end of a program, any termination code present in the USERGRAPHICS unit is
executed.
Turtlegraphics is shipped with a skeleton version of USERGRAPHICS in the file
USRGRAFS. This may be used if no' special initialization or termination are
required. If your system requires special configuration, you can write your own
USERGRAPHICS unit. The only requirement is that USERGRAPHICS be in
*SYSTEM.LIBRARY, and that the FIRST procedure in its interface section must be
called Hardware_config.

IV-35

Users' Manual Supplement, Version IV
Installation Guide

IV.4.4

Turtlegraphics Character Fonts

Turtlegraphics allows programs to label figures by calling two special routines,
WChar and WString. These routines draw characters in figures by using a table
stored in a file called *SYSTEM.FONT.
The standard system is shipped with a character font that contains 128 ASCII
codes, sim ilar in style to those on the some personal computers. Each character
occupies an area 8 pixels high by 8 pixels wide. This character size may be
inappropriate to some displays. On high resolution displays, such characters are
too small. On low resolution displays, it may be desirable to use a 5x7 character
matrix.
To replace the default font with one of your own design, you must first be sure
that your version of the function Query Environment initializes the display record
fields CharHeight and CharWidth to the proper values. You must then generate a
new table and save it on the boot disk as SYSTEM.FONT.
A Font Structure

Turtlegraphics reads the font table as a I-dimensional packed Boolean array. To
draw a character, it computes the index of the first bit of a character as follows:
index: = ord(character)

*

CharHeight * CharWidth;

It then displays the characters, using an algorithm similar to:

for x: =a to CharWidth - 1
do for y: =a to CharHeight - 1
do if font[index + x*CharHeight + y] then
setyixel(screen, x+turtle_x, y+turtle_y, 1)
else
setyixel(screen, x+turtle_x, y+turtle_y, 0);
Therefore, the font table is designed like a

packed array [0 •• 127, O•• CharWidth-1, O•• CharHeight] of Boolean
,Do not use such a declaration to create your character font in Pascal! Pascal
aligns all arrays (packed arrays included) so that all rows and columns begin on
word boundaries. This will cause you problems if the prodllct of CharHeight and
CharWidth is not evenly divisible by 16!

IV-36

Users' Manual Supplement, Version IV
Installation Guide

IV .4.5

Linking and Lihrarying Turtlegraphies

Once you have written the low-level graphics I/o routines, you must link them into
. one of the GRAFIXx.CODE files to produce a complete Turtlegraphics unit. The
standard p-System Linker will do the job quite nicely. Select either
GRAFIX2.CODE or GRAPHIX4.CODE to host your linking, depending on the real
number size of your P-machine. The output file should be called TURTLE.CODE.
To run programs that USE TURTLEGRAPHICS, be sure SYSTEM.FONT is on the
boot disk. Also, be sure that *USERLIB. TEXT indicates where TURTLEGRAPHICS
and USERGRAPHICS may be found, or include both units in *SYSTEM.LIBRARY.

Exercising TURTLEGRAPHICS
Included in the adaptable Turtlegraphics package are two exercise programs,
EXERCISE2.CODE and EXERCISE4.CODE. Both are created from the source in
EXERCISE.TEXT. They are provided to help you debug your low-level graphics I/O
routines. They are programs written in Pascal, and are designed to exercise
progressively more sophisticated aspects of your routines.
The exercise is divided into two main sections. The first section tests graphics
I/O to the actual display. The second half runs a similar set of test on usercreated figures, and then copies the figures to the actual display for your
examination. The paragraphs that follow explain the operation of the exercises.

Actual Display Set and Clear Pixel Test
This test should display a set of colored, dotted lines horizontally across the
display, drawing a pair from left to right with each pass. The test should end
when it has cycled through all the colors available on your display. It will then
query you to see that it has determined the number of available colors correctly.
F or this and all subsequent queries, affirm a correct result by preSSing 'Y' (either
upper or lower case). Any other character is ,considered a negative response, and
the exercises will terminate.

IV-37

Users" Manual Supplemen t, Version IV
Installation Guide

Actual Display Fill Color Teats
The next set of exercises tests Fill Color. First the system calls Fillscreen in all
the valid colors for your system. You should be careful to be sure that
Set_screenyixel uses the same color values as Fill_Color.
The next phase of this test should set the screen to color a and then display a set
of overlapping rectangles from the lower left hand comer of the display to the
upper right, using all the available colors. This is a test of windowing in
F ill Color.
The screen for a 4-color system is shown below:

IV-38

Users' Manual Supplement, Version IV
Installation Guide

Actual Display Line-Drawing Exercises
The next portion of the exercises are designed to check the Draw line routine.
First a set of radial lines are drawn from the center of the screen-: Thirty-six
(36) radials are drawn starting at the :3 O'clock position, then moving
counterclockwise around the center point. This behavior is repeated for all the
non-zero colors. Again, be sure that the color assignment matches both Fill Color
an d Se t_screen"'pixel. A sample copy of the sort of display created by thiS test
appears in the figure below:

1V-39

Users' Manual Supplement, Version IV
Installation Guide

The next part of the tests check to see if Draw_line respects the viewport of the
display. The system issues the same commands as it did on the previous tests, but
this time the viewport is restricted to a small rectangle in the center of the
display_ The result should be that the lines should stop at the periphery of the
rectangle, rather than continuing to their previous end points. The figure below
show how the display should appear when the test in complete:

IV-40

Users' Manual Supplement, Version IV
Installation Guide

The last line-drawing test on the actual display is performed only on systems with
more than two colors. This checks the update modes for line drawing. A small
rectangular area in the middle of the display is shaded. Then the same set of
radials as before are drawn in each of the modes. The expected effects for each
mode are summarized here:
Mode 0
In Nap mode nothing else should appear.
Modes 1 and 2
Both Substitute and Overwrite modes should draw lines
over the top of the rectangle and beyond.
Mode 3
Underwrite mode should not alter the center rectangle.
Radials should be visible from the periphery of the
rectangle, continuing out to their previous end points.
Mode 4
In complement mode the radials should emerge from the
center pOint, but change color at the periphery of the
center rectangle, and terminate at the edge of the screen.

User-Created Figures Exercises
A fter testing the display, the Exercise program performs all the same operations
on user-created figures. The results of each test are indicated on the actual
display. A frame is constructed on the actual display using Fill Color. The user
figures resulting from each test are copied into this viewing frame.
All the same figures should result, except for those that tested viewports: a usercreated figure cannot contain a viewport.
We remind you that a test can prove the presence of bugs, but never their
absence! EXERCISE will not prove that your routines are error free, but if all
the tests execute successfully, your low-level routines work well enough that you
can now start using Turtlegraphics.

1V-41



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2013:06:30 08:56:39-08:00
Modify Date                     : 2013:06:30 11:35:18-07:00
Metadata Date                   : 2013:06:30 11:35:18-07:00
Producer                        : Adobe Acrobat 9.55 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:92eab9ef-051e-1a4e-8f30-2fc8d30ae29a
Instance ID                     : uuid:d6b5fc3b-bcf9-a84e-9f6d-89bb9f19a80a
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 233

EXIF Metadata provided by EXIF.tools