home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Simtel MSDOS 1992 December
/
simtel1292_SIMTEL_1292_Walnut_Creek.iso
/
msdos
/
pascal
/
surpas.arc
/
SURPAS.DOC
< prev
next >
Wrap
Text File
|
1987-10-20
|
46KB
|
1,243 lines
.pl 66
.op
.mt 0
.mb 0
.po 5
S U R P A S
Pascal Program Development System
Version 1.0
O P E R A T I N G M A N U A L
Copyright (C) 1987
Tixaku Pty Ltd
P.O. Box 373
Wentworthville
NSW 2145
AUSTRALIA
.pa
COPYRIGHT
Copyright (C) 1987, 1988 by Tixaku Pty Ltd. All rights reserved. No
part of this publication may be copied, duplicated or otherwise
distributed, in any form or by any means, without the prior written
permission of Tixaku Pty Ltd, P.O. Box 373, Wentworthville, NSW 2145,
AUSTRALIA.
This package is NOT Public Domain nor is it FREEWARE, although its
distribution is similar to that of "freeware".
The basic difference between the license for SURPAS and that of
software that is freeware is that the use of SURPAS beyond a free
trial period, is subject to a low mandatory usage royalty payment
instead of a voluntary contribution. Unlike most commercial software
vendors, we believe that you are entitled to a test drive with our
software. On the other hand, like many commercial software vendors,
we feel that if you continue using our software you should pay us for
the privilege. The price you pay should still be fair, but it
should not be free.
Use of SURPAS (or SPAS87) beyond ten days of first use of the
program, the "free trial period", is subject to a mandatory usage
royalty payment of $20.00 (twenty dollars) per computer console
(CRT) on which it may be used simultaneously.
This usage royalty payment must be forwarded directly to Tixaku Pty.
Ltd. at the address indicated at the end of this document. The free
trial period is intended to allow you to try the program before paying
for it. If at the end of the free trial period, you decide you do not
want to pay the usage royalty, this may be done provided all copies of
the program which are or will be in your possession are never used
by you again. Even in this case they may be further distributed.
Obviously, even though payment is legally mandatory, we are relying on
your honesty, because in most cases, we do not have much capability
to enforce it. Remember that your payment will help us to afford to
develop other fine programs that you may also be interested in using.
The program SURPAS and its documentation is copyrighted by Tixaku Pty.
Ltd. We give restricted permission to make unlimited copies for your
personal use. We also give restricted permission to make unlimited
number of copies of the entire package for distribution to others.
This includes making the package available for others to download
from non-commercial electronic bulletin boards.
Distributed copies of this package must not be modified in any way,
except for dividing it up into several smaller files that must be
made available at the same time, and all copies must contain all the
files included in the list below.
No charge whatsoever, except for a nominal copying fee and the cost
of the media (diskette etc.), may be demanded or received for such
distribution.
.pa
DISCLAIMER
Tixaku Pty Ltd makes no representations or warranties with respect to
the contents hereof and specifically disclaims any implied warranties
of merchantability or fitness for any particular purpose. Further,
Tixaku Pty Ltd reserves the right to revise this publication without
obligation of Tixaku Pty Ltd notify any person of such revision.
TRADEMARKS
SURPAS, SURPAS Pascal, SURPAS is trademark of Tixaku.
MS-DOS is a trademark of Microsoft Inc.
.pa
.pn
SURPAS Pascal Operating Manual Table of contents
TABLE OF CONTENTS
0 Introduction
0.1 System requirements
0.2 The distribution package
0.3 Notations used in this manual
1 Running SURPAS
1.1 Invoking SURPAS
1.2 Command lines
1.3 The HELP command (
2 Loading, saving and naming source texts
2.1 The LOAD command
2.2 The SAVE command
2.3 The NAME command
3 The editor
3.1 Cursor movement commands
3.2 Mode selection commands
3.3 Editing commands
3.4 Block commands
3.5 Search/replace commands
3.6 The ADJUST mode
3.7 Other editor commands
3.8 Editor error messages
4 The compiler
4.1 The COMPILE command
4.2 The RUN command
4.3 The PROGRAM command
4.4 The OBJECT command
4.5 The FIND command
4.6 The WHERE command
4.7 Error handling
5 Further commands
5.2 The USE command
5.3 The MEMORY command
5.4 The ZAP command
5.5 The QUIT command
.pa
Section 0 Introduction
SURPAS is a program development package based upon the block struc
tured programming language Pascal. SURPAS supports the 8087 floating
point co-processor.
SURPAS includes all facilities required to create, edit, compile, run
and debug programs written in Pascal. The system consists of a run
time package, an on-screen editor, and a Pascal compiler, and it is
fully contained in a single program occupying only 32K bytes.
SURPAS Pascal closely follows the definition of Standard Pascal as
contained in the "User Manual and Report" by K. Jensen and N. Wirth.
In addition SURPAS Pascal offers some extensions to furthermore in
crease the versatility of the language.
This manual describes how to operate the SURPAS package. In progra
mming matters you are referred to the "SURPAS Pascal Programming
Manual".
.pa
Section 0 Introduction
0.1 System requirements
To use SURPAS the following requirements must be fulfilled by your
computer system:
. 8086 or 8088 microprocessor.
. MS-DOS operating system.
. At least one disk drive.
. At least 64K bytes of RAM available to programs.
Note that SURPAS will not run on systems with an 8080 or an 8085
microprocessor.
0.2 The distribution package
The distribution package contains the following files:
README.DOC A text file which describes the current version
of the SURPAS. Before using SURPAS please display and
read this file, for instance using a 'TYPE' command
from the operating system.
SURPAS.COM This file contains the SURPAS system itself, i.e.
SURPAS.COM the runtime package, the editor, and the Pascal com
piler.
SURPAS.ERM The error messages file. This fi!e contains a list of
error messages used by the compiler for reporting com
pilation errors.
SURPAS.HLP The help texts file. This file contains the help texts
displayed by the HELP command and by the ^J editor
command.
CPAS87.COM The 8087 version of SURPAS. This version uses the 8087
NDP (numeric coprocessor) for floating point calcula
tions, but in a!l other aspects it is equivalent to the
standard version. If your system is equipped with an
8087 co-processor, you will probably want to use this
version instead of the standard version.
INSTALL.COM The SURPAS install program. If you have got an unin
stalled version of SURPAS, use this program to confi
gure the package for use on your specific system.
INSTALL may also be used to modify a preinstalled
version to suit your individual needs. The INSTALL
program is fully self-explanatory.
INSTALL.TRM Install program data files. These files contain
INSTALL.DAT configuration data for up to 50 different computer
systems and terminals.
.pa
Section 0 Introduction
The distribution package may furthermore contain various demonstration
programs as source texts (i.e. as '.PAS' files).
.3 Notations used in this manual
Whenever the term "filename" is used it refers to a disk file name.
The general format of a disk file name is:
<drive>:<name>.<ext>
where <drive> is the disk drive identifier (A-O), <name> is any combi
nation of up to 8 letters or digits, and <ext> is any combination of
up to three letters or digits. The <name> field must always be speci
fied, whereas the <drive> field and the <type> field are optional. If
the <drive> field (and the colon following it) is omitted, the
currently logged drive is assumed. If the <ext> fie]d (and the period
preceding it) is omitted, a default extension is assumed depending on
the context.
Throughout the manual, hex numbers (numbers to base 16) are preceded
by a '$' character, e.g. $16EO.
.pa
Section 1 Running SURPAS
Section 1
Running SURPAS
1.1 Invoking SURPAS
To invoke SURPAS enter the command line:
SURPAS
If the SURPAS.COM file is not located on the currently logged drive,
first log in this drive (for instance by entering 'B:', if SURPAS is
on the disk in drive B). Once loaded the system prompts:
SURPAS V1.0 (MS-DOS version, 8086 CPU)
Copyright (C) 1987 Tixaku Pty Ltd
Include error messages (Y/N)?
Now type 'Y' to load the error message file (SURPAS.ERM), or any other
character to omit it. If you type 'Y' at this point, the compiler will
display an error message on locating an error. Other wise, only the
error number is displayed, and you will yourself have to look up the
error in the "SURPAS Pascal Programming Manual".
Following a cold-start (as described above), SURPAS may be warmstarted
from MS-DOS using the command line:
SURPAS *
This of course requires that no vital memory areas have been
overwritten by other programs run in the meantime.
1.2 Command lines
SURPAS prompts by printing two angle brackets ('>>'). Each time this
prompt appears, SURPAS is ready to accept and process a command line.
When you enter a command line, you may use the following editing keys:
BACKSPACE Backspaces one character. On most keyboards this code is
generated by pressing the key marked BS, BACK, or BACK
SPACE, or by pressing CTRL/H.
DEL Same as BACKSPACE described above. On most keyboards
this code is generated by pressing the key marked DEL or
RUBOUT.
CTRL/X Backspaces to the beginning of the line.
RETURN Terminates the input line. On most keyboards this code
is generated by pressing the key marked RETURN or ENTER.
.pa
Section 1 Running SURPAS
Below is shown a list of the commands recognized by SURPAS (each
command is described in full in the subsequent sections). All commands
may be abbreviated to their first letter.
HELP Display help texts.
LOAD Load a source text.
SAVE Save the source text.
NAME Set current file n#me.
EDIT Invoke the on-screen editor.
COMPILE Compile the source text.
RUN Run the current program.
PROGRAM Compile into a program file.
OBJECT Compile into an object file.
FIND Find a run time error.
WHERE Find error location in an include file.
DIR Display disk directory.
USE Change current logged drive and user.
MEMORY Display size of text and free memory.
ZAP Delete the source text.
QUIT Return to the operating system.
1.3 The HELP command
The HELP command is used to display help texts. Use it whenever you
are in doubt as to what to type on a command line. The command line
format of the HELP command is:
HELP <command>
Where <command> is one of the commands shown above (or the first
letter of one of them). If <command> is not specified, HELP displays
a command summary. Otherwise, it displays a complete description of
that particular command.
The HELP command only works if the SURPAS.HLP text file is present on
the disk from which SURPAS was executed. If this is not the case,
HELP displays:
No SURPAS.HLP file on disk
If you try to obtain help on an non-existing command, HELP displays:
No such help text
.pa
Section 2 Loading, saving and naming files
Section 2
Loading, saving and naming files
2.1 The LOAD command
The LOAD command is used to load a source text into the memory buffer.
The command line format is:
LOAD <filename>
The file type defaults to '.PAS'. When a file is loaded, it is appen
ded to the end of the source text already held within th, memory
buffer. On loading the file, SURPAS displays:
Loading d:filename.ext
If the file specified does not exist, SURPAS displays:
No such file
If loading the entire file would overflow the memory buffer SURPAS
displays:
File too big
For both error conditions the text already within the memory buffer
remains unchanged.
When a file is successfully loaded, the current file name is se| to
the name of that file. The current file name is used by th, SAVE,
PROGRAM, and OBJECT commands if a file name is not explici. tly
stated.
2.2 The SAVE command
The SAVE command is used to save the text held within the memory
buffer in a disk file. The command line format is:
SAVE <filename>
The file extension defaults to '.PAS'. If <filename> is omitted
entirely, the current file name is used. On saving the file, SURPAS
displays:
Saving d:filename.ext
If a file of the same name and extension exists on the disk specified
its extension is changed to '.BAK' before the new file is created (the
backup file facility may be disabled using the INSTALL program so that
duplicate files are simply deleted). If the disk directory is full,
SURPAS displays:
Directory is full
.pa
Section 2 Loading, saving and naming files
If there is not enough room on the disk to create a new file, SURPAS
displays:
Disk is full
If one of the above errors are reported, insert a new disk, log it in
using the USE command, and try SAVE again.
2.3 The NAME command
The NAME command is used to display and optionally change the current
file name. The command line format is:
NAME <filename>
If <filename> is omitted entirely, the current file name is not chan
ged, but only displayed. Otherwise the current file name is set to
<filename>. The default file extension is '.PAS'. The NAME command
ends by displaying:
Current file is d:filename.ext
.pa
Section 3 The editor
Section 3
The editor
The SURPAS on-screen editor is used to enter and edit sourc texts. The
maximum size of a source text is up to 60K bytes depending on the
amount of memory available (usually enough memory is available to
allow source texts of all 60K bytes). If a program grows to be too
large for the editor to handle it in one piece, you must break it into
one or more seperate text and use include files.
The editor is invoked using the command:
EDIT
The on-screen editor is specifically designed for use with video
displays. On entering the editor, the start of the text held within
the memory buffer is displayed on the screen. If the tex is too long
for the screen, which it usually is, then only th' first portion is
displayed. This is the concept of a "window" The whole text is there
and accessible by editor commands, but only a portion of it can be
seen through the "window" of the screen. When any editor command would
take you to a position it the text which is not displayed, the
"window" is moved to show that portion of the text.
The cursor marks a position in the text and can be moved to and
position occupied by text. The window shows the portion of text near
the cursor. To see another portion of the text, simply move the cursor.
Lines of a text may be as long as you wish, but the editor is only
able to display the first part of a line. If a line is longer than
the screen width, a '+' is displayed in the last position of the line
on the screen.
When you use the SURPAS editor, you will notice that it has a great
deal of "intelligence" built in. For instance, it updates the display
only when it has nothing else to do, i.e. only when you are not
entering commands or characters. Furthermore, when the editor is in
the process of updating the display, it still scans the keyboard for
your input. If the editor cannot keep up with your input, i.e. if
you type characters faster than the editor can process them, the
characters are stored in a "type-ahead" buffer, and once you relax,
the buffer is emptied one character at a time. Up to 64 characters
can be waiting in the "type-ahead" buffer.
To enter characters into the text you simply type them. Depending on
the current mode of operation, new characters will either be inserted
(pushing the remainder of the line to the right), or they will rep
lace old charac#ers.
.pa
Section 3 The editor
3.1 Cursor movement commands
^S Move cursor left one character.
^D Move cursor right one character.
^A Move cursor left one word.
^F Move cursor right one word.
^QS Move cursor to beginning of line.
^QD Move cursor to end of line.
^E Move cursor up one line.
^X Move cursor down one line.
^QE Move cursor to top of screen.
^QX Move cursor to bottom of screen.
^R Move cursor up one page.
^C Move cursor down one page.
^QR Move cursor to start of text.
^QC Move cursor to end of text.
3.2 Mode selection commands
^V INSERT on/off. When INSERT is on and a character is typed at
the keyboard, the remainder of the line is pushed to the
right to make room for the character. When INSERT is off
and a character is typed at the keyboard the new character
simply replaces the character under the cursor.
^Z AUTO (automatic tabulator) on/off. When the automatic tabu
lator is on, every new line will automatically start at the
same indentation as the line above.
^B TABS on/off. When TABS is on, the TAB (^I) command will
insert ASCII TAB characters into the text. Otherwise the TAB
command will insert an appropriate number of blanks to move
the cursor to the next TAB stop. Usin: ASCII TAB characters
often saves memory, but it prevents use of the ADJUST mode
to adjust the indentation of blocks of lines.
^W ADJUST mode on/off. The ADJUST mode is used to adjust the
indentation of blocks of lines. For further details see
section 3.6.
.pa
Section 3 The editor
RETURN Newline (same as ^M). This command depends on whether insert
is on, a CR/LF (carriage-return line-feed) sequence is
inserted into the text, which causes a blank line to appear,
or which breaks the current line into two if the cursor is
not at the end of the line. If AUTO is also on, the new line
will automatically start at the same indentation as the line
above. If INSERT is off, the cursor is simply moved to the
beginning of the next line.
^N Insert carriage return. Inserts a CR/LF (carriage-return
line-feed) sequence at the cursor, which causes a blank line
to appear, or which breaks the current line into two if the
cursor is not at the end of the line. The cursor does not
move.
^TAB Tabulate (same as ^I). If TABS is on, an ASCII TAB character
is inserted into the text, which causes the cursor to move
to the next multiple of eight columns. If TABS is off,
enough blanks are inserted to move the cursor to the next
multiple of eight columns. Note that TABS should be off if
you intend using the ADJUST mode to adjust the indentation
of your program lines later on.
DEL Delete character left. Deletes the character before the
cursor, and moves the cursor left one column.
^G Delete character right. Deletes one character under the
cursor. The cursor does not move.
^T Delete word. Deletes the word that starts at the current
character position (a word is any group of non-blank charac
ters). The cursor does not move.
^Y Delete a line. Deletes the entire line holding the cursor,
and scrolls the remainder of the text up one line. The
cursor moves to column one of the next line.
^Q DEL Delete to beginning of line. Deletes all characters before
the cursor on the current line.
^QY Delete to end of line. Deletes all characters after the
cusor on the current line.
3.4 Block commands
The block commands operate on blocks of text. A block is delimited by
a start block marker and an end block marker, and these are shown on
the screen as '>' and '<' in reverse. Before a block manipulation
command, you must first set a start block marker and an end block
marker, and furthermore you must make sure that the cursor is not
within the block.
^KB Set start block marker. Inserts a start block marker at the
current cursor position, and moves the cursor right one
column. If a start block marker is already set somewhere
else, it is removed.
.pa
Section 3 The editor
^KK Set end block marker. Inserts an end block marker at the
current cursor position, and moves the cursor right one
column. If an end block marker is already set somewhere
else, it is removed.
^KV Move block. Moves the marked block to the current cursor
position, i.e. copies it to the current cursor position and
removes it at its original position. The block markers are
removed. This command will not operate if the cursor is
within the marked block.
^KC Copy block. Copies the marked block to the current cursor
position. The block markers are not removed. This command
will not operate if the cursor is within the marked block.
^KY Delete block. Delete the marked block as well as the block
markers. This command will not operate if the cursor is
within the block.
^KP Print block. Outputs the marked block to the printer. This
command will not operate if the cursor is within the block.
^KH Remove block markers. Note that when you leave the editor,
using the ^KD command, the block markers are automatically
removed.
3.5 Search/replace commands
The search/replace commands are used to quickly locate and optionally
replace occurrances of a string in the text. Note that search and
replace strings cannot contain CR/LF (carriage-return line-feed) se
quences, and that the maximum length of such strings is 32 characters.
^QF Find string. On entering this command, the status line is
cleared, and a 'Find?' prompt appears in its place. Now
type the string to be found, and end by pressing RETURN. You
may use the DEL key to correct errors. Note that TAB charac
ters are displayed as '^I'. Once the string is input, the
scanning of the text starts. If a matching string is found,
the cursor is moved to the character position just after the
string. Otherwise the cursor does not move. The scan only
includes the text after the cursor. To include all of it,
type ^QR before ^QF.
.pa
Section 3 The editor
^QA Find and replace string. This command is an extended ver
sion of ^QF, which furthermore allows you to replace the
string(s) found with another string. The command will
prompt you for a find string (the 'Find?' prompt), a rep
lace string (the 'Replace with?' prompt), and an option list
(the 'Options (G,N)?' prompt). The 'G' option indicates a
global search, and the 'N' option indicates that the
string(s) found should be replaced without asking. On ente
ring options, type the letters with no delimiters in bet
ween. If the 'N' option is not selected, a 'Replace (Y/N)?'
prompt will appear each time a matching string is found, and
the cursor will move between the text and the prompt in
short intervals. Typing 'Y' will replace the string, whe
reas 'N' will leave it unchanged. If the 'G' option is
selected, the search will not stop at the first occurrance,
but continue until the entire text (after the initial
cursor positon) has been scanned, or RETURN is entered in
response to the 'Replace (Y/N)?' prompt.
^L Continue search. Repeats the last ^QF or ^QA command with
the same parameters.
3.6 The ADJUST mode
The ADJUST mode is designed to make it easy to adjust the indentation
of a line or a whole group of lines. You enter the ADJUST mode by
pressing ^W.
Once you are in the ADJUST mode, each time ^S is typed, the whole line
moves one position to the left, and each time ^D is typed, the whole
line moves one position to the right. Moving the cursor up or down,
using ^E or ^X, makes the same adjustment to lines above or below.
Note that once a direction has been chosen (either up or down), you
cannot move backwards in the opposite direction.
When the line (or group of lines) is adjusted to the desired indenta
tion, press ^W to leave the ADJUST mode.
Note that the ADJUST mode will not correctly adjust lines containing
ASCII TAB characters. Therefore, set TABS off before entering lines
that may require adjustments later on.
3.7 Other editor commands
^J Help. Displays a summary of all editor commands on the
screen. This command only works if the SURPAS.HLP file is
present on the disk from which SURPAS was started.u
^KD Terminate editor. On entering this command, the screen is
cleared and you are returned to the command mode (the '>>'
prompt). If you have been correcting an error in an include
file, it will be saved, and the original file will be
reloaded. For further details on this, see section 4.7.
.pa
Section 3 The editor
^KX Exit editor. Under normal circumstances this command does
exactly the same as ^KD. However, if you have been correc
ting an error in an include file, ^KX will not restore the
original file upon exit.
3.8 Editor error messages
Editor error messages are displayed on the top line (where the status
line is normally located). An example:
ERROR: No room to insert. Press <RETURN>
To reset from an error condition and restore the status line, press
RETURN. There are four different error messages:
No room to insert
This message is displayed if you try to insert characters when there
is no memory left.
Block not found
This message appears if you invoke a block command when no or only one
block marker is set. It will also be reported if you are within the
marked block on invoking the block command. In the latter case, simply
move the cursor outside the block, and re-enter the command.
No SURPAS.HLP file on disk
This message is displayed if the ^J (help) command is unable to locate
the SURPAS.HLP text file.
No such help text
This message is displayed if the SURPAS.HLP file does not contain an
editor command summary. Under normal circumstances you will never see
this message.
.pa
Section 4 The compiler
Section 4
The compiler
The compiler is the heart of the SURPAS Pascal language system. It is
capable of translating SURPAS Pascal, as defined in the "SURPAS Pascal
Programming Manual", into native machine code instructions.
When the compiler is invoked from a COMPILE or a RUN command, the
object code is stored directly into memory in succession of the source
text. This mode is extremely fast (up to 5000 lines are processed per
minute), and once the program is compiled it can be executed immedia
tely.Users should however note that since the system requires memory
for both source text and the object .code at the same time, it is
likely that very large programs cannot be compiled in this mode.
The PROGRAM and OBJECT commands instruct the compiler to write the
object code to a disk file. This mode is of course somewhat slower
than the above, but it requires less memory, and makes possible the
generation of '.COM' files which may be executed directly from the
operating system.
When activated from a FIND command, the compiler may be used to locate
a statement in the source text which corresponds to a specific address
in the object code, typically the address of a run-time error. This
mode is invaluable help for the debugging of a program.
4.1 The COMPILE command
When the compiler is invoked from a COMPILE command, the object is
stored directly into memory in succession of the source text. Note
that whenever you invoke the editor, the code produced by the COMPILE
command is erased. The actions performed by the COMPILE command
depends on the version of SURPAS in use.
On entry the compiler displays:
Compiling
Following a successful compilation, you are informed of the size of
the code segment, the size of the data segment, and the size of free
memory (used for the stack segment):
Code: rrrrrr bytes (aaaa paragraphs)
Data: ssssss bytes (bbbb paragraphs)
Free: tttttt bytes (cccc paragraphs)
where the numbers in parentheses are the paragraphs sizes (in hex) of
each segment. The code segment size includes both the run-time package
and the actual program code.
.pa
Section 4 The compiler
4.2 The RUN command
The RUN command is used to execute a program. If no object code is
present, the compiler is invoked to compile the program. Assuming a
successful compilation, or if the object code was already present, the
message:
Running
is output, and control is transferred to the program. When the
program ends, it automatically enters the command mode of SURPAS.
If a run-time error occurs, or if you interrupt the program by
pressing ^C, the program will terminate displaying a status message,
for instance:
EXECUTION ERROR 04 AT PC=254E Program terminated
You may then use the FIND command to locate the statement that caused
the error or was interrupted.
4.3 The PROGRAM command
The PROGRAM command is used to compile the program into a machine code
program file on a disk:
PROGRAM <filename>,<ssegmin>,<ssegmax>,<csegmin>,<dsegmin>
where <filename> is a disk file name, and <ssegmin>, <ssegmax>,
<csegmin>, and <dsegmin> are hex addresses (without the preceding '$'
character). The default file type is '.COM'. If <filename> is omitted
entirely, the current file name is used with the extension changed to
'.COM'. Any one of the four hex parameters may be omitted, for instance:
PROGRAM B:TEST,800 (only <ssegmin>)
PROGRAM ,,,CD8,12E4 (only <csegmin> and <dsegmin>)
<ssegmin> and <ssegmax> specify the minimum and maximum sizes (in
paragrahps) of the stack segment. <ssegmin> defaults to 100 hex (4K
bytes), and <ssegmax> defaults to the value of <ssegmin>. <csegmin>
and <dsegmin> specify the minimum sizes (in paragrahps) of the code
and data segments. They default to the lowest possible values. They
must not be larger than hex FFF (64K bytes), and usually they are only
specified for programs that will chain to other programs with larger
code and/or data segments.
Before compiling the program, SURPAS displays:
Compiling to d:filename.ext
On compiling the program, SURPAS also writes a copy of the runtime
package into the command file. The run-time package always occupies
the first portion of the code segment.
.pa
Section 4 The compiler
Following a successful compilation, you are informed of the size of
the code segment, the size of the data segment, and the minimum size
of the stack segment:
Code: rrrrrr bytes (aaaa paragraphs)
Data: ssssss bytes (bbbb paragraphs)
Free: tttttt bytes (cccc paragraphs)
where the numbers in parentheses are the paragraph sizes (in hex) of
each segment. One paragraph corresponds to 16 bytes. The code segment
size includes both the run-time package and the actual program code.
In SURPAS the PROGRAM command actually works in two different modes.
In the "compile" mode, it generates the object code and at the same
time writes it to the program file. This mode only requires room for
the source text and the symbol table. In the "dump" mode on the other
hand, the PROGRAM command simply dumps an already existing object code
into the program file, without actually compiling the source text.
This mode is extremely fast and only limited by the speed of your disk
system.
The PROGRAM command automatically selects the proper mode of
operation. If a COMPILE command is issued before the PROGRAM command,
the PROGRAM command realizes that the object code already exists
within memory, and thus selects the "dump" mode. On the other hand, if
no object code is present within memory prior to the PROGRAM command,
the "compile" mode is selected. Since the "dump" mode is
signi#!cantly faster than the "compile" mode, especially for large
programs, it is recommended that you always issue a COMPILE command
immediately before a PROGRAM command.
4.4 The OBJECT command
The OBJECT command is used to create object (chain) files, i.e. files
that do not contain the run-time package but only the actual program
code. Object files may only be activated through the chain procedure
of SURPAS Pascal - they cannot be executed directly from the operating
system. For further details on program chaining, please refer to the
"SURPAS Pascal Programming Manual". The command line format of the
OBJECT command is:
OBJECT <filename>
where <filename> is a disk file name. The default file type is '.CHN'
(short for chain). If <filename> is omitted entirely, the current
file name is used with its type changed to '.CHN'.
Since the memory allocation state is not changed by a call to the
chain procedure, you need not specify segment size information when
creating an object file.
It is up to you, however, to specify sufficiently large minimum
segment sizes on compiling the "root" program (using the PROGRAM
command), as the memory allocation state is established once and for
all when the "root" program is executed from the operating system.
Therefore, note the code and data segment paragraph sizes output at
the end of each object file compilation, and specify the largest
values when compiling the "root" program.
.pa
Section 4 The compiler
4.5 The FIND command
The FIND command is used to locate a statement in the source text that
corresponds to an offset address in the object code. In this mode the
compiler generates no object code. The command line format is:
FIND <offset>
where <offset> is the offset address of the statement to be located.
The offset address must be specified in hex with no preceding '$'
character. The offset address is always the true program counter
offset within the code segment.
If <offset> is omitted, the offset address of the most recent run-time
error is substituted instead. Thus, to locate the statement that
caused a run time error, simply enter a FIND comman# when the error is
reported. On entry the compiler displays:
Searching
If the offset address is passed during compilation, the compiler stops
and displays:
Target address found
Press <RETURN> to edit or <ESC> to abort
When you press RETURN the editor is invoked, and the cursor is placed
at or just after the relevant section. If you press ESC you are
returned to the command mode. If the offset address is out of range,
the compiler outputs:
Target address not found
before returning you to the command mode.
If a run-time error occurs within an overlay subroutine (a disk
resident procedure or function), the FIND command will not always
correctly locate the statement that caused the error. For a
discussion of this problem and a method to avoid it, please refer to
section 15.9 of the "SURPAS Pascal Programming Manual".
4.6 The WHERE command
The WHERE command invokes the editor, and moves the cursor to a
specific position in the text. The command line format is:
WHERE <offset>
where <offset> is a hex number (with no preceding '$' character)
specifying the offset address of the spot to be located. Whenever you
leave the editor, the offset address of the cursor is recorded as the
default <offset> value. Thus, if you use WHERE with no argument in
stead of EDIT to invoke the editor, the cursor will be moved to the
spot you left previously instead of to the beginning of the text. In
addition, when the compiler reports an error, it also records the
offset address of the error as the default WHERE argument. In this
case, a WHERE command will invoke the editor and move the cursor to
the spot in error.
.pa
Section 4 The compiler
4.7 Error handling
If an error is found during a compilation, the compiler stops and
displays an error number. If the error message file was loaded on
running SURPAS, an error message is displayed as well:
Error 04: Duplicate identifier
Press <RETURN> to edit or <ESC> to abort
On pressing RETURN, the editor is invoked and the cursor is moved to
the spot in error. You may then edit the source text in the same way
as usual. If you press ESC you are returned to the command mode.
If an error is spotted within an include file the situation is a bit
more complicated. In this case the compiler displays the name of the
file and the offset address o# the spot in error. Assuming that the
current file name is A:MAIN.PAS and that the include file name is
A:FUNCLIB.PAS. The error message might then read:
Include file A:FUNCLIB.PAS at CC=07B2
Error 25: Unknown or invalid variable identifier
Press <RETURN> to edit or <ESC> to abort
The offset address (CC) is the number of characters (in hex) read from
the file before the error occurred. If you press RETURN at this
stage, SURPAS will proceed by saving the text currently held within
memory. On doing so, it would in this case display:
Saving A:MAIN.PAS
since A:MAIN.PAS is the current file name (set through LOAD or NAME).
The file is only saved if it has not been modified since it was loaded
or saved the last time. Next thing the include file is loaded. In this
case SURPAS would display:
Loading A:FUNCLIB.PAS
Finally SURPAS will automatically invoke the editor and move the
cursor to the spot in error. You may then correct the error. If you
exit the editor through ^KD, SURPAS will automatically save the
include file and reload the original file before returning to the
command mode. In this case, the display would be:
Saving A:FUNCLIB.PAS
Loading A:MAIN.PAS
If you however exit the editor through ^KX, the include file will
remain the current file.
.pa
Section 5 Further commands
Section 5
Further commands
5.1 The DIR command
The DIR command is used to display the directory of a disk. The
command line format is:
DIR <afn>
where <afn> is an ambiguous file name as the one used in a MS-DOS DIR
command, i.e. question marks (?) and asterisks (*) may be interspersed
throughout the fi)e name and type fields.
A question mark will match any character in that position, and an
asterisk will match any combination of characters within the field in
which it is used (actually, an asterisk in the name field is equiva
lent to eigth question marks, and an asterisk in the extension field
is equivalent to three question marks).
If both the name and the extension fields are left out, leaving only
the drive identifier and a colon, then all files on that drive are
listed. If <afn> is omitted entirely, then all files of the currently
logged drive are listed.
5.2 The USE command
The use command is used to display and set the currently logged drive
(the default drive).
The command line format is:
USE <drive>
Where <drive> is a drive identifier (A-O). If <drive> is specified,
that drive becomes the default drive. Before returning to the command
level, the USE command displays the identifier of the default drive,
for instance:
Current drive is A
5.3 The MEMORY command
The MEMORY command is used to display the current memory allocation
state:
Code: rrrrrr bytes (aaaa paragraphs)
Data: ssssss bytes (bbbb paragraphs)
Free: tttttt bytes (cccc paragraphs)
The 'Code' and 'Data' fields are displayed only if an object code
version of the current program is present in memory. The numbers in
parentheses are the paragraph sizes (in hex) of each area. One para
graph corresponds to 16 bytes.
.pa
Section 5 Further commands
5.4 The ZAP command
The ZAP command erases the text held within the memory buffer, and
changes the current file name to 'WORK.PAS'. As a safety precaution,
ZAP prompts:
Are you sure (Y/N)?
Any answer but 'Y' or 'y' will leave the text unchanged.
5.5 The QUIT command
The QUIT command transfers control to the operating system. If the
source text has been edited but not saved, SURPAS prompts:
Text not saved. Quit (Y/N)?
and any answer but 'Y' or 'y' will return you to the command mode.
You may later warmstart SURPAS as described in section 1.1.
.pa
