Olivetti M20 User manual

M 20 PERsoNmCOMPUTER
PASCAL Language
User Guide

PREFACE
This manual is produced for programmers
using the M20 to create PASCAL language
programs. The PASCAL language avail-
able on the M20 is the MS-PASCAL
developed by "Microsoft Corporation",
and which isdescribed in the "M20 PAS-
CAL Language Reference Manual". The
reference manual gives the complete
instruction set and explains other fun-
damental principles of PASCAL program-
ming.
It is assumed that the reader of
this User Guide has a working knowledge
of both The PASCAL language and PCOS.
This User Guide explains how to use the
PASCAL compiler and the linker to pro-
duce executable program files for PCOS
release 3.0, and supplies further
information concerning this particular
PASCAL implementation.
This User Guide is divided in two
parts:
Part
I - describes how to create an
executable program file
starting from a PASCAL
language source file.
Part
11 - details the functions and
procedures (contained in
two library files) avail-
able on the M20.
The following are trademarks of Ing. C. Olivetti & C.. S.p.A.:
OLICOM. GTL. OLITERM. OLIWORD, OLINUM. OLISTAT. OLITUTOR.
OLIENTRY. OLISORT. OLIMASTER.
MULTIPLAN is a registered trademark of MICROSOFI Inc.
MS-DOS is a trademark of MICROSOFI' Inc.
CPIM and CPIM-86 are registered trademarks of Digital Research
Inc.
CBASIC-86 is a trademark of Digital Research Inc.
Copyright O by Olivetti. 1983.
al1 rights rese~ed.
REFERENCES:
PASCAL Language Reference Manual
(Code 3987710
Q (O))
PCOS (Professional Computer
Operating System) User Guide
(Code 3985280
D (O)
I/0 with External Peripherals
User Guide
(Code 3982300
N (2) )
Assembler User Guide
(Code 3987670 L
(1 ) )
M20 Hardware Architecture and
Functions
(Code 4100630
W (O) )
DISTRIBUTION : Genera1 (6)
EDITION: July 1983
RELEASE: 3.0
PUBLICATION ISSUED BY:
Ing.
C. Olivetti 8 C., S.p.A.
Direzione Documentazione
77, Via Jervis
- 10015 IVREA (Italy)

PREFACE
This manual is produced for programmers
using the M20 to create PASCAL language
programs. The PASCAL
. language avail-
able on the M20 is the MS-PASCAL
developed by "Microsoft Corporation",
and which is described in the "M20 PAS-
CAL Language Reference Manual". The
reference manual gives the complete
instruction set and explains other fun-
damental principles of PASCAL program-
ming.
It is assumed that the reader of
this User Guide has a working knowledge
of both The PASCAL language and PCOS.
This User Guide explains how to use the
PASCAL compiler and the linker to pro-
duce executable program files for PCOS
release 3.0,- and supplies further
information concerning this particular
PASCAL implementation.
This User Guide is divided in two
parts:
Part
I - describes how to create an
executable program file
starting from a PASCAL
language source file.
Part
Il - details the functions and
procedures (contained in
two library files) avail-
able on the M20.
The following are trademarks of Ing. C. Oliveiii & C.. S.p.A.:
OLICOM. GTL, OLITERM. OLIWORD. OLINUM, OLISTAT, OLITUTOR.
OLIENTRY. OLISORT. OLIMASTER.
MULTIPLAN is a registered trademark of MICROSOFT Inc.
MS-OOS is a trademark of MICROSOFI Inc.
CPIM and CPIM-86 are registered trademarks of Digital Research
Inc.
CBASIC-86 is a trademark of Digital Research Inc
Copyright
O by Olivetti. 1983.
al1 rights reserved.
REFERENCES:
' I)
PASCAL Language Reference Manual
(Code 3987710
Q (O))
PCOS (Professional Computer
Operating System) User Guide
(Code 3985280
D (O)
210 with External Peripherals
User Guide
(Code 3982300
N (2))
Assembler User Guide
(Code 3987670 L (1
)
M20 Hardware Architecture and
Functions
(Code 4100630
W (O) )
DZSTRIBUTZON : Genera1 (G)
EDZTZON: July 1983
RELEASE: 3.0
Ing.
C. Olivetti & C-, S.p.A.
Direzione Documentazione
77, Via Jervis
- 10015 IVREA (Italy)

CONTENTS
PART I
1. TNTRODUCTION
PROGRAMMING IN PASCAL
ON THE M20
THE M20 PASCAL PACKAGE
SYSTEM REQUIREMENTS
ABOUT THIS .MANUAL
NOTATION CONVENTION
2. PROGRAM DEVELOPMENT
CREATING AN EXECUTABLE FILE
PROGRAM DEVELOPMENT
SAMPLE SESSION
CREATING AN M20 PASCAL
SOURCE PROGRAM
COMPILING YOUR M20
PASCAL PROGRAM
LINKING YOUR M20
PASCAL PROGRAM
EXECUTING YOUR M20
PASCAL PROGRAM
SAMPLE SESSION LOG
3. THE PASCAL COMPILER
INTRODUCTION
COMPILER ACTION
PASl
PARAME'TER SPECIFICATION
PASl COMPZLER SWITCHES
ERRORS AND WARNINGS
PAS2
PAS3
DISK SPACE
4.
' THE LINK COMMAND
INTRODUCTION
USING "~asìnk"
THE LINK COMMAND 4-2
COMMENTS 4-4
MINIMUM COMMAND ELEMENTS 4-5
THE KEYWORDS 4-6
MULTI-FILE KEYWORDS
FILE KEYWORDS
VALUE KEYWORDS
STRING KEYWORDS
SIMPLE KEYWORDS
BLOCK KEYWORDS
KEYWORD ORDER
ERRORS
ALTERNATE STACK/HEAP SEGMENTS
PLOADING PASCAL PROGRAMS
5. LIBRARIES
INTRODUCTION
MLIB
M20 LIBRARIES
iii

USING THE M20 PASCAL LIBRARY 5-4
USING GRA.PHICS 5-4
PART
11
6. INTRODUCTION T0 THE M20 PASCAL
LZBRARY
INTRODUCTION
FUNCTION RESULTS
FUNCTIONAL GROUPS 6-1
BYTESTREAM 1/0 FUNCTIONS 6-2
BLOCK TRANSFER FUNCTIONS 6-3
STORAGE ALLOCATION FUNCTIONS 6-3
dhexlong
dhexword
directory
diskfree
dlong
dnurnw
dstring
error
getbyte
getdate
getlen
TIME AND DATE FUNCTIONS ,6-3
getposition
IEEE-488 FUNCTIONS
ERROR PROCEDURE
MISCELLANEOUS FUNCTIONS 6-5
7. THE M20 PASCAL LIBRARY
!
bclear
bmove
bootsys
bset
bwset
checkvol
closedevice
closefile
crlf
dhexdbyte
getstatus
gettirne
getvol
ilninput
ipoll
iprint
ireset
iset
isrq0
isrql
iwrite
lookbyte

maxsize
newabsanyseg
newabsolute
newlargestblock
newsameseg
opendevice
openfile
parsename
pdispose
peof
pnew
pseek
putbyte
readbytes
readline
remove
rename
resetbyte
sdevtab
search
setcontrol
setdate
setsysseg
settirne
setvol
stickynew
stringlen
writebytes
8. INTRODUCTION T0 GRAPHICS
INTRODUCTION
SUMMARY OF FEATURES
CONCEPTS
FLINCTIONAL GROUPS
ERRORS
DEFAULT CONDITIONS
9. THE M20 PASCAL GRAPHICS
LIBRARY
CloseGraphics
CloseViewTrans
Escape
GDP
GraphCursorRel
GraphPosAbs
GraphPosRel

InqGraphCursor
InqGraphPos
InqPixel
1nqPixelArray
InqPixelCoords
InqTextCursor
1nqViewArea
InqWorldCoordSpace
LineAbs
LineRel
MarkerAbs
MarkerRel
OpenGraphics
PixelArray
Polyline
Polymarker
SelectCursor
SelectGrColour
SelectTxColour
SelectViewTrans
SelectColourLogic
SetColourRep
SetGrCsrBlinkrate
. SetGrCsrShape
SetLineClass
SetTextLine
SetTxCsfBlinkrate
SetTxCsrShape
SetWorldCoordSpace
TextCursor
A. ZMPLEMENTATION CHARACTERISTICS
INTRODUCTION
ZMPLEMENTATION ADDITIONS
IMPLEMENTATION RESTRICTIONS
B. THE M20 PASCAL LIBRARY -
FUNCTIONAL LIST
BYTESTREAM 1/O FUNCTIONS
BLOCK TRANSFER FUNCTIONS
STORAGE ALLOCATION FUNCTIONS
TIME AND DATE FUNCTIONS
IEEE-488 FUNCTlONS
ERROR PROCEDURE
MISCELLANEOUS FUNCTIONS
C. M20 PASCAL GRAPHICS LIBRARY -
FUNCTIONAL LIST
TRANSFORMATION AND CONTROL
GRAPHICS OUTPUT
GRAPHICS ATTRIBUTES
D. SYSTEM ERRORS

E. M20 - RS-232-C DEVICE
PARAMETER TABLE
F. DEVZCE 1D (DID) ASSIGNMENTS
G. VOCABULARY
H. ASC11 CODE
vii

1. INTRODUCTION

ABOUT THIS CHAPTER
This chapter is a brief introduction to the M20 PASCAL package. This
chapter also provides an overview of this user guide.
CONTENTS
PROGRAMMING ZN PASCAL
ON THE M20
THE M20 PASCAL
PACKAGE
SYSTEM REQUIREMENTS
ABOUT THIS MANUAL
NOTATION
CONVENTION

INTRODUCTION
PROGRAMMING INPASCAL ON THE M20
The M20 PASCAL language is a compiled language. This means that a PASCAL
language program must be written in an Editor environment; on the M20
this can be done in the Video File Editor environment which is described
in the "M20 PCOS (Professional Computer Operating System) User Guide".
This edited version of the program containing PASCAL statements is known
as the source file. The structure of the source file and the PASCAL
language as implemented on the M20 are detailed in the "M20 PASCAL
LANGUAGE Reference Manual". This user guide details al1 the subsequent
steps required before the program can be successfully executed.
The next step is to compile the program using the PASCAL compiler. The
PASCAL compiler takes a source file in input and creates a new file
called the object file.
The fina1 step in creating an executable load file is to link object
files using the LINK command. LINK takes one or more object files in
input and creates an executable binary load file. Note that object files
created using other computer languages can be LZWKed to object files out-
put by the PASCAL compiler.
THE M20 PASCAL PACKAGE
The M20 PASCAL package contains the PASCAL compiler, the LINK command,
and the Video File Editor mentioned above. Also included in the package
is the MLIB command for creating library files of object modules. The
package. also includes other data files required by the compiler and
library files of object modules which implement rea1 number arithmetic
and for interfacing some of the PCOS system calls and the routines of the
M20 graphics package.
SYSTEM REQUIREMENTS
The Olivetti PASCAL compiler will run on any M20 with a minimum of 384K
bytes of random access memory. For easier operation, an M20 with two
floppy disk drives or one floppy disk drive and a hard disk is recom-
mended.

ABOUT THIS MANUAL
Part one of this manual (chapters 1-5 ) describes the operation of the
M20 PASCAL Compiler and ttie M20 linker from the most rudimentary pro-
cedure~to more advanced topics that may be of interest only to experi-
enced programmers. 1t isassumed however that the reader has a working
knowledge of both the PASCAL language and PCOS.
Chapter two "Program Development" describes the process of program
development. This chapter includes a sample session which provides a
step-by-step description of al1 the stages that follow the writing of a
program. This chapter is aimed primarily at users who are new to pro-
gramming in PASCAL.
Chapters
3 and 4 are complete descriptions of the compiler and the linker
respectively. These two chapters are self contained and experienced pro-
grammers may want read these chapters right from the start.
Chapter 5 discusses the use of library files and describes the MLIB com-
mand for creating library files.
Part two is dedicated to the functions and procedures contained in the
two library files available inthe M20 PASCAL package; the M20 PASCAL
Library and the M20 PASCAL Graphics Library.
The M20 PASCAL Library contains the functions (and one procedure) which
interface some of the PCOS system calls. The M20 PASCAL Library is
introduced in chapter 6 and the functions (and one procedure) are
described in chapter
7.
The M20 PASCAL Graphics Library contains functions and procedures which
interface the routines of the M20 Graphics package. The M20 PASCAL Graph-
ics Library is introduced in chapter 8 and the functions and procedures
are detailed in chapter
9.
NOTATIOH CONVENTION
The notation used in this manual to describe command syntax is that
defined in the "PCOS User Guide". Refer to the "PCOS User Guide" also
for rules governing file names and file identifiers in general.
PASCAL LANGUAGE USER SUIDE

I
1 2. PROGRAM DEVELOPMENT I
l
l
l
l
1 l

I
l
ABOUT THIS CHAPTER
!
This chapter provides a short introduction to program development, a mul-
I
i
tistep process which includes first writing the program, and then compil-
ing, linking, and executing
it. For a brief explanation of terms that
may be unfamiliar, see Appendix
H "Vocabulary."
I
CONTENTS
CREATING AN EXECUTABLE FILE
PROGRAM DEVELOPMENT 2-2
SAMPLE SESSION 2-4
CREATING AN M20 PASCAL 2-4
SOURCE PROGRAM
COMPILING YOUR M20 2-5
PASCAL PROGRAM
LZNKING YOUR M20
PASCAL PROGRAM
EXECUTING YOUR M20 2-1 O
PASCAL PROGRAM
SAMPLE SESSION LOG 2-1
O

PROGRAM DEVELOPMENT
CREATING AN EXECUTABLE FILE
A microprocessor can execute only its own nachine instructions; it cannot
execute source program statements directly. Therefore, before a PASCAL
program can Se executed, some type of translation, from the statements in
the source file to the machine language of the microprocessor, must
occur .
Compilers and interpreters are two types of programs that perform this
translation. Depending on the programming language in use, either or
both types of translation may be available. The M20 PASCAL is a compiled
language.
A compiler translates a source program and creates a new file called an
object file. The object file contains relocatable machine code that can
be placed and run at different absolute locations in memory.
Compilation also associates memory addresses with variables and with the
targets of GOTO statements, so that lists of variables or of labels do
not have to be searched during execution of your program.
Many compilers, including the M20 PASCAL Compiler, are what are called
"optimizing" compilers. During optimization, the compiler reorders
expressions and eliminates common subexpressions, either to increase
speed of execution or to decrease program size. These factors combine to
measurably increase the execution speed of your program.
The M20 PASCAL Compiler has a three-part structure.. The first two parts,
pass one and pass two, together carry out the optimization and create the
object code. Pass three is an optional step that creates an object code
listing. Compiling is described in more detail in Chapter
3 "The PASCAL
Compil.er".
Before a successfully compiled program can be executed, it must Se
linked. Linking is the process which computes absolute offset addresses
for routines and variables in relocatable object modules and resolves al1
external references by searching through the runtime library (and any
other specified library files). On the M20 this operation is done by the
LINK command. LZNK saves your program on disk as an executable file,
ready to run.
Zt is possible, at link time, to link more than one object module, as
well as routines written in Assembly Language or other high-leve1
languages and routines in other libraries. The LZNK command is described
in greater detail inChapter
4 "The LZNK Command".

PROGRAN DEVELOPMENT
The entii-e process of program development is outlined below. The process
is illustrated schematically in figure 2-1
l
EDITOR I
I
SOURCE
FILE (SI
PASCAL
errors?
ASSEMBLER
SOURCt
FILE (S)
r,
I
I
ASSEMBLER
I
I
I
errors?
(-) (-) LIBRARY (-)
PASCAL
EXECUTABLE
PROGRAM
PROGRAM
a
KEY
-
*
REPEAT PROCESS
REQUIRED UITHOUT
PATH ERROR-CHECKING
------
OPTIONAL
PATH
Fig. 2-1 Program Development
PASCAC CANGUAGE USER GUIDE

I
I
1 PROGRAM DEVELOPMENT
1
!
Create and edit the PASCAL (and M20 Assembler) source file(s).
Program development begins when you write a PA.5CAL program using the
Video File Editor. Use the text editor also to write any Assembly
Language routines you may plan to include.
Compile the program with the
"/D" ($DEBUG+) switch. Assemble the
Assembler source,
if any, using the M20 Assembler (ASM) comnand.
Once you have written a program, compile
it with the M20 PASCAL Com-
piler. The Compiler flags al1 syntax and l'ogic errors as
it reads
your source file. The
"/D" Compiler switch (or the corresponding
"$DEBUG+" metacommand in the source file) turns on al1 the error-
checkinq switches. These switches are equivalent to their
correspondinq metacommands and generate diaqnostic calls for al1 run-
time errors(see chapter 3 for more detail on Compiler switches). If
compilation is successful, the compiler will create a relocatable
object file.
If you have written your own Assembly Language routines (for example,
to increase the speed of execution of a particular algorithm), assem-
ble those routines with the Assembler (ASM) command. The
ASM command
is described in the "M20 ASSEMBLER User Guide".
3. Link the compiled (and assembled) object files with the runtime
li brary .
An object file output by the PASCAL compiler must be linked with the
runtime library "runtime.libH. LINK
will create an executable pro-
gram file.
4. Execute the program.
Havinq compiled the proqram with $DEBUG+
will cause the executable
program to go through extensive (and time consuming) error checking
procedures.
Repeat this process unti1 your program has successful3y compiled,
linked, and run without errors.
5. Recompile, relink, and rerun with SDEBUG-.
Repeating the process without the runtime error-checkinq switches
will reduce the anount of time and space required to execute the pro-
gram.

l
ERRORS AND WARNIN6S
i ~
PASCAL errors and warnings can be returned either by the conpiler (at
compile tine) or during program execution (run time). The codes of errors
and warnings that can be returned are detailed in Appendix
H of the
Re f erence Ma nua l.
DLIMPING FACILITIES
Throughout the process of program development the progranmer may need to
display source files, object files, etc.. This can be done using the PCOS
co~mandFLIST, which allows a number of optional features for dumping
various types of files. The FLIST command is detailed in the "M20
PCOS
User Guide".
\
SAMPLE SESSION
l
1.
This sanple session provides stey-by-step instructions for compiling an~
linking an M20 PASCAL progran.
Creating an executable M20 PASCAL progran involves the following steps:
1. Write ana save a PASCAL source file.
2. Compile your program with the M20 PASCAL coriipiler.
a) Stars pass one and enter your filenames in response to the
prompts.
b)
Run pass two of the compiler.
C) Run pass three of the compiler. (This step is optional.)
3. Link your object file to the runtime library "runtime.lib".
4. Execute (i.e., run) your program.
Compiler passes one and two are required. You need to run pass three
only
if need or want an object listing, which we do for this session.
This sample session makes the following assumptions:
1.
You have an P120 with a mininuili of 384K bytes of random access rnenory
and two disk drives (0: and 1 : ).
2. The sample program is already debugged, so that it will compile,
link, and execute successfull y.
?ASCAL LAYGUAGE USER GUIDE

j 3. An 05jec.t listing is required, fherefore al1 three passes of the com-
piler will Se run.
4. No conpiler switches will Se used.
, 5. There are no problems with data, code, or meinory limits.
I
I
CREATING AN M20 PASCAL SOURCE PROGRAM
Turn on your computer and load PCOS. You can create a PASCAL program
using the Vide File Editor.
A PASCAL source file should, in most cases,
have the ".pasn extension. For fhis sariiple session, ue shall use a pro-
gram called "sort.pas". sort.pas will resicie on drive 1.
COMPILING YOUR M20 PASCAL PROGRAM I
As rnentioned previously, compiling a program is either a two or three-
step process, depending on whether or not you choose to produce an object
code lisfing. For the sample session, we will run al1 three passes.
Pass One
Insert the disk containing the files "pasl.crad" and "PASKEY" in drive 0.
In response to the PCCS prompt, enter
pasl
This coanand starts pass one of the
M20 PASCAL compiler.
The compiler prints a header then prompts you with the following aessage:
- Ready diskette in default drive O
or enter new default drive number:
To this message respond by entering the number 1 icollowed by a carriage
return.
The compiler then prompts you for four filenaaes:
1. The source filenane
2. The object filename
3. The source listing filenarne
4. The object listing filenarne
Aespond to fhe prompts as described in the following paragraphs. For