Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / pascal / compiler / surpas / surpas.doc < prev next >

Wrap

Text File | 1987-10-20 | 45.4 KB | 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