Turbo Pascal Borland's No-Nonsense License Statement! This Software Is Protected by Both United States Copyright Law and International Treaty Provisions

Turbo Pascal Borland's No-Nonsense License Statement! This software is protected by both United States copyright law and international treaty provisions. Therefore, you must treat this software just like Q book, with the following single exception. Borland International authorizes you to make archival copies of the software for the sole purpose of backing-up our software and protecting your investment from loss. By saying, "just like a book," Borland means, for example, that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just like a book that can't be read by two different people in two different places at the same time, neither can the software be used by two different people in two different places at the ·same time. (Unless, of course, Borland's copyright has been violated.) Programs that you independently write and compile using the Turbo Pascal language compiler may be used, given away, or sold without additional license orfees. You are not required to indicate that your programs were developed using Turbo Pascal, or that they contain source code provided with Borland language products (toolboxes). The sample programs on the Turbo Pascal diskette provide a demonstration of the various features of Turbo Pascal. They are intended for educational purposes only. Borland I nternational grants you (the registered owner ofTurbo Pascal) the right to edit or modify these sample programs for your own use, but you may not give them away or sell them, alone or as part of any program, in object or source code form. You may, however, incorporate miscellaneous routines from these prograrl}s into your own programs, as long as your resulting program does not substantially duplicate all or part of the sample program in appearance or functionality. WARRANTY With respect to the physical diskette and physical documentation enclosed herein, Borland International, Inc. ("Borland") warrants the same to be free of defects in materials and workmanship for a period of 60 days from the date of purchase. In the event of notification within the warranty period of defects in material or workmanship, Borland will replace the defective diskette or documentation. If you need to retum a product. call the Borland Customer Service Department to obtain a return authorization number. The remedy for breach of this warranty shall be limited to replacement and shall not encompass any other damages, including but not limited to loss of profit. and special, incidental, consequential, or other similar claims. Borland International, Inc. specifically disclaims all other warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose with respect to defects in the diskette and documentation, and the program license granted herein in particular, and without limiting operation of the program license with respect to any particular application, use, or purpose. In no event shall Borland be liable for any loss of profit or any other commercial damage, including but not limited to special. incidental, consequential or other damages. GOVERNING LAW This statement shall be construed, interpreted, and governed by the laws of the state of California. First Edition Printed in USA 987 Turbo Pascal version 3.0 Reference Manual

TABLE OF CONTENTS

INTRODUCTION ...... 1 The Pascal Language ...... 1 TURBO Pascal ...... , ...... 1 Structure of This Manual ...... 2 Typography ...... 4 Syntax Descriptions ...... 4

Chapter 1. USING THE TURBO SYSTEM ...... 7' .COM and .CMD files ...... ,...... 7 BEFORE USE ...... ,...... 7 IMPORTANT NOTE !!! ...... 7 Files On The Distribution Disk ...... 8 Starting TURBO Pascal ...... 10 Installation ...... 12 IBM PC Screen Installation ...... 12 Non-IBM PC Screen Installation ...... 12 Installation of Editing Commands ...... 13 The Menu ...... 14 Logged Drive Selection ...... 15 Work File Selection ...... ;...... 15 Main File Selection ...... 16 Edit Command ...... 17 Compile Command ...... 17 Run Command ...... 17 Save Command ...... 17 Directory Command ...... 18 Quit Command ...... 18 compiler Options ...... 18 The TURBO Editor ...... 19 The Status Line ...... 19 Editing Commands ...... 20 A Note on Control Characters ...... 22 Before You Start: How To Get Out ...... 22 Basic Movement Commands...... 22 Extended Movement Commands ...... 25 Insert and Delete Commands ...... 26 Block Commands ...... 28 Miscellaneous Editing Commands ...... 30

TABLE OF CONTENTS The TURBO editor vs. WordStar ...... 34 Cursor Movement ...... 34 Mark Single Word ...... 34 End Edit ...... 35 Line Restore ...... 35 Tabulator ...... 35 Auto Indentation ...... 35

Chapter 2. BASIC LANGUAGE ELEMENTS ...... 37 Basic Symbols ...... 37 Reserved Words ...... 37 Standard Identifiers ...... 38 Delimiters ...... 39 Program Lines ...... 39

Chapter 3. STANDARD SCALAR TYPES ...... 41 Integer ...... 41 Byte ...... 41 Real ...... 42 Boolean ...... 42 Char ...... 42

Chapter 4. USER DEFINED LANGUAGE ELEMENTS ...... 43 Identifiers ...... 43 Numbers ...... 43 Strings ...... 44 Control Characters ...... 45 Comments ...... 46 Compiler Directives ...... 46

Chapter 5. PROGRAM HEADING AND PROGRAM BLOCK ...... 47 Program Heading ...... 47 Declaration Part ...... 47 Label Declaration Part ...... 48 Constant Definition Part ...... 48 Type Definition Part ...... 49 Variable Declaration Part ...... 49 Procedure and Function Declaration Part ...... 50 Statement Part ...... 50

ii TURBO Pascal Reference Manual Chapter 6. EXPRESSIONS ...... 51 Operators ...... 51 Unary Minus ...... 51 Not Operator ...... 52 Multiplying Operators ...... 52 Adding Operators ...... 53 Relational Operators ...... 53 Function Designators ...... 54

Chapter 7. STATEMENTS ...... 55 Simple Statements ...... 55 Assignment Statement ...... 55 Procedure Statement ...... 56 Goto Statement ...... 56 Empty Statement ...... 56 Structured Statements ...... 57 Compound Statement ...... 57 Conditional Statements ...... 57 If Statement ...... 57 Case Statement ...... 58 Repetitive Statements ...... 59 For Statement ...... 60 While statement ...... 61 Repeat Statement ...... 61

Chapter 8. SCALAR AND SUBRANGE TYPES ...... 63 Scalar Type ...... 63 Subrange Type ...... 64 Type Conversion ...... 65 Range Checking ...... 65

Chapter 9. STRING TYPE ...... 67 String Type Definition ...... 67 String Expressions ...... 67 String Assignment ...... 68 String Procedures ...... 69 Delete ...... 69 Insert ...... 69 Str ...... 70 Val ...... 70

TABLE OF CONTENTS iii String Functions ...... 71 Copy ...... 71 Coneat ...... 71 Length ...... 72 Pos ...... 72 Strings and Characters ...... 73

Chapter 10. ARRAY TYPE ...... 75 Array Definition ...... 75 Multidimensional Arrays ...... 76 Character Arrays ...... 77 Predefined Arrays ...... 77

Chapter 11. RECORD TYPE ...... 79 Record Definition ...... 79 With Statement ...... 81 Variant Records ...... 82

Chapter 12. SET TYPE ...... 85 Set Type Definition ...... 85 Set Expressions ...... 86 Set Constructors ...... 86 Set Operators ...... 87 Set Assignments ...... 88

Chapter 13. TYPED CONSTANTS ...... 89 Unstructured Typed Constants ...... 89 Structured Typed Constants ...... 90 Array Constants ...... 90 Multi-dimensional Array Constants ...... 91 Record Constants ...... 91 Set Constants ...... 92

Chapter 14. FILE TYPES ...... 93 File Type Definition ...... 93 Operations on Files ...... 94 Assign ...... 94 Rewrite ...... 94 Reset ...... 94 Read ...... 95 Write ...... 95 Seek ...... 95 Flush ...... 96 Close ...... 96

iv TURBO Pascal Reference Manual Erase ...... 96 Rename ...... 96 File Standard Functions ...... 97 EOF ...... 97 FilePos ...... 97 FileSize ...... 98 Using Files ...... 98 Text Files ...... 101 Operations on Text Files ...... 101 ReadLn ...... 101 WriteLn ...... 101 Eoln ...... 102 SeekEoln ...... 102 SeekEof ...... 102 Logical Devices ...... 104 Standard Files ...... 105 Text Input and Output ...... 108 Read Procedure ...... 108 Readln Procedure ...... ,...... 110 Write Procedure ...... 111 Write Parameters ...... 112 Writeln Procedure ...... 113 Untyped Files ...... 114 BlockRead / BlockWrite ...... 114 I/O checking ...... 116

Chapter 15. POINTER TYPES ...... 119 Defining a Pointer Variable ...... 119 Allocating Variables (New) ...... 120 Mark and Release ...... 121 Using Pointers ...... 122 Dispose ...... 124 GetMem ...... 125 FreeMem ...... 125 MaxAvail ...... 126

TABLE OF CONTENTS v Chapter 16. PROCEDURES AND FUNCTIONS ...... 127 Parameters ...... 127 Relaxations on Parameter Type Checking ...... 129 Untyped Variable Parameters ...... 130 Procedures ...... 131 Procedure Declaration ...... , 131 Standard Procedures ...... 133 ClrEol ...... 133 ClrS'cr ...... 133 Crtlnit ...... 133 CrtExit ...... 134 Delay ...... 134 Del Line ...... 134 Ins Line ...... 134 GotoXY ...... 134 Exit ...... 135 Halt ...... 135 LowVideo ...... 135 NormVideo ...... 135 Randomize ...... 135 Move ...... 136 FiIIChar ...... 136 Functions ...... 137 Function Declaration ...... 137 Standard Functions ...... 139 Arithmetic Functions ...... 139 Abs ...... 139 ArcTan ...... 139 Cos ...... 139 Exp ...... 140 Frac ...... 140 Int ...... 140 Ln ...... 140 Sin ...... 140 Sqr ...... 141 Sqrt ...... 141 Scalar Functions ...... 141 Pred ...... 141 Succ ...... 141 Odd ...... 141

vi TURBO Pascal Reference Manual Transfer Functions ...... 142 Chr ...... 142 Ord ...... 142 Round ...... 142 Trunc ...... 142 Miscellaneous Standard Functions ...... 143 Hi ...... 143 KeyPressed ...... 143 Lo ...... 143 Random ...... 143 Random(Num) ...... 144 ParamCount ...... 144 ParamStr ...... 144 SizeOf ...... 144 Swap ...... 144 UpCase ...... 144 Forward References ...... 145

Chapter 17. INCLUDING FILES ...... 147

Chapter 18. OVERLAY SYSTEM ...... 149 Creating Overlays ...... 152 Nested Overlays ...... 154 Automatic Overlay Management ...... 155 Placing Overlay Files ...... 155 Efficient Use of Overlays ...... 155 Restrictions Imposed on Overlays ...... 156 Data Area ...... 156 Forward Declarations ...... 156 Recursion ...... 156 Externals ...... 156 Run-Time Errors ...... 156

Chapter 19. IBM PC GOODIES ...... 159 Screen Mode Control ...... 160 Text Modes ...... 160 Color Modes ...... 161 TextColor ...... 161 TextBackground ...... 162 Cursor Position ...... 162 WhereX ...... 162 WhereY ...... 162

TABLE OF CONTENTS vII Graphics Modes ...... 163 GraphColorMode ...... 163 GraphMode ...... 164 HiRes ...... 164 HiResColor ...... 164 Palette ...... 165 GraphBackground ...... 166 Windows ...... 168 Text Windows ...... 168 Graphics Windows ...... 169 Basic Graphics ...... 17t Plot ...... 171 Draw ...... 171 Extended Graphics ...... 172 ColorTable ...... 172 Arc ...... 173 Circle ...... 173 GetPic ...... 173 Put Pic ...... 174 GetDotColor ...... 174 FiIIScreen ...... 175 FiIIShape Procedure ...... 175 FiIIPattern ...... 175 Pattern ...... 176 Turtlegraphics ...... 177 Back ...... 178 ClearScreen ...... 179 Forward ...... 179 Heading ...... 179 HideTurtle ...... 179 Home ...... 179 NoWrap ...... 180 PenDown ...... 180 PenUp ...... 180 SetHeading ...... 180 SetPenColor ...... 181 Set Position ...... 181 ShowTurtle ...... 181 TurnLeft ...... 181 TurnRight ...... 181 TurtleWindow ...... 182 TurtleThere ...... 183 TurtleDelay ...... 183 Wrap ...... 184 Xcor ...... 184 viii TURBO Pascal Reference Manual Ycor ...... 184 Sound ...... 185 Editor Command Keys ...... 186

Chapter 20. PC-DOS AND MS-DOS ...... 187 Tree-Structured Directories ...... 187 On the Main Menu ...... 187 Directory-related procedures ...... 189 ChOir ...... 189 MkDir ...... 189 RmDir ...... 189 GetDir ...... 189 Compiler Options '" ...... 190 Memory / Com file / cHn-file ...... 190 Minimum Code Segment Size ...... 191 Minimum Data Segment Size ...... 191 Minimum Free Dynamic Memory ...... 192 Maximum Free Dynamic Memory ...... 192 Command Line Parameter ...... 192 Find Run-time Error ...... '" ...... 192 Standard Identifiers ...... 193 Chain and Execute ...... 193 Overlays ...... 196 OvrPath Procedure ... '" ...... 196 Files ...... 198 File Names ...... 198 Number of Open Files ...... 198 Extended File Size ...... 199 File of Byte ...... '" ...... 199 Untyped Files ...... '" ...... 200 Flush Procedure ...... 200 Truncate Procedure ...... '" ...... 200 Text Files ...... 200 Buffer Size ...... '" ...... '" ...... 200 Append Procedure ...... ,...... 201 Flush Procedure ...... '" ...... 201 Logical Devices ...... '" ...... 201 I/O redirection .... ,...... 202 Absolute Variables ...... ,. 203 Absolute Address Functions ...... 204 Addr ...... 204 Ofs ...... 205 Seg ...... 204 Cseg ...... 205 Dseg ...... 205 Sseg ...... 205

TABLE OF CONTENTS ix Predefined Arrays ...... 206 Mem Array ...... 206 Port Array ...... 206 With Statements ...... 207 Pointer Related Items ...... 207 MemAvaii ...... 207 Pointer Values ...... 207 Assigning a Value to a Pointer ...... 207 Obtaining The Value of a Pointer ...... 207 DOS Function Calls ...... 208 User Written I/O Drivers ...... 209 External Subprograms ...... 210 In-line Machine Code ...... 211 Interrupt Handling ...... 214 Intr procedure ...... 215 Internal Data Formats ...... 216 Basic Data Types ...... 216 Scalars ...... 216 Reals ...... 217 Strings ...... 217 Sets ...... 218 Pointers ...... 218 Data Structures ...... 219 Arrays ...... 219 Records ...... 219 Disk Files ...... 220 File Interface Blocks ...... 220 Random Access Files ...... 221 Text Files ...... 221 Parameters ...... 221 Variable Parameters ...... 223 Value Parameters ...... 223 Scalars ...... 223 Reals ...... 223 Strings ...... 223 Sets ...... 224 Pointers ...... 224 Arrays and Records ...... 224 Function Results ...... 224 The Heap and The Stacks ...... 225 Memory Management ...... 226

x TURBO Pascal Reference Manual Chapter 21. CP/M-86 ...... 227 Compiler Options ...... 227 Memory I Cmd file I cHn-file ...... 227 Minimum Code Segment Size ...... 228 Minimum Data Segment Size ...... 229 Minimum Free Dynamic Memory ...... 229 Maximum Free Dynamic Memory ...... 229 Command Line Parameter ...... 229 Find Runtime Error ...... 229 Standard Identifiers ...... 230 Chain and Execute ...... 231 Overlays ...... 233 OverDrive Procedure ...... 233 Files ...... 235 File Names ...... 235 Text Files ...... 235 Buffer Size ...... 235 Absolute Variables ...... 236 Absolute Address Functions ...... 237 Addr ...... 237 Ofs ...... 237 Seg ...... 237 Cseg ...... 237 Dseg ...... 238 Sseg ...... 238 Predefined Arrays ...... 238 Mem Array ...... 238 Port Array ...... 239 With Statements ...... 239 Pointer Related Items ...... 239 MemAvaii ...... 239 Pointer Values ...... 239 Assigning a Value to a Pointer ...... 240 Obtaining The Value of a Pointer ...... 240 Function Calls ...... 240 User Written 1/0 Drivers ...... 241 External Subprograms ...... 242 In-line Machine Code ...... 243 Interrupt Handling ...... 245 Intr procedure ...... 245

TABLE OF CONTENTS xi Internal Data Formats ...... 246 Basic Data Types ...... 246 Scalars ...... 247 Reals ...... 247 Strings ...... 248 Sets ...... 248 Pointers ...... 249 Data Structures ...... ,...... 249 Arrays ...... 249 Records ...... 250 Disk Files ...... 250 File Interface Blocks ...... 250 Random Access Files ...... 251 Text Files ...... 252 Parameters ...... 252 Variable Parameters ...... 253 Value Parameters ...... 253 Scalars ...... 254 Reals ...... 254 Strings ...... 254 Sets ...... 254 Pointers ...... 254 Arrays and Records ...... 254 Function Results ...... 255 The Heap and The Stacks ...... 255 Memory Management ...... 256

Chapter 22. CP/M-SO ...... 259 eXecute Command ...... 259 compiler Options ...... 259 Memory / Com file / cHn-file ...... 260 Start Address ...... 261 End Address ...... 261 Find Runtime Error ...... 262 Standard Identifiers ...... 263 Chain and Execute ...... 263 Overlays ...... 265 OvrDrive Procedure ...... 265 Files ...... 267 File Names ...... 267 Text Files ...... 267 Absolute Variables ...... 267 Addr ...... 268

xii TURBO Pascal Reference Manual Predefined Arrays ...... 268 Mem Array ...... 268 Port Array ...... 269 Array Subscript Optimization ...... 269 With Statements ...... 269 Pointer Related Items ...... 270 MemAvail ...... 270 Pointers and Integers ...... 270 CPIM Function Calls ...... 271 Bdos procedure and function ...... 271 BdosHL function ...... 271 Bios procedure and function ...... 272 BiosHL function ...... 272 User Written 110 Drivers ...... 272 External Subprograms ...... 274 In;..line Machine Code ...... 274 Interrupt Handling ...... 277 Internal Data Formats ...... 278 Basic Data Types ...... 278 Scalars ...... 278 Reals ...... 278 Strings ...... 279 Sets ...... 279 File Interface Blocks ...... 280 Pointers ...... 281 Data Structures ...... 281 Arrays ...... 281 Records ...... 282 Disk Files ...... 282 Random Access Files ...... 282 Text Files ...... 283 Parameters ...... 283 Variable Parameters ...... 283 Value Parameters ...... 283 Scalars ...... 283 Reals ...... 284 Strings ...... 284 Sets ...... 284 Pointers ...... 285 Arrays and Records ...... 285 Function Results ...... 285 The Heap and The Stacks ...... 286

TABLE OF CONTENTS xiii Memory Management ...... 288 Memory Maps ...... 288 Compilation in Memory ...... 288 Compilation To Disk ...... 289 Execution in Memory ...... 290 Execution of a Program File ...... 291

Chapter 23. TURBO BCD PASCAL ...... 293 Files On the TURBO BCD Pascal Distribution Diskette ...... 293 BCD Range ...... 293 Form function ...... 294 Numeric Fields ...... 294 String Fields ...... 297 Writing BCD Reals ...... 297 Formatted Writing ...... 298 Internal Data Format ...... 298

Chapter 24. TURBO-87 ...... 301 Files On the TURBO-87 Distribution Diskette ...... 301 Writing 8087 Reals ...... 302 Internal Data Format ...... 302

Appendix A. SUMMARY OF STANDARD PROCEDURES AND FUNCTIONS ...... 303 Input/Output Procedures and Functions ...... 303 Arithmetic Functions ...... 304 File-Handling Routines ...... 304 Heap Control Procedures and Functions ...... 304 Miscellaneous Procedures and Functions ...... 305 Scalar Functions ...... 306 Directory-Related Procedures (PC/MS-DOS) ...... 306 Screen-Related Procedures and Functions ...... 306 String Procedures and Functions ...... 307 Transfer Functions ...... 307 IBM PC Procedures and Functions ...... 307 Basic Graphics, Windows, and Sound ...... 307 Extended Graphics ...... 308 Turtlegraphics ...... 308

Appendix B. SUMMARY OF OPERATORS ...... 311

xiv TURBO Pascal Reference Manual Appendix C. SUMMARY OF COMPILER DIRECTIVES ...... 313 IMPORTANT NOTICE ...... 313 Common Compiler Directives ...... 314 B - I/O Mode Selection ...... 314 C - Control C and S ...... 314 I - I/O Error Handling ...... 314 I - Include Files ...... 314 R - Index Range Check ...... 315 V - Var-parameter Type Checking ...... 315 U - User interrupt ...... 315 PC-DOS, MS-DOS Compiler Directives ...... 316 G - Input File Buffer ...... 316 P - Output File Buffer ...... 316 D - Device Checking ...... 316 F-Number of Open Files ...... 317 PC-DOS, MS-DOS, and CP/M-86 Compiler Directive ...... 317 K - Stack Checking ...... 318 CP/M-80 Compiler Directives ...... 318 A - Absolute Code ...... 318 W - Nesting of With Statements ...... 318 X - Array Optimization ...... 318

Appendix D. TURBO VS. STANDARD PASCAL ...... 319 Recursion ...... 319 Get and Put ...... 319 Goto Statements ...... 319 Page Procedure ...... 319 Packed Variables ...... 320 Procedural Parameters ...... 320

Appendix E. COMPILER ERROR MESSAGES ...... 321

Appendix F. RUN-TIME ERROR MESSAGES ...... 325

Appendix G. I/O ERROR MESSAGES ...... 327

Appendix H. TRANSLATING ERROR MESSAGES ...... 329 Error Message File Listing ...... 330

Appendix I. TURBO SYNTAX ...... 330

TABLE OF CONTENTS xv Appendix J. ASCII TABLE ...... 339

Appendix K. KEYBOARD RETURN CODES ...... 341

Appendix L.INSTALLATION ...... 345 Terminal installation ...... 345 IBM PC Display Selection ...... 345 Non-IBM PC Installation ...... 346 Editing Command Installation ...... 350

Appendix M. CP/M PRIMER ...... 355 How to use TURBO on a CP/M system ...... 355 Copying Your TURBO Disk ...... 355 Using Your TURBO Disk ...... 356

Appendix N. HELPU! ...... 357

INDEX ...... 377

xvi TURBO Pascal Reference Manual LIST OF FIGURES

1-1 Log-on Message ...... 10 1-2 Main Menu ...... 11 1-3 Installation Main Menu ...... 12 1-4 Main Menu ...... 14 1-5 Editor Status Line ...... 19

15-1 Using Dispose ...... 124

18-1 Principle of Overlay System ...... 149 18-2 Largest Overlay Subprogram Loaded ...... 150 18-3 Smaller Overlay Subprogram Loaded ...... 151 18-4 Multiple Overlay Files ...... 153 18-5 Nested Overlay Files ...... 154

19-1 Text Windows ...... 169 19-2 Graphics Windows ...... 170 19-3 Turtle Coordinates ...... 178 19-4 Turtle Coordinates ...... 183

20-1 TURBO Main Menu under DOS 2.0 ...... 187 20-2 Options Menu ...... 190 20-3 Memory Usage Menu ...... 191 20-4 Run-time Error Message ...... 192 20-5 Find Run-time Error ...... 192

21-1 Options Menu ...... 227 21-2 Memory Usage Menu ...... 228 21-3 Run-time Error Message ...... 230 21-4 Find Run-time Error ...... 230

22-1 Options Menu ...... 260 22-2 Start and End Addresses ...... 261 22-3 Run-time Error Message ...... 262 22-4 Find Run-time Error ...... 262 22-5 Memory map during compilation in memory ...... 288 22-6 Memory map during compilation to a file ...... 289 22-7 Memory map during execution in direct mode ...... 290 22-8 Memory map during execution of a program file ...... 291

L-1 IBM PC Screen Installation Menu ...... 345 L-2 Terminal Installation Menu ...... 346

TABLE OF CONTENTS xvii LIST OF TABLES

1-1 Editing Command Overview ...... 21

14-1 Operation of EOLN and Eof ...... 105

19-1 Text Mode Color Scale ...... 161 19-2 High Resolution Graphics Color Scale ...... 165 19-3 Color Palettes in Color Graphics ...... ,. 165 19-4 Color Palettes in B/W Graphics ...... 166 19-5 Graphics Background Color Scale ...... 167 19-6 IBM PC Keyboard Editing Keys ...... 186

K-1 Keyboard Return Codes ...... 343

L-1 Secondary Editing Commands ...... 353

xv;;; TURBO Pascal Reference Manual INTRODUCTION

This book is a reference manual for the TURBO Pascal system as imple mented for the PC-DOS, MS-DOS, CP/M-86, and CP/M-80 operating systems. Although making thorough use of examples, it is not meant as a Pascal tutorial or textbook, and at least a basic knowledge of Pascal is assumed. A TURBO Pascal Tutorial, called Turbo Pascal Tutor, is also available from Borland. See the catalog of Borland products at the back of this book for more information about Turbo Pascal Tutor.

The Pascal Language

Pascal is a general-purpose, high level programming language originally designed by Professor Niklaus Wirth of the Technical University of Zur ich, Switzerland and named in honor of Blaise Pascal, the famous French Seventeenth Century philosopher and mathematician.

Professor Wirth's definition of the Pascal language, published in 1971, was intended to aid the teaching of a systematic approach to computer programing, specifically introducing structured programming. Pascal has since been used to program almost any task on almost any computer and it is today established as one of the foremost high-level languages; whether the application is education, hobby, or profeSSional program ming.

TURBO Pascal

TURBO Pascal is designed to meet the requirements of all categories of users: it offers the student a friendly interactive environment which greatly aids the learning process; and in the hands of a programmer it becomes an extremely effective development tool providing both compi lation and execution times second to none.

TURBO Pascal closely follows the definition of Standard Pascal as defined by K. Jensen and N. Wirth in the Pascal User Manual and Report. The few and minor differences are described in Appendix D. In addition to the standard, a number of extensions are provided, such as:

INTRODUCTION 1 Absolute address variables Bit/byte manipulation Direct access to CPU memory and data ports Dynamic strings Free ordering of sections within declaration part Full support of operating system facilities In-line machine code generation Include files Logical operations on integers Overlay system Program chaining with common variables Random access data files Structured constants Type conversion functions

IBM PC and compatibles only:

Colors Graphics Turtlegraphics Windows Sound

Furthermore, many extra standard procedures and functions are includ ed to increase the versatility of TURBO Pascal.

Structure of This Manual

As this manual describes slightly different TURBO Pascal implementa tions, namely PC-DOS, MS-DOS, CP/M-86, and CP/M-80, the reader should keep the following structure in mind:

1: Chapter 1 describes the installation and use of TURBO Pascal, the built-in editor, etc. This information applies to all implementations.

2: T~e main body of the manual, chapters 2 through 18, describe the com mon parts of TURBO Pascal, i.e. those parts of the language which are identical in all three versions. These include Standard Pascal and many extensions. As long as you use the language as described in these chapters, your. programs will be fully portable between implementations.

2 TURBO Pascal Reference Manual 3: Chapters 19, 20, 21, and 22 describe items which have not been covered in previous chapters because they differ among implementa tions, for example special features, requirements, and limitations of each implementation. In particular, you should notice that chapter 19 explains all the IBM PC extensions such as colors, graphics, sound, windows, etc. To avoid confusion, you need only read the chapter(s) pertaining to your implementation.

Parts of chapters 20, 21, and 22 deal with technicalities such as internal data formats, interrupts, direct memory and port accesses, in-line as sembly code, user written I/O drivers, etc. It is assumed that the reader has previous knowledge of such matters, and no attempt is made to teach these things. Remember that these chapters are imple mentation dependent, so programs using techniques described there are no longer directly portable between implementations.

In fact, you need not bother with these chapters at all if your aim is to write plain Pascal code, or if portability between the different TURBO im plementations is important to you.

4: Chapter 23 describes TURBO-BCD. This is a special version of TURBO Pascal for PC-DOS, MS-DOS, and CP/M-S6 which uses binary coded decimal (BCD) arithmetic for higher precision in real operations; especial ly useful for business applications.

5: Chapter 24 describes the special 16-bit TURBO-S7 which uses the op tional SOS7 co-processor for added speed and extended range in Real arithmetic.

6: The appendices are common to all implementations and contain sum maries of language elements, syntax diagrams, error messages, details on installation procedures, an alphabetical subject index, etc.

7: Appendix N contains answers to a number of the most common questions-please read it if you have any problems.

INTRODUCTION 3 Typography

The body of this manual is printed in normal typeface. Special charac ters are used for the following special purposes:

Alternate Characters in alternate typeface are used to illustrate program examples and procedure and function declarations.

Italics Italics are used to emphasize certain concepts and terminology, such as predefined standard identifiers, parameters, and other syntax elements.

Boldface Boldface is used to mark reserved words in the text as well as in program examples.

Syntax Descriptions The entire syntax of the Pascal language expressed as Backus-Naur Forms is collected in Appendix I, which also describes the typography and special symbols used in these forms.

Where appropriate syntax descriptions are also used more specifically to show the syntax of single language elements as in the following syntax description of the function Concat:

Concat ( Stt , St2 { , StN} )

Reserved words are printed in boldface, identifiers use mixed upper and lower case, and elements explained in the text are printed in italics.

4 TURBO Pascal Reference Manual The text will explain that St1, St2, and StN must be string expressions. The syntax description shows that the word Concat must be followed by two or more string expressions, separated by commas and enclosed in parentheses. In other words, the following examples are legal (assum ing that Name is a string variable):

Conca t ( , TURBO' , , Pascal' ) Conca t ( 'TU' , 'RBO' , , Pascal' ) Concat('T', 'U', 'R', 'B', '0' ,Name)

INTRODUCTION 5 Notes:

6 TURBO Pascal Reference Manual Chapter 1 USING THE TURBO SYSTEM

this chapter describes the installation and use of the TURBO Pascal system, specifically the built-in editor .

. COM and .CMD files

Files with the extension .COM mark the executable program files in CP/M-80 and PC-DOS / MS-DOS. In CP/M-86 these will instead be marked .CMD. Thus, whenever .COM-files are mentioned in the follow ing, it should be understood as .CMD if your operating system is CP/M- 86.

BEFORE USE

Before using the TURBO Pascal you should, for your own protection, make a work-copy of the distribution diskette and store the original safely away. Remember that the User's License allows you to make as many copies as you need for your own personal use and for backup purposes only. Use a file-copy program to make the copy, and make sure that all files are successfully transferred.

IMPORTANT NOTE I!!

TURBO Pascal provides a number of compiler directives to control special runtime facilities such as index checking, recursion, etc. PLEASE NOTICE that the default settings of these directives will op timize execution speed and minimize code size. Thus, a number of runtime facilities (such as index checking and recursion) are de selected until explicitly selected by the programmer. All compiler directives and their default values are described in Appendix C. (De-selecting recursion applies to CP/M-SO only; in 16-bit versions recursion is always possible.)

USING THE TURBO SYSTEM 7 Files On The Distribution Disk

Files On The Distribution Disk

The distribution disk contains the following files:

TURBO.COM The TURBO Pascal program: compiler and editor. When you enter the command TURBO on your terminal, this file will load, and TURBO will be up and running.

TURBO.OVR Overlay file for TURBO.COM (CP/M-SO version only). Needs to be present on the run-time disk only if you want to execute .COM files from TURBO.

TURBO.MSG Text file containing error messages. Needs not be present on your run time disk if you will accept the system without explanatory compile-time error messages. Errors will in that case just print out an error number, and the manual can be consulted to find the explanation. In any case, as the system will automatically point out the error, you may find it an ad vantage to use TURBO without these error messages; it not only saves space on the disk, but more importantly, it gives you approx. 1.5 Kbytes extra memory for programs. This message file may be edited if you wish to translate error messages into another language as described in Appendix H. .

TINST.COM Installation program. Just type TINST at your terminal, and the pro gram takes you through a completely menu-driven installation pro cedure. This and the following files need not be present on your run time disk.

TINST.DTA Terminal installation data (not present on IBM PC versions).

TINST.MSG Messages for the installation program. Even this file may be translated into any language desired .

. PAS files Sample Pascal programs.

8 TURBO Pascal Reference Manual Files On The Distribution Disk

GRAPH.P IBM PC versions only. Contains the external declarations necessary to use the extended graphics and turtlegraphics routines contained in GRAPH.BIN. Only necessary on the run-time disk if you want to do tur tlegraphics.

GRAPH.BIN IBM PC versions only. This file contains the extended graphics and tur tlegraphics machine language routines. Only necessary on the run-time disk if you want to do extended or turtle graphics.

READ.ME If present, this file contains the latest corrections or suggestions on the use of the system.

Only TURBO. COM must be on your run-time disk. A fully operative TURBO Pascal thus requires only 30 K of disk space (37 K for 16-bit systems). TURBO.OVR is required only if you want to be able to exe cute programs from the TURBO menu. TURBO.MSG is needed only if you want on-line compile-time error messages. The TINST files are used only for the installation procedure, and the GRAPH files are needed only when you want to do extended graphics or turtlegraphics. The example .PAS files, of course, may be included on the run-time disk if so desired, but they are not necessary.

USING THE TURBO SYSTEM 9 Starting TURBO Pascal

Starting TURBO Pascal

When you have a copy of the system on your work-disk, enter the com mand

TURBO

at your terminal. The system will log on with the following message:

Figure 1-1: Log-on Message

N.NNX specifies your release number and [System] indicates the operating environment (operating system and CPU), for example CP IM-a6 on IBM PC. The second-to-the-Iast line tells you which screen is installed. At the moment none-but more about that later.

If you enter a Y in response to the error message question, the error message file will be read into memory (if it is on the disk), briefly display ing the message Loading TURBO. MSG. You may instead answer N and save about 1.5 Kbytes of memory. Then the TURBO main menu will appear:

10 TURBO Pascal Reference Manual Starting TURBO Pascal

Logged drive: A Work file: Main file: Edit Compile Run Save Dir Quit compiler Options Text: 0 bytes Free: 62903 bytes

Figure 1-2: Main Menu

The menu shows you the commands available, each of which will be described in following sections. Each command is executed by entering the associated capital letter (highlighted after terminal installation if your terminal has that feature). Don't press < RETURN> ; the command ex ecutes immediately. The values above for Logged drive and memory use are for the sake of example only; the values shown will be the actual values for your computer.

IBM PC users who are satisfied with the 'Default display mode' can use TURBO as it comes and may skip the following and go to page 14. If you're an non-IBM PC user, you may use TURBO without installation if you don't plan to use the built-in editor - but assuming that you do, type Q now to leave TURBO for a minute to perform the installation.

USING THE TURBO SYSTEM 11 Installation

Installation

Type TINST to start the installation program. All TlNST files and the TURBO. COM file must be on the logged drive. This menu will appear:

TURBO Pascal installation menu. Choose installation item from the following:

[S]creen installation I [C]ommand installation [Q]uit

Enter 5, C, or Q: [M]essage

Figure 1-3: Installation Main Menu

IBM PC Screen Installation

When you hit S to perform Screen installation, a menu will appear which lets you select the screen mode you want the TURBO environment to use (see Appendix L for details). When you have made your choice, the main menu re-appears, and you may now continue with the Command installation described on pages 350 pp, or you may terminate the instal lation at this point by entering Q for Quit.

Non-IBM PC Screen Installation

Now hit S to select Screen installation. A menu containing the names of the most commonly used terminals will appear, and you may choose the one that suits you by entering the appropriate number. If your terminal is not on the menu, nor compatible with any of these (note that a lot of terminals are compatible with ADM-3A), then you must perform the installation yourself. This is quite straightforward, but you will need to consult the manual that came with your terminal to answer the questions asked by the installation menu. See Appendix L for details.

12 TURBO Pascal Reference Manual Installation

When you have chosen a terminal, you are asked if you want to modify it before installation. Normally, you will answer No to this question, which means that you are satisfied with the predefined terminal installation. If you do want to modify the terminal, answer Yes, and you will be taken through a series of questions as described in Appendix L.

Now you will be asked the operating frequency of your microprocessor. Enter the appropriate value (2, 4, 6, or 8, most probably 4).

After that, the main menu re-appears, and you may now continue with the Command installation described in the next section or you may ter minate the installation at this point by entering Q for Quit.

Installation of Editing Commands

The built-in editor responds to a number of commands which are used to move the cursor around on the screen, delete and insert text, move text etc. Each of these functions may be activated by either a primary or a secondary command. The secondary commands are installed by Bor land and comply with the 'standard' set by WordStar. The primary com mands are un-defined for most systems, and using the installation pro gram, they may easily be defined to suit your taste or your keyboard. IBM PC systems are supplied with the arrows and dedicated function keys installed as primary commands as described in chapter 19.

Please turn to appendix L for a full description of the editor command in stallation.

USING THE TURBO SYSTEM 13 The Menu

The Menu

After installation, you once again activate TURBO Pascal by typing the command TURBO. Your screen should now clear and display the menu, this time with the command letters highlighted. If not, check your instal lation data.

Logged drive: A Work file: Main file: Edit Compile Run Save Dir Quit compiler Options Text: 0 bytes Free: 62903 bytes

> •

Figure 1-4: Main Menu

By the way, whenever highlighting is mentioned here, it is assuming that your screen has different video attributes to show text in different inten sities, inverse, underline or some other way. If not, just disregard any mention of highlighting.

This menu shows you the commands available to you while working with TURBO Pascal. A command is activated by pressing the associated upper case (highlighted) letter. Don't press < RETURN>, the com mand is executed immediately. The menu may very well disappear from the screen when working with the system; it is easily restored byenter ing an 'illegal command', i.e. any key that does not activate a command. < RETURN> or < SPACE> will do perfectly.

The following sections describe each command in detail.

14 TURBO Pascal Reference Manual The Menu

Logged Drive Selection

The L command is used to change the currently logged drive. When you press L, this prompt:

New drive: II

invites you to enter a new drive name, that is, a letter from A through P, optionally followed by a colon and terminated with < RETURN> . If you don't want to change, the current value, just hit < RETURN>. The L command performs a disk-reset, even when you don't change the drive, and should therefore be used whenever you change disks to avoid a fa tal disk write error.

The new drive is not immediately shown on the menu, as it is not au tomatically updated. Hit for example < SPACE> to display a fresh menu which will show the new logged drive.

Work File Selection

The W command is used to select a work file which is the file to be used to Edit, Compile, Run, eXecute, and Save. The W command will issue this command:

Work file name: -

and you may respond with any legal file name: a name of one through eight characters, an optional period, and an optional file type of no more than three characters: FILENAME.TYP

If you enter a file name without period and file type, the file type PAS is automatically assumed and appended to the name. You may explicitly specify a file name with no file type by entering a period after the name, but omitting the type.

Examples: PROGRAM becomes PROGRAM. PAS PROGRAM. is not changed PROGRAM.FIL is not changed

USING THE TURBO SYSTEM 15 The Menu

File types .BAK, .CHN, and .COM/.CMD should be avoided, as TURBO uses these names for special purposes.

When the Work file has been specified, the file is read from disk, if present. If the file does not already exist, the message New F i 1 e is is sued. If you have edited another file which you have not saved, the mes sage: Workfile X:FILENAME.TYP not saved. Save (YIN)? •

warns you that you are about to load a new file into memory and overwrite the one you have just worked on. Answer Y to save or N to skip.

The new work file name will show on the menu the next time it is updat ed, like when you hit < SPACE> .

Main File Selection

The M command may be used to define a main file when working with programs which use the compiler directive $1 to include a file. The Main file should be the file which which contains the include directives. You can then define the Work file to be different from the Main file, and thus edit different include files while leaving the name of the Main file un changed.

When a compilation is started, and the Work file is different from the Main file, the current Work file is automatically saved , and the Main file is loaded into memory. If an error is found during compilation, the file containing the error (whether it is the Main file or an include file) au tomatically becomes the Work file which may then be edited. When the error has been corrected and compilation is started again, the corrected Work file is automatically saved, and the Main file is re-Ioaded.

The Main file name is specified as described for the Work file name in the previous section.

16 TURBO Pascal Reference Manual The Menu

Edit Command

The E command is used to invoke the built-in editor and edit the file defined as the Work file. If no Work file is specified, you are first asked to specify one. The menu disappears, and the editor is activated. More about the use of the editor on pages 19 pp.

While you may use the TURBO system to compile and run programs without installing a terminal, the use of the editor requires that your ter minal be installed. See page 12.

Compile Command

The C command is used to activate the compiler. If no Main file is specified, the Work file will be compiled, otherwise the Main file will be compiled. In the latter case, if the Work file has been edited, you will be asked whether or not to save it before the Main file is loaded and com piled. The compilation may be interrupted at any moment by pressing a key.

The compilation may result either in a program residing in memory, in a .COM file, or in a .CHN file. The choice is made on the compiler Options menu described on pages 190 (PC/MS-DOS systems), 227 (CP/M-86), and 259 (CP/M-80). The default is to have the program residing in memory.

Run Command

The R command is used to activate a program residing in memory or, if the C-switch on the compiler Options menu is active, a TURBO object code file (.COM or .CMD file). If a compiled program is already in memory, it will be activated. If not, a compilation will automatically take place as described above.

Save Command

The S command is used to save the current Work file on disk. The old version of this file, if any, will be renamed to .BAK, and the new version will be saved.

USING THE TURBO SYSTEM 17 The Menu

Directory Command

The D command gives you a directory listing and information about remaining space on the logged drive. When hitting D, you are prompted thus:

Dir mask: -

You may enter a drive designator or a drive designator followed by a file name or a mask containing the usual wildcards * and ? Or you may just hit < RETURN> to get a full directory listing.

Quit Command

The Quit command is used to leave the TURBO system. If the Work file has been edited since it was loaded, you are asked whether you want to save it before quitting. compiler Options

The 0 command selects a menu on which you may view and change some default values of the compiler. It also provides a helpful function to find run-time errors in programs compiled into object code files.

As these options vary between implementations, further discussion is deferred to chapters 20, 21, and 22.

18 TURBO Pascal Reference Manual The TURBO Editor

The TURBO Editor

The bUilt-in editor is a full-screen editor specifically designed for the creation of program source text. If you are familiar with MicroPro's WordS tar, you need but little instruction in the use of the TURBO editor, as all editor commands are exactly like the ones you know from WordStar. There are a few minor differences, and the TURBO editor has a few extensions; these are discussed on page 34. You may install your own commands 'on top' of the WordStar commands, as described on page 13; and IBM PC systems come with arrows and dedicated function keys already installed. The WordStar commmands, however, may still be used.

Using the TURBO editor is simple as can be: when you have defined a Work file and hit E, the menu disappears, and the editor is activated. If the Work file exists on the logged drive, it is loaded and the first page of text is displayed. If it is a new file, the screen is blank except for the status line at the top.

You leave the editor and return to the menu by pressing Ctrl-K-D; more about that later.

Text is entered on the keyboard just as if you were using a typewriter. To terminate a line, press the < RETURN> key (or CR or ENTER or whatever it is called on your keyboard). When you have entered enough lines to fill the screen, the top line will scroll off the screen, but don't worry, it is not lost, and you may page back and forth in your text with the editing commands described later.

Let us first take a look at the meaning of the status line at the top of the screen.

The Status Line

The top line on the screen is the status line containing the following in formation:

Line n Col n Insert Indent X:FILENAME.TYP

Figure 1-5: Editor Status Line

USING THE TURBO SYSTEM 19 The TURBO Editor

Line n Shows the number of the line containing the cursor counted from the start of the file.

Coin Shows the number of the column containing the cursor counted from the left of the line.

Insert Indicates that characters entered on the keyboard will be inserted at the cursor position. Existing text to the right of the cursor will move to the right as you write new text. Using the insert mode on/off command (Ctrl-V by default) will instead display the text Overwrite. Text entered on the keyboard will then overwrite characters under the cursor instead of inserting them.

Indent Indicates that auto-indent is in effect. It may be switched off by the auto-indent on/off command (Ctrl-Q-I by default).

X:FILENAME.TYP The drive, name, and type of the file being edited.

Editing Commands

As mentioned before, you use the editor almost as a typewriter, but as this is a computerized text editor it offers you a number of editing facili tie£ which make text manipulation, and in this case specifically program writing, much easier than on paper.

The TURBO editor accepts a total of 45 editing commands to move the cursor around, page through the text, find and replace text strings, etc, etc. These commands can be grouped into the following four categories:

Cursor movement commands, Insert and delete commands, Block commands, and Miscellaneous commands

Each of these groups contain logically related commands which will be described separately in following sections. The following table provides an overview of the commands available:

20 TURBO Pascal Reference Manual The TURBO Editor

CURSOR MOVEMENT COMMANDS: Character left To top of screen Character right To top of file Word left To top of file Word right To end of file Line up To left on line Line down To right on line Scroll up To beginning of block Scroll down To end of block Page up To last cursor position Page down

INSERT & DELETE COMMANDS: Insert mode on/off Delete right word Insert line Delete character under cursor Delete line Delete left charnctor Delete to end of line

BLOCK COMMANDS: MISC. EDITING COMMANDS: Mark block begin End edit Mark block end Tab Mark single word Auto tab on/off Copy block Restore line Move block Find Delete block Find & replace Read block from disk Repeat last find Write block to disk Control character prefix Hide/display block

Table 1-1: Editing Command Overview

In a case like this, the best way of learning is by doing; so start TURBO, specify one of the demo Pascal programs as your Work file, and enter E to start Editing. Then use the commands as you read on.

Hang on, even if you find it a bit hard in the beginning. It Is not just by chance we have chosen to make the TURBO editor WordStar compati ble - the logic of these commands, once learned, quickly become so much a part of you that the editor virtually turns into an extension of your mind. Take it from one who has written megabytes worth of text with that editor.

USING THE TURBO SYSTEM 21 The TURBO Editor

Each of the following descriptions consists of a heading defining the command, followed by the default keystrokes used to activate the com mand, with room in between to note which keys to use on your terminal, if you use other keys. If you have arrow keys and dedicated word pro cessing keys (insert, delete, etc.), it might be convenient to use these. Please refer to pages 13 pp for installation details.

The following descriptions of the commands assume the use of the default WordStar compatible keystrokes.

A Note on Control Characters

All commands are issued using control characters. A control character is a special character generated by your keyboard when you hold down the < CONTROL> (or < CTRL » key on your keyboard and press any key from A through Z (well, even the [, \, ], A, and _ keys generate control characters for that matter).

The < CONTROL> key works like the < SHIFT> key: if you hold down the < SHIFT> key and press A, you will get a capital A; if you hold down the < CONTROL > k~y and press A, you will get a Control A (Ctrl-A for short).

Before You Start: How To Get Out

The command which takes you out of the editor is described on page 30, but you may find it useful to know already now that the Ctrl-K-D command exits the editor and returns you to the menu environment. This command does not automatically save the file; that must be done with the Save command from the menu.

Basic Movement Commands

The most basic thing to learn about an editor is how to move the cursor around on the screen. The TURBO editor uses a special group of con trol characters to do that, namely the control characters A, S, 0, F, E, R, X, and C.

22 TURBO Pascal Reference Manual The TURBO Editor

Why these? Because they are conveniently located close to the control key, so that your left little finger can rest on that while you use the mid dle and index fingers to activate the commands. Furthermore, the char acters are arranged in such a way on the keyboard as to logically indi cate their use. Let's examine the basic movements: cursor up, down, left, and right:

E S D X

These four characters are placed so that it is logical to assume that Ctrl-E moves the cursor up, Ctrl-X down, Ctrl-S to the left, and Ctrl-D to the right. And that is exactly what they do. Try to move the cursor around on the screen with these four commands. If your keyboard has repeating keys, you may just hold down the control key and one of these four keys, and the cursor will move rapidly across the screen.

Now let us look at some extensions of those movements:

E R A S D F X C

The location of the Ctrl-R next to the Ctrl-E suggests that Ctrl-R moves the cursor up, and so it does, only not one line at a time but a whole page. Similarly, Ctrl-C moves the cursor down one page at a time.

Likewise with Ctrl-A and Ctrl-F: Ctrl-A moves to the left like Ctrl-S, but a whole word at a time, and Ctrl-F moves one word to the right.

The two last basic movement commands do not move the cursor but scrolls the entire screen upwards or downwards in the file:

W E R A S D F Z X C

Ctrl-W scrolls upwards in the file (the lines on the screen move down), and Ctrl-Z scrolls downwards in the file (the lines on the screen move up).

USING THE TURBO SYSTEM 23 The TURBO Editor

Character left Ctrl-S Moves the cursor one character to the left non-destructively, without affecting the character there. < BACKSPACE> may be installed to have the same effect. This command does not work across line breaks; when the cursor reaches th.e left edge of the screen, it stops.

Character right Ctrl-D Moves the cursor one character to the right non-destructively, without affecting the character there. This command does not work across line breaks, i.e. when the cursor reaches the right end of the screen, the text starts scrolling horizontally until the cursor reaches the extreme right of the line, in column 128, where it stops.

Word left Ctrl-A Moves the cursor to the beginning of the word to the left. A word is defined as a sequence of characters delimited by one of the following

characters: Ispacel < > , ; . ( ) [ ] A , * + - I $. This command works across line breaks.

Word right Ctrl-F Moves the cursor to the beginning of the word to the right. See the definition of a word above. This command works across line breaks.

Line up Ctrl-E Moves the cursor to the line above. If the cursor is on the top line, the screen scrolls down one line.

Line down Ctrl-X Moves the cursor to the line below. If the cursor is on the second-last line, the screen scrolls up one line.

Scroll up Ctrl-W Scrolls 'up' towards the beginning of the file, one line at a time (the en tire screen scrolls down). The cursor remains on its line until it reaches the bottom of the screen.

Scroll down Ctrl-Z Scrolls 'down' towards the end of the file, one line at a time (the entire screen scrolls up). The cursor remains on its line until it reaches the top of the screen.

24 TURBO Pascal Reference Manual The TURBO Editor

Page up Ctrl-R Moves the cursor one page up with an overlap of one line; the cursor moves one screenful less one line backwards in the text.

Page down Ctrl-C Moves the cursor one page down with an overlap of one line; the cursor moves one screenful less one line forwards in the text.

Extended Movement Commands

The commands discussed above will let you move freely around in your program text, and they are easy to learn and understand. Try to use them all for a while and see how natural they feel.

Once you master them, you will probably sometimes want to move more rapidly. The TURBO editor provides six commands to move rapidly to the extreme ends of lines, to the beginning and end of the text, and to the last cursor position.

These commands require two characters to be entered: first a Ctrl-Q and then one of the following control characters: S, 0, E, X, R, and C. They repeat the pattern from before:

E R S 0 X C

Ctrl-Q-S moves the cursor to the extreme left of the line, and Ctrl-Q-O moves it to the extreme right of the line. Ctrl-Q-E moves the cursor to the top of the screen, Ctrl-Q-X moves it to the bottom of the screen. Ctrl-Q-R moves the cursor all the way 'up' to the start of the file, Ctrl Q-C moves it all the way 'down' to the end of the file.

To left on line Ctrl-Q-S Moves the cursor all the way to the left edge of the screen, to column one.

To right on line Ctrl-Q-O Moves the cursor to the end of the line to the position following the last printable character on the line. Trailing blanks are always removed from all lines to preserve space.

USING THE TURBO SYSTEM 25 The TURBO Editor

To top of screen Ctrl-Q-E Moves the cursor to the top of the screen.

To bottom of screen Ctrl-Q-X Moves the cursor to the bottom of the screen.

To top of file Ctrl-Q-R Moves to the first character of the text.

To end of file Ctrl-Q-C Moves to the last character of the text.

Finally the Ctrl-Q prefix with a B, K, or P control character allows you to jump far within the file:

To beginning of block Ctrl-Q-B Moves the cursor to the the position of the block begin marker set with Ctrl-K-B (hence the Q-B). The command works even if the block is not displayed (see hide/display block later), or the block end marker is not set.

To end of block Ctrl-Q-K Moves the cursor to the position of the block end marker set with Ctrl K-K (hence the Q-K). The command works even if the block is not displayed (see hide/display block later), or the block begin marker is not set.

To last cursor position Ctrl-Q-P Moves to the last Position of the cursor. This command is particularly useful to move back to the last position after a Save operation or after a find or find/replace operation.

Insert and Delete Commands

These commands let you insert and delete characters, words, and lines. They can be divided into three groups: one command which controls the text entry mode (insert or overwrite), a number of simple commands, and one extended command.

Notice that the TURBO editor provides a 'regret' facility which lets you 'undo' changes as long as you have not left the line. This command (Ctrl-Q-L) is described on page 31.

26 TURBO Pascal Reference Manual The TURBO Editor

Insert mode on/off Ctrl-V When you enter text, you may choose between two entry modes: Insert and Overwrite. Insert mode is the default value when the editor is in voked, and it lets you insert new text into an existing text. The existing text to the right of the cursor simply moves to the right while you enter the new text.

Overwrite mode may be chosen if you wish to replace old text with new text. Characters entered then replace existing characters under the cur sor.

You switch between these modes with the insert mode on/off command Ctrl-V, and the current mode is displayed in the status line at the top of the screen.

Delete left character < DEL> Moves one character to the left and deletes the character there. Any characters to the right of the cursor move one position to the left. The < BACKSPACE> key which normally backspaces non-destructively like Ctrl-S may be installed to perform this function if it is more con veniently located on your keyboard, or if your keyboard lacks a < DELETE> key (sometimes labeled < DEL>, < RUBOUT >, or < RUB». This command works across line breaks, and can be used to remove line breaks.

Delete character under cursor Ctrl-G Deletes the character under the cursor and moves any characters to the right of the cursor one pOSition to the left. This command does not work across line breaks.

Delete right word Ctrl-T Deletes the word to the right of the cursor. A word is defined as a se quence of characters delimited by one of the following characters:

Ispace! < > ,; . ( ) [ ] A , * + - / $. This command works across line breaks, and may be used to remove line breaks.

Insert line Ctrl-N Inserts a line break at the cursor position. The cursor does not move.

Delete line Ctrl-V Deletes the line containing the cursor and moves any lines below one line up. The cursor moves to the left edge of the screen. No provision exists to restore a deleted line, so take care!

USING THE TURBO SYSTEM 27 The TURBO Editor

Delete to end of line Ctrl-Q-Y Deletes all text from the cursor position to the end of the line.

Block Commands

All block commands are extended commands (two characters each in the standard command definition), and you may ignore them at first if you feel a bit dazzled at this pOint. Later on, when you feel the need to move, delete, or copy whole chunks of text, you should return to this section.

For the persevering, we'll go on and discuss the use of blocks.

A block of text is simply any amount of text, from a single character to several pages of text. A block is marked by placing a Begin block mark er at the first character and an End block marker at the last character of the desired portion of the text. Thus marked, the block may be copied, moved, deleted, and written to a file. A command is available to read an external file into the text as a block, and a special command convenient ly marks a single word as a block.

Mark block begin Ctrl-K-B This command marks the beginning of a block. The marker itself is not visible on the screen, and the block only becomes visibly marked when the End block marker is set, and then only if the screen is installed to show some sort of highlighting. But even if the block is not visibly marked, it is internally marked and may be manipulated.

Mark block end Ctrl-K-K This command marks the end of a block. As above, the marker itself is not visible on the screen, and the block only becomes visibly marked when the Begin block marker is also set.

Mark single word Ctrl-K-T This command marks a single word as a block, and thus replaces the Begin block - End block sequence which is a bit clumsy when marking just one word. If the cursor is placed within a word, then this word will be marked; if not then the word to the left of the cursor will be marked. A word is defined as a sequence of characters delimited by one of the

following characters: Ispace! < > ,;. ( ) [ ] A , • + - / $.

28 TURBO Pascal Reference Manual The TURBO Editor

Hide/display block Ctrl-K-H This command causes the visual marking of a block (dim text) to be al ternately switched off and on. Block manipulation commands (copy, move, delete, and write to a file) work only when the block is displayed. Block related cursor movements (jump to beginning/end of block) work whether the block is hidden or displayed.

Copy block Ctrl-K-C This command places a copy of a previously marked block starting at the cursor position. The original block is left unchanged, and the mark ers are placed around the new copy of the block. If no block is marked, the command performs no operation, and no error message is issued.

Move block Ctrl-K-V This command moves a previously marked block from its original posi tion to the cursor position. The block disappears from its original posi tion and the markers remain around the block at its new position. If no block is marked, the command performs no operation, and no error message is issued.

Delete block Ctrl-K-Y This command deletes the previously marked block. No provision exists to restore a deleted block, so be careful!

Read block from disk Ctrl-K-R This command is used to read a file into the current text at the cursor position, exactly as if it was a block that was moved or copied. The block read in is marked as a block. When this command is issued, you are prompted for the name of the file to read. The file specified may be any legal filename. If no file type is specified, .PAS is automatically as sumed. A file without type is specified as a name followed by a period.

USING THE TURBO SYSTEM 29 The TURBO Editor

Write block to disk Ctrl-K-W This command is used to write a previously marked block to a file. The block is left unchanged, and the markers remain in place. When this command is issued, you are prompted for the name of the file to write to. If the file specified already exists, a warning is issued before the ex isting file is overwritten. If no block is marked, the command performs no operation, and no error message is issued.The file specified may be any legal filename. If no file type is specified, .PAS is automatically as sumed. A file without type is specified as a name followed by a period. Avoid the use of file types .BAK, .CHN, and .COM/.CMD, as they are used for special purposes by the TURBO system.

Miscellaneous Editing Commands

This section collects a number of commands which do not logically fall into any of the above categories. They are nonetheless important, espe cially this first one:

End edit Ctrl-K-D This command ends the edit and returns to the main menu. The editing has been performed entirely in memory, and any associated disk file is not affected. Saving the edited file on disk is done explicitly with the Save command from the main menu or automatically in connection with a compilation or definition of a new Work file.

Tab TAB/Ctrl-I There are no fixed tab pOSitions in the TURBO editor. Instead, tab posi tions are automatically set to the beginning of each word on the line im mediately above the cursor. This provides a very convenient automatic tabbing feature especially useful in program editing where you often want to line up columns of related items, like variable declarations and such. Remember that Pascal allows you to write extremely beautiful source texts - do it, not for the sake of the purists, but more importantly to keep the program easy to understand, especially when you return to make changes after some time.

30 TURBO Pascal Reference Manual The TURBO Editor

Auto indent on/off Ctrl-Q-I The auto indent feature provides automatic indenting of successive lines. When active, the indent of the current line is repeated on each fol lowing line, that is, when you hit < RETURN> , the cursor does not re turn to column one but to the starting column of the line you just ter minated. When you want to change the indent, use any of the cursor right or left commands to select the new column. When auto indent is active, the message Indent is displayed in the status line, and when passive the message is removed. Auto indent is active by default.

Restore line Ctrl-Q-L This command lets you regret changes made to a line as long as you have not left the line. The line is simply restored to its original contents regardless of what changes you have made. But only as long as you remain on the line; the moment you leave it, changes are there to stay. For this reason, the Delete line (Ctrl-Y) command can regrettably only be regretted, not restored. Some days you may find yourself continuously falling asleep on the Ctrl-Y key, with vast consequences. A good long break usually helps.

Find Ctrl-Q-F The Find command lets you search for any string of up to 30 characters. When you enter this command, the status line is cleared, and you are prompted for a search string. Enter the string you are looking for and terminate with < RETURN> . The search string may contain any char acters, also control characters. Control characters €ire entered into the search string with the Ctrl-P prefix. Example: enter a Ctrl-A by holding down the Control key while pressing first P, then A. You may thus in clude a line break in a search string by specifying Ctrl-M Ctrl-J. Notice that Ctrl-A has a special meaning: it matches any character and may be used as a wildcard in search strings.

Search strings may be edited with the Character Left, Character Right, Word Left, and Word Right commands. Word Right recalls the previous search string which may then be edited. The search operation may be aborted with the Abort command (Ctrl-U).

When the search string is specified, you are asked for search options. The following options are available:

USING THE TURBO SYSTEM 31 The TURBO Editor

B Search backwards. Search from the current cursor position towards the beginning of the text. G Global search. Search the entire text, irrespective of the current cursor position. n n = any number. Find the n'th occurrence of the search string, counted from the current cursor position. U Ignore upper/lower case. Regard upper and lower case alphabeticals as equal. W Search for whole words only. Skip matching patterns which are embed ded in other words.

Examples: W search for whole words only. The search string 'term' will only match the word 'term', not for example the word 'terminal'. BU search backwards and ignore upper/lower case. 'Block' will match both 'blockhead' and 'BLOCKADE', etc. 125 Find the 125th occurrence of the search string.

Terminate the list of options (if any) with < RETURN> , and the search starts. If the text contains a target matching the search string, the cur sor is positioned at the end of the target. The search operation may be repeated by the Repeat last find command (Ctrl-L).

Find and replace Ctrl-Q-A The Find and Replace command lets you search for any string of up to 30 characters and replace it with any other string of up to 30 characters. When you enter this command, the status line is cleared, and you are prompted for a search string. Enter the string you are looking for and terminate with < RETURN> . The search string may contain any char acters, also control characters. Control characters are entered into the search string with the Ctrl-P prefix. Example: enter a Ctrl-A by holding down the Control key while pressing first P, then A. You may thus in clude a line break in a search string by specifying Ctrl-M Ctrl-J. Notice that Ctrl-A has a special meaning: it matches any character and may be used as a wildcard in search strings.

32 TURBO Pascal Reference Manual The TURBO Editor

When the search string is specified, you are asked to enter the string to replace the search string. Enter up to 30 characters; control character entry and editing is performed as above, but Ctrl-A has no special meaning in the replace string. If you just press < RETURN> , the tar get will be replaced with nothing, in effect deleted.

Finally you are prompted for options. The search and replace options are:

B Search and replace backwards. Search and replace from the current cursor position towards the beginning of the text. G Global search and replace. Search and replace in the entire text, ir respective of the current cursor position. n n = any number. Find and replace n occurrences of the search string, counted from the current cursor position. N Replace without asking. Do not stop and ask Replace (YIN) for each oc currences of the search string. U Ignore upper/lower case. Regard upper and lower case alphabeticals as equal. W Search and replace whole words only. Skip matching patterns which are embedded in other words.

Examples: N10 Find the next ten occurrences of the search string and replace without asking. GW Find and replace whole words in the entire text. Ignore upper/lower case.

Terminate the list of options (if any) with < RETURN>, and the search and replace starts. Depending on the options specified, the string may be found. When found (and if the N option is not specified), the cursor is positioned at the end of the target, and you are asked the question: Replace (YIN)? on the prompt line at the top of the screen. You may abort the search and replace operation at this point with the Abort command (Ctrl-U). The search and replace operation may be repeated by the Repeat last find command (Ctrl-L).

Repeat last find Ctrl-L This command repeats the latest Find or Find and replace operation ex actly as if all information had been re-entered.

USING THE TURBO SYSTEM 33 The TURBO Editor

Control character prefix Ctrl-P The TURBO editor allows you to enter control characters into the file by prefixing the desired control character with a Ctrl-P, that is, first press Ctrl-P, then press the desired control character. Control characters will appear as low-lighted capital letters on the screen (or inverse, depending on your terminal).

Abort operation Ctrl-U The Ctrl-U command lets you abort any command in process whenever it pauses for input, like when Search and Replace asks Replace YIN?, or during entry of a search string or a file name (block Read and Write).

The TURBO editor vs. WordStar

Someone used to WordStar will notice that a few TURBO commands work slightly different, and although TURBO contains only a subset of WordStar's commands, a number of special features not found in WordStar have been added to enhance the editing of program source code. These differences are discussed in the following.

Cursor Movement

The cursor movement controls Ctrl-S, 0, E, and X move freely around on the screen and do not jump to column one on empty lines. This does not mean that the screen is full of blanks; on the contrary, all trailing blanks are automatically deleted. This way of moving the cursor is espe cially useful for example when matching indented begin - end pairs.

Ctrl-S and Ctrl-D do not work across line breaks. To move from one line to another you must use Ctrl-E, Ctrl-X, Ctrl-A, or Ctrl-F.

Mark Single Word

Ctrl-K-T is used to mark a single word as a block which is more con venient than the two-step process of marking the beginning and the end of the word separately.

34 TURBO Pascal Reference Manual The TURBO editor VS. WordStar

End Edit

The Ctrl-K-D command ends editing and returns you to the menu. As editing in TURBO is done entirely in memory, this command does not change the file on disk (as it does in WordStar). Updating the disk file must be done explicitly with the Save command from the main menu or automatically in connection with a compilation or definition of a new Work file. TURBO's Ctrl-K-D does not resemble WordStar's Ctrl-K-Q (quit edit) command either, as the changed text is not abandoned; it is left in memory ready to be Compiled or Saved.

Line Restore

The Ctrl-Q-L command restores a line to its contents before edit as long as the cursor has not left the line.

Tabulator

No fixed tab settings are provided. Instead, the automatic tab feature sets tabs to the start of each word on the line immediately above the cursor.

Auto Indentation

The Ctrl-Q-I command switches the auto indent feature on and off.

USING THE TURBO SYSTEM 35 The TURBO editor VS. WordStar

Notes:

36 TURBO Pascal Reference Manual Chapter 2 BASIC LANGUAGE ELEMENTS

Basic Symbols

The basic vocabulary of TURBO Pascal consists of basic symbols divid ed into letters, digits, and special symbols:

LeHers A to Z, a to z, and _ (underscore) Digits o 1 2 345 678 9 Special symbols +-*I="<>() [] {}.,:; '#$

No distinction is made between upper and lower case letters. Certain operators and delimiters are formed using two special symbols:

Assignment operator: : = Relational operators: <> <= >= Subrange delimiter: .. Brackets: ( . and . ) may be used instead of [ and ] Comments: (* and *) may be used instead of { and }

Reserved Words Reserved words are integral parts of TURBO Pascal. They cannot be redefined and must therefore not be used as user defined identifiers. Throughout this manual, reserved words are written in boldface. * absolute * external nil * shl and file not * shr array forward * overlay * string begin for of then case function or type const goto packed to div * inline procedure until do if program var downto in record while else label repeat with end mod set * xor

*Not defined in standard Pascal.

BASIC LANGUAGE ELEMENTS 37 Reserved Words

Standard Identifiers TURBO Pascal defines a number standard identifiers of predefined types, constants, variables, procedures, and functions. Any of these identifiers may be redefined but it will mean the loss of the facility offered by that particular identifier and may lead to confusion. The following standard identifiers are therefore best left to their special purposes: Addr Delay Length Real ArcTan Delete Ln Release Assign EOF Lo Rename Aux EOLN LowVideo Reset AuxInptr Erase Lst Rewrite AuxOutPtr Execute LstOutPtr Round BlockRead Exit Mark Seek BlockWrite Exp MaxInt Sin Boolean False Mem SizeOf BufLen FilePos MemAvail SeekEof Byte FileSize MemW SeekEoln Chain FillChar Move Sqr Char Flush New Sqrt Chr Frac NormVideo Str Close GetMem Odd Succ ClrEOL GotoXY Ord Swap ClrScr Halt Output Text Con HeapPtr Pi Trm ConInPtr Hi Port True ConOutPtr IOresult PortW Trunc Concat Input Pos UpCase ConstPtr InsLine Pred Usr Copy Insert Ptr UsrInptr Cos Int Random UsrOutPtr CrtExit Integer Randomize Val CrtInit Kbd Read Write DelLine KeyPressed ReadLn WriteLn Each TURBO Pascal implementation further contains a number of dedi cated standard identifiers which are listed in chapters 20, 21, and 22.

38 TURBO Pascal Reference Manual Standard Identifiers

Throughout this manual, all identifiers, including standard identifiers, are written in a combination of upper and lower case letters (see page 43). In the text (as opposed to program examples), they are furthermore printed in italics.

Delimiters

Language elements must be separated by at least one of the following delimiters: a blank, an end of line, or a comment.

Program Lines

The maximum length of a program line is 127 characters; any character beyond the 127th is ignored by the compiler. For this reason the TURBO editor allows only 127 characters on a line, but source code prepared with other editors may use longer lines. If such a text is read into the TURBO editor, line breaks will be automatically inserted, and a warning is issued.

BASIC LANGUAGE ELEMENTS 39 Program Lines

Notes:

40 TURBO Pascal Reference Manual Chapter 3 STANDARD SCALAR TYPES

A data type defines the set of values a variable may assume. Every vari able in a program must be associated with one and only one data type. Although data types in TURBO Pascal can be quite sophisticated, they are all built from simple (unstructured) types.

A simple type may either be defined by the programmer (it is then called a declared scalar type), or be one of the standard scalar types: integer, real, boolean, char, or byte. The following is a description of these five standard scalar types.

Integer

Integers are whole numbers; in TURBO Pascal they are limited to a range of - 32768 through 32767. Integers occupy two bytes in memory.

Overflow of integer arithmetic operations is not detected. Notice in par ticular that partial results in integer expressions must be kept within the integer range. For instance, the expression 1000 * 100 I 50 will not yield 2000, as the multiplication causes an overflow.

Byte

The type Byte is a subrange of the type Integer, of the range 0 .. 255. Bytes are therefore compatible with integers. Whenever a Byte value is expected, an Integer value may be specified instead and vice versa, ex cept when passed as parameters. Furthermore, Bytes and Integers may be mixed in expressions and Byte variables may be assigned integer values. A variable of type Byte occupies one byte in memory.

STANDARD SCALAR TYPES 41 Real

Real

The range of real numbers is 1 E - 38 through 1 E + 38 with a mantissa of up to 11 significant digits. Reals occupy 6 bytes in memory.

Overflow during an arithmetic operation involving reals causes the pro gram to halt, displaying an execution error. An underflow will cause a result of zero.

Although the type real is included here as a standard scalar type, the following differences between reals and other scalar types should be noticed:

1) The functions Pred and Succ cannot take real arguments. 2) Reals cannot be used in array indexing. 3) Reals cannot be used to define the base type of a set. 4) Reals cannot be used in controlling for and case statements. 5) Subranges of reals are not allowed.

Boolean

A boolean value can assume either of the logical truth values denoted by the standard identifiers True and False. These are defined such that False < True. A Boolean variable occupies one byte in memory.

Char

A Char value is one character in the ASCII character set. Characters are ordered according to their ASCII value, for example: 'A' < 'S'. The or dinal (ASCII) values of characters range from 0 to 255. A Char variable occupies one byte in memory.

42 TURBO Pascal Reference Manual Chapter 4 USER DEFINED LANGUAGE ELEMENTS

Identifiers

Identifiers are used to denote labels, constants, types, variables, pro cedures, and functions. An identifier consists of a letter or underscore followed by any combination of letters, digits, or underscores. An identifier is limited in length only by the line length of 127 characters, and all characters are significant.

Examples: TURBO square persons_counted BirthDate 3rdRoot illegal, starts with a digit Two Words illegal, must not contain a space

As TURBO Pascal does not distinguish between upper and lower case letters, the use of mixed upper and lower case as in BirthDate has no functional meaning. It is nevertheless encouraged as it leads to more le gible identifiers. VeryLongldentifier is easier to read for the human reader than VERYLONGIDENTIFIER. This mixed mode will be used for all identifiers throughout this manual.

Numbers

Numbers are constants of integer type or of real type. Integer constants are whole numbers expressed in either decimal or hexadecimal notation. Hexadecima~ constants are identified by being preceded by a dollar sign: $ABC is a hexadecimal constant. The decimal integer range is - 32768 through 32767 and the hexadecimal integer range is $0000 through $FFFF.

USER DEFINED LANGUAGE ELEMENTS .. 43 Numbers

Examples: 1 12345 -1 $123 $ABC $123G illegal, G is not a legal hexadecimal digit 1.2345 illegal as an integer, contains a decimal parts

The range of Real numbers is 1 E-38 through 1 E + 38 with a mantissa of up to 11 significant digits. Exponential notation may be used, with the letter E preceding the scale factor meaning "times ten to the power of". An integer constant is allowed anywhere a real constant is allowed. Separators are not allowed within numbers.

Examples: 1.0 1234.5678 -0.012 lE6 2E-5 -1.2345678901E+12 1 legal, but it is not a real, it is an integer

Strings

A string constant is a sequence of characters enclosed in single quotes: 'This is a string constant '

A single quote may be contained in a string by writing two successive single quotes. Strings containing only a single character are of the stan dard type char. A string is compatible with an array of Char of the same length. All string constants are compatible with all string types.

Examples: 'TURBO' 'You' '11 see' , , " , . , , .,

44 TURBO Pascal Reference Manual Strings

As shown in example 2 and 3, a single quote within a string is written as two consecutive quotes. The four consecutive single quotes in example 3 thus constitute a string containing one quote.

The last example - the quotes enclosing no characters, denoting the empty string - is compatible only with string types.

Control Characters

TURBO Pascal also allows control characters to be embedded in strings. Two notations for control characters are supported: 1) The # symbol followed by an integer constant in the range 0 .. 255 denotes a character of the corresponding ASCII value, and 2) the A symbol followed by a character, denotes the corresponding control character.

Examples: # 10 ASCII 10 decimal (Line Feed). #$lB ASCII 1 B hex (Escape).

A G Control-G (Bell).

A 1 Control-L (Form Feed).

A [ Control-[ (Escape).

Sequences of control characters may be concatenated into strings by writing them without separators between the individual characters:

#13#10 #27 A U#20 AGAG"GAG

The above strings contain t~o, three, and four characters, respectively. Control characters may also be mixed with text strings:

'Waiting for input! '''GAGAG' Please wake up' #27'U ' 'This is another line of text 'AMAJ

These three strings contain 37, 3, and 31 characters, respectively.

USER DEFINED LANGUAGE ELEMENTS 45 Comments

Comments

A comment may be inserted anywhere in the program where a delimiter is legal. It is delimited by the curly braces { and }, which may be re placed by the symbols (* and *).

Examples: {This is a comment} (* and so is this *)

Curly braces may not be nested within curly braces, and (* ..*) may not be nested within (* ..*). However, curly braces may be nested within (* ..*) and vice versa, thus allowing entire sections of source code to be commented away, even if they contain comments.

Compiler Directives

A number of features of the TURBO Pascal compiler are controlled through compiler directives. A compiler directive is introduced as a com ment with a special syntax which means that whenever a comment is al lowed in a program, a compiler directive is also allowed.

A compiler directive consists of an opening brace immediately followed by a dollar-sign immediately followed by one compiler directive letter or a list of compiler directive letters separated by commas. The syntax of the directive or directive list depends upon the directive(s) selected. A full description of each of the compiler directives follow in the relevant sec tions; and a summary of compiler directives is located in Appendix C. File inclusion is discussed in chapter 17.

Examples: {$I-} {$I INCLUDE. FIL} {$R-, B+, V-} (*$X-*)

Notice that no spaces are allowed before or after the dollar-sign.

46 TURBO Pascal Reference Manual Chapter 5 PROGRAM HEADING AND PROGRAM BLOCK

A Pascal program consists of a program heading followed by a program block. The program block is further divided into a declaration part, in which all objects local to the program are defined, and a statement part, which specifies the actions to be executed upon these objects. Each is described in detail in the following sections.

Program Heading

In TURBO Pascal, the program heading is purely optional and of no significance to the program. If present, it gives the program a name, and optionally lists the parameters through which the program communi cates with the environment. The list consists of a sequence of identifiers enclosed in parentheses and separated by commas.

Examples: program Circles; program Accountant(Input,Output); program Writer(Input,Printer);

Declaration Part

The declaration part of a block declares all identifiers to be used within the statement part of that block (and possibly other blocks within it). The declaration part is divided into five different sections:

1) Label declaration part 2) Constant definition part 3) Type definition part 4) Variable declaration part 5) Procedure and function declaration part

Whereas standard Pascal specifies that each section may only occur zero or one time, and only in the above order, TURBO Pascal allows each of these sections to occur any number of times in any order in the declaration part.

PROGRAM HEADING AND PROGRAM BLOCK 47 Declaration Part

Labe/ Dec/aration Part

Any statement in a program may be prefixed with a label, enabling direct branching to that statement by a 90to statement. A label consists of a label name followed by a colon. Before use, the label must be de clared in a label declaration part. The reserved word label heads this part, and it is followed by a list of label identifiers separated by commas and terminated by a semi-colon.

Example: label 10, error, 999, Quit;

Whereas standard Pascal limits labels to numbers of no more than 4 di gits, TURBO Pascal allows both numbers and identifiers to be used as labels.

Constant Definition Part

The constant definition part introduces identifiers as synonyms for con stant values. The reserved word const heads the constant definition part, and is followed by a list of constant assignments separated by semi-colons. Each constant assignment consists of an identifier followed by an equal sign and a constant. Constants are either strings or numbers as defined on pages 43 and 44.

Example: const Limit = 255; Max = 1024; PassWord = 'SESAM'; CursHome = ~['V';

The following constants are predefined in TURBO Pascal which may be referenced without previous definition:

Name: Type and value: Pi Real (3.1415926536E+OO). False Boolean (the truth value false). True Boolean (the truth value true). Maxint Integer (32767).

As described in chapter 13, a constant definition part may also define typed constants.

48 TURBO Pascal Reference Manual Declaration Part

Type Definition Part

A data type in Pascal may be either directly described in the variable de claration part or referenced by a type identifier. Several standard type identifiers are provided, and the programmer may create his own types through the use of the type definition. The reserved word type heads the type definition part, and it is followed by one or more type assign ments separated by semi-colons. Each type assignment consists of a type identifier followed by an equal sign and a type.

Example: type Number = Integer; Day = (mon,tues,wed,thur,fri,sat,sun); List = array[l .. 10] of Real;

More examples of type definitions are found in subsequent sections.

Variable Declaration Part

Every variable occurring in a program must be declared before use. The declaration must textually precede any use of the variable so that the variable is 'known' to the compiler when it is used.

A variable declaration consists' of the reserved word var followed by one or more identifier(s), separated by commas, each followed by a colon and a type. This creates a new variable of the specified type and associ ates it with the specified identifier.

Example: var Result, Intermediate, SubTotal: Real; I, J, X, Y: Integer; Accepted, Valid: Boolean; Period: Day; Buffer: array[O .. 127] of Byte; The 'scope' of the identifiers shown above is the block in which they are defined, and any block within that block. Note, however, that any such block within another block may define another variable using the same identifier. This variable is said to be local to the block in which it is declared (and any blocks within that block), and the variable declared on the outer level (the global variable) becomes inaccessible.

PROGRAM HEADING AND PROGRAM BLOCK 49 Declaration Part

Complex Variable Declaration

The following declaration, which clarifies a subtle point in Turbo Pascal's type checking, creates two variables that Turbo Pascal considers the same type:

var rl, r2 = record fl : char; end

However, this declaration creates two variables which Turbo Pascal considers to be of different type:

var rl = record fl : char; end r2 = record fl : char; end Procedure and Function Declaration Part

A procedure declaration serves to define a procedure within the current procedure or program (see page 131). A procedure is activated from a procedure statement (see page 56), and upon completion, program exe cution continues with the statement immediately following the calling statement.

A function declaration serves to define a program part which computes and returns a value (see page 137). A function is activated when its designator is met as part of an expression (see page 54).

Statement Part

The statement part is the last part of a block. It specifies the actions to be executed by the program. The statement part takes the form of a compound statement followed by a period or a semi-colon. A compound statement consists of the reserved word begin, followed by a list of statements separated by semicolons, terminated by the reserved word end.

50 TURBO Pascal Reference Manual Chapter 6 EXPRESSIONS

Expressions are algorithmic constructs specifying rules for the computa tion of values. They consist of operands: variables, constants, and func tion designators combined by means of operators as defined in the fol lowing.

This section describes how to form expressions from the standard scalar types Integer, Real, Boolean, and Char. Expressions containing declared scalar types, string types, and set types are described on pages 63, 67, and 86, respectively.

Operators

Operators fall into five categories, denoted by their order of precedence:

1) Unary minus (minus with one operand only). 2) Not operator. 3) Multiplying operators: *, I, diY, mod, and, shl, and shr. 4) Adding operators: +, -, or, and xor. 5) Relational operators: =, < >, <, >, < =, > =, and in.

Sequences of operators of the same precedence are evaluated from left to right. Expressions within parentheses are evaluated first and indepen dently of preceding or succeeding operators.

If both of the operands of the multiplying and adding operators are of type Integer, then the result is of type Integer. If one (or both) of the operands is of type Real, then the result is also of type Real.

Unary Minus

The unary minus denotes a negation of its operand which may be of Real or Integer types.

EXPRESSIONS 51 Operators

Not Operator

The not operator negates (inverses) the logical value of its Boolean operand:

not True = False not False = True

TURBO Pascal also allows the not operator to be applied to an Integer operand, in which case bitwise negation takes place.

Examples: not 0 = -1 not -15 = 14 not $2345 = $DCBA

Multiplying Operators

Operator Operation Operand type Result type

multiplication Real Real multiplication Integer Integer multiplication Real, Integer Real I division Real, Integer Real I division Integer Real I division Real Real div Integer division Integer Integer mod modulus Integer Integer and arithmetic and Integer Integer and logical and Boolean Boolean shl shift left Integer Integer shr shift right Integer Integer

Examples: 12 * 34 = 408 123 / 4 = 30.75 123 div 4 = 30 12 mod 5 = 2 True and False = False 12 and 22 = 4 2 shl 7 = 256 256 shr 7 = 2

52 TURBO Pascal Reference Manual Operators

Adding Operators

Operator Operation Operand type Result type

+ addition Real Real + addition Integer Integer + addition Real, Integer Real subtraction Real Real subtraction Integer Integer subtraction Real, Integer Real or arithmetic or Integer Integer or logical or Boolean Boolean xor arithmetic xor Integer Integer xor logical xor Boolean Boolean

Examples: 123+456 =579 456-123.0 = 333.0 True or False = True 12 or 22 =30 True xor False = True 12 xor 22 =26

Relational Operators

The relational operators work on all standard scalar types: Real, Integer, Boolean, Char, and Byte. Operands of type Integer, Real, and Byte may be mixed. The type of the result is always Boolean, i.e. True or False.

equal to <> not equal to > greater than < less than >= greater than or equal to <= less than or equal to

Expressions 53 Operators

Examples: a = b true if a is equal to b. a <> b true if a is not equal to b. a > b true if a is greater than b. a < b true if a is less than b. a >= b true if a is greater than or equal to b. a <= b true if a is less than or equal to b.

Function Designators

A function designator is a function identifier optionally followed by a parameter list, which is one or more variables or expressions separated by commas and enclosed in parentheses. The occurrence of a function designator causes the function with that name to be activated. If the function is not one of the pre-defined standard functions, it must be de clared before activation.

Examples: Round(PlotPos) Writeln(Pi * (Sqr(R))) (Max(X,Y) < 25) and (Z > Sqrt(X * Y)) Volume(Radius,Height)

54 TURBO Pascal Reference Manual Chapter 7 STATEMENTS

The statement part defines the action to be carried out by the program (or subprogram) as a sequence of statements; each specifying one part of the action. In this sense Pascal is a sequential programming language: statements are executed sequentially in time; never simul taneously. The statement part is enclosed by the reserved words begin and end and within it, statements are separated by semi-colons. State ments may be either simple or structured.

Simple Statements

Simple statements are statements which contain no other statements. These are the assignment statement, procedure statement, goto state ment, and empty statement.

Assignment Statement

The most fundamental of all statements is the assignment statement. It is used to specify that a certain value is to be assigned to a certain vari able. An assignment consists of a variable identifier followed by the as signment operator: = followed by an expression.

Assignment is possible to variables of any type (except files) as long as the variable (or the function) and the expression are of the same type. As an exception, if the variable is of type Real, the type of the expres sion may be Integer.

Examples: Angle := Angle * Pi; AccessOK := False; Entry := Answer = PassWord; SpherVol := 4 * Pi * R * R;

STATEMENTS 55 Simple Statements

Procedure Statement

A procedure statement serves to activate a previously defined user defined procedure or a pre-defined standard procedure. The statement consists of a procedure identifier, optionally followed by a parameter list, which is a list of variables or expressions separated by commas and en closed in parentheses. When the procedure statement is encountered during program execution, control is transferred to the named pro cedure, and the value (or the address) of possible parameters are transferred to the procedure. When the procedure finishes, program ex ecution continues from the statement following the procedure state ment.

Examples: Find(Name,Address); Sort (Address) ; UpperCase(Text); UpdateCustFile(CustRecord);

Goto Statement

A goto statement consists of the reserved word goto followed by a label identifier. It serves to transfer further processing to that pOint in the pro gram text which is marked by the label. The following rules should be observed when using goto statements:

1) Before use, labels must be declared. The declaration takes place in a la bel declaration in the declaration part of the block in which the label is used. 2) The scope of a label is the block in which it is declared. It is thus not possible to jump into or out of procedures and functions.

Empty Statement

An 'empty' statement is a statement which consists of no symbols, and which has no effect. It may occur whenever the syntax of Pascal re quires a statement but no action is to take place.

Examples: begin end.

while Answer <> II do; repeat until KeyPressed; {wait for any key to be hit}

56 TURBO Pascal Reference Manual Structured Statements

Structured Statements

Structured statements are constructs composed of other statements which are to be executed in sequence (compound statements), condi tionally (conditional statements), or repeatedly (repetitive statements). The discussion of the with statement is deferred to pages 81 pp.

Compound Statement

A compound statement is used if more than one statement is to be exe cuted in a situation where the Pascal syntax allows only one statement to be specified. It consists of any number of statements separated by semi-colons and enclosed within the reserved words begin and end, and specifies that the component statements are to be executed in the sequence in which they are written.

Example: if Small > Big then begin Tmp := Small; Small := Big; Big Tmp; end;

Conditional Statements

A conditional statement selects for execution a single one of its com ponent statements.

If Statement

The if statement specifies that a statement be executed only if a certain condition (Boolean expression) is true. If it is false, then either no state ment or the statement following the reserved word else is to be execut ed. Notice that else must not be preceded by a semicolon.

STATEMENTS 57 Structured Statements

The syntactic ambiguity arising from the construct:

if expr1 then if expr2 then stmt1 else stmt2

is resolved by interpreting the construct as follows:

if expr1 then begin if expr2 then stmt1 else stmt2 end

The else-clause part belongs generally to the last if statement which has no else part.

Examples: if Interest > 25 then Usury := True else TakeLoan := OK;

if (Entry < 0) or (Entry> 100) then begin Write('Range is 1 to 100, please re-enter: '); Read( Entry) ; end; Case Statement

The case statement consists of an expression (the selector) and a list of statements, each preceded by a case label of the same type as the selector. It specifies that the one statement be executed whose case la bel is equal to the current value of the selector. If none of the case la bels contain the value of the selector, then either no statement is exe cuted, or, optionally, the statements following the reserved word else are executed. The else clause is an expansion of standard Pascal.

58 TURBO Pascal Reference Manual Structured Statements

A case label consists of any number of constants or subranges separat ed by commas followed by a colon. A subrange is written as two con stants separated by the subrange delimiter ' .. '. The type of the con stants must be the same as the type of the selector. The statement fol lowing the case label is executed if the value of the selector equals one of the constants or if it lies within one of the subranges.

Valid selector types are all simple types, i.e. all scalar types except real.

Examples: case Operator of '+', : Result Answer + Result; - , . Result Answer - Result; '*' . Result Answer * Result; '/' : Result Answer / Result; end;

case Year of Min .. 1939: begin Time := PreWorldWar2; Writeln( 'The world at peace ... '); end; 1946 .. Max: begin Time := PostWorldWar2 Writeln( 'Building a new world.'); end; else begin Time := WorldWar2; Writeln( 'We are at war'); end; end;

Repetitive Statements

Repetitive statements specify that certain statements are to be execut ed repeatedly. If the number of repetitions is known before the repeti tions are started, the for statement is the appropriate construct to ex press this situation. Otherwise the while or the repeat statement should be used.

STATEMENTS 59 Structured Statements

For Statement

The for statement indicates that the component statement is to be re peatedly executed while a progression of values is assigned to a vari able which is called the control variable. The progression can be ascend ing: to or descending: downto the final value.

The control variable, the initial value, and the final value must all be of the same type. Valid types are all simple types, i.e. all scalar types ex cept real.

If the initial value is greater than the final value when using the to clause, or if the initial value is less than the final value when using the downto clause, the component statement is not executed at all.

Examples: for I := 2 to 100 do if A[I] > Max then Max := A[I];

for I := 1 to NoOfLines do begin Readln(Line); if Length(Line) < Limit then ShortLines := ShortLines + 1 else LongLines := LongLines + 1 end;

Notice that the component statement of a for statement must not con tain assignments to the control variable. If the repetition is to be ter minated before the final value is reached, a goto statement must be used, although such constructs are not recommended - it is better pro gramming practice use a while or a repeat statement instead.

Upon completion of a for statement, the control variable equals the final value, unless the loop was not executed at all, in which case no assign ment is made to the control variable.

60 TURBO Pascal Reference Manual Structured Statements

While statement

The expression controlling the repetition must be of type Boolean. The statement is repeatedly executed as long as expression is True. If its value is false at the beginning, the statement is not executed at all.

Examples: while Size > I do Size Sqrt (Size) ;

while ThisMonth do begin ThisMonth := CurMonth SampleMonth; Process; {process this sample by the Process procedure} end;

Repeat Statement

The expression controlling the repetition must be of type Boolean. The sequence of statements between the reserved words repeat and until is executed repeatedly until the expression becomes true. As opposed to the while statement, the repeat statement is always executed at least once, as evaluation of the condition takes place at the end of the loop.

Example: repeat Write(AM, 'Delete this item? (YIN)'); Read(Answer); until UpCase(Answer) in ['Y', 'N'];

STATEMENTS 61 Structured Staten7ents

Notes:

62 TURBO Pascal Reference Manual SCALAR AND SUBRANGE TYPES Chapter 8 SCALAR AND SUBRANGE TYPES

The basic data types of Pascal are the scalar types. Scalar types consti tute a finite and linear ordered set of values. Although the standard type Real is included as a scalar type, it does not conform to this definition. Therefore, Reals may not always be used in the same context as other scalar types.

Scalar Type

Apart from the standard scalar types ( Integer, Real, Boolean, Char, and Byte), Pascal supports user defined scalar types, also called declared scalar types. The definition of a scalar type specifies, in order, all of its possible values. The values of the new type will be represented by identifiers, which will be the constants of the new type.

Examples: type Operator - (Plus.Minus.Multi.Divide): Day - (Mon.Tues.Wed.Thur.Fri.Sat.Sun): Month (Jan.Feb.Mar.Apr.May.Jun.Jul.Aug.Sep.Oct.Nov.Dec): Card - (Club.Diamond.Heart.Spade):

Variables of the above type Card can assume one of four values, name ly Club, Diamond, Heart, or Spade. You are already acquainted with the standard scalar type Boolean which is defined as:

type Boolean = (False,True);

The relational operators =, < >, >, <, > =, and < = can be ap plied to all scalar types, as long as both operands are of the same type (reals and integers may be mixed). The ordering of the scalar type is used as the basis of the comparison, i.e. the order in which the values are introduced in the type definition. For the above type card, the follow ing is true:

Club < Diamond < Heart < Spade

SCALAR AND SUBRANGE TYPES 63 Scalar Type

The following standard functions can be used with arguments of scalar type:

Succ(Diamond) The successor of Diamond (Heart). Pred(Diamond) The predecessor of Diamond (Club). Ord(Diamond) The ordinal value of Diamond (1 [as the ordinal value of the first value of a scalar type is 0]).

The result type of Succ and Pred is the same as the argument type. The result type of Ord is Integer.

Subrange Type

A type may be defined as a subrange of another already defined scalar type. Such types are called subranges. The definition of a subrange sim ply specifies the least and the largest value in the subrange. The first constant specifies the lower bound and must not be greater than the second constant, the upper bound. A subrange of type Real is not al lowed.

Examples: type HemiSphere (North, South, East, West); World East .. West; CompassRange O .. 360; Upper 'A' .. 'Z'; Lower 'a' .. 'z'; Degree (Celc, Fahr, Ream, Kelv); Wine (Red, White, Rose, Sparkling);

The type World is a subrange of the scalar type HemiSphere (called the associated scalar type). The associated scalar type of Compassrange is Integer, and the associated scalar type of Upper and Lower is Char.

You already know the standard subrange type Byte, which is defined as:

type Byte = 0 .. 255;

A subrange type retains all the properties of its associated scalar type, being restricted only in its range of values.

64 TURBO Pascal Reference Manual Subrange Type

The use of defined scalar types and subrange types is strongly recom mended as it greatly improves the readability of programs. Furthermore, run time checks may be included in the program code (see page 65 ) to verify the values assigned to defined scalar variables and subrange vari ables. Another advantage of defined types and subrange types is that they often save memory. TURBO Pascal allocates only one byte of memory for variables of a defined scalar type or a subrange type with a total number of elements less than 256. Similarly, integer subrange vari ables, where lower and upper bounds are both within the range 0 through 255, occupy only one byte of memory.

Type Conversion

The Ord function may be used to convert scalar types into values of type integer. Standard Pascal does not provide a way to reverse this process, i.e. a way of converting an integer into a scalar value.

In TURBO Pascal, a value of one scalar type may be converted into a value of another scalar type, with the same ordinal value, by means of the Retype facility. Retyping is achieved by using the type identifier of the desired type as a function deSignator followed by one parameter en closed in parentheses. The parameter may be a value of any scalar type except Real. Assuming the type definitions on pages 63 and 64 , then:

Integer(Heart) 2 Month(lO) Nov HemiSphe re ( 2 ) East Upper(14) '0' Oegree(3) Ke~ Char(78) 'N' Integer( '7' ) 55

Range Checking

The generation of code to perform run-time range checks on scalar and subrange variables is controlled with the R compiler directive. The de fault setting is { $R-}, i.e. no checking is performed. When an assign ment is made to a scalar or a subrange variable while this directive is ac tive ({ $R +}), assignment values are checked to be within range. It is recommended to use this setting as long as a program is not fully de bugged.

SCALAR AND SUBRANGE TYPES 65 Range Checking

Example: program Rangecheck; type Digit = O.. 9; var Digl,Dig2,Dig3: digit; begin Digl := 5; {valid} Dig2 := Digl + 3; {valid as Dig1 + 3 < = 9} Dig3 := 47; {invalid but causes no error} {$R+} Dig3 := 55; {invalid and causes a run time error} {$R-} Dig3 := 167; {invalid but causes no error} end.

66 TURBO Pascal Reference Manual Chapter 9 STRING TYPE

TURBO Pascal offers the convenience of string types for processing of character strings, i.e. sequences of characters. String types are struc tured types, and are in many ways similar to array types (see chapter 10). There is, however, one major difference between these: the number of characters in a string (i.e. the length of the string) may vary dynami cally between 0 and a specified upper limit, whereas the number of ele ments in an array is fixed.

String Type Definition

The definition of a string type must specify the maximum number of characters it can contain, i.e. the maximum length of strings of that type. The definition consists of the reserved word string followed by the maximum length enclosed in square brackets. The length is specified by an integer constant in the range 1 through 255. Notice that strings do not have a default length; the length must always be specified.

Example: type FileName = string[14]; ScreenLine = string[80];

String variables occupy the defined maximum length in memory plus one byte which contains the current length of the variable. The individual characters within a string are indexed from 1 through the length of the string.

String Expressions

Strings are manipulated by the use of string expressions. String expres sions consist of string constants, string variables, function designators, and operators.

STRING TYPE 67 String Expressions

The plus-sign may be used to concatenate strings. The Concat function (see page 71 ) performs the same function, but the + operator is often more convenient. If the length of the result is greater than 255, a run time error occurs.

Example: 'TURBO' + 'Pascal' 'TURBO Pascal' '123' + '.' + '456' '123.456' 'A ' + 'B' + ' C ' + 'D ' 'ABCD'

The relational operators =, < >, >, <, > =, and < = are lower in precedence than the concatenation operator. When applied to string operands, the result is a Boolean value ( True or False). When compar ing two strings, single characters are compared from the left to the right according to their ASCII values. If the strings are of different length, but equal up to and including the last character of the shortest string, then the shortest string is considered the smaller. Strings are equal only if their lengths as well as their contents are identical.

Examples: 'A' < 'B' is true 'A' > 'h' is false '2' < '12' is false 'TURBO' = 'TURBO' is true 'TURBO ' = 'TURBO' is false 'Pascal Compiler' < 'Pascal compiler' is true

String Assignment

The assignment operator is used to assign the value of a string expres sion to a string variable.

Example: Age := 'fiftieth'; Line := 'Many happy returns on your' + Age + ' hirthdc

If the maximum length of a string variable is exceeded (by assigning too many characters to the variable), the exceeding characters are truncat ed. E.g., if the variable Age above was declared to be of type string[5], then after the assignment, the variable will only contain the five leftmost characters: 'fifth'.

68 TURBO Pascal Reference Manual String Procedures

String Procedures

The following standard string procedures are available in TURBO Pas cal:

Delete

Syntax: Delete ( St , Pos , Num );

Delete removes a substring containing Num characters from St starting at position Pos. St is a string variable and both Pos and Num are integer expressions. If Pos is greater than Length ( St ), no characters are re moved. If an attempt is made to delete characters beyond the end of the string (i.e. Pos + Num exceeds the length of the string), only charac ters within the string are deleted. If Pos is outside the range 1.. 255, a run time error occurs.

If St has the value 'ABCDEFG' then: Delete (St, 2,4) will give St the value 'AFG'. Delete (St, 2,10) will give St the value 'A'.

Insert

Syntax: Insert ( Obj, Target, Pos);

Insert inserts the string Obj into the string Target at the position Pos. Obj is a string expression, Target is a string variable, and Pas is an in teger expression. If Pos is greater than Length( Targe~, then abj is con catenated to Target. If the result is longer than the maximum length of Target, then excess characters will be truncated and Target will only contain the leftmost characters. If Pas is outside the range 1 .. 255, a run time error occurs.

If St has the value 'ABCDEFG' then: Insert ( 'XX' , st, 3) will give St the value 'ABXXCDEFG'

STRING TYPE 69 String Procedures

Sfr

Syntax: Str (Va/ue:n, St);

The Str procedure converts the numeric value of Value into a string and stores the result in St. Value is a write parameter of type integer or of type real, and St is a string variable. Write parameters are expressions with special formatting commands (see page 112). Note that ifthe field isn't specified, the number will be left-justified.

If I has the value 1234 then: S t r ( I : 5 , S t) gives St the value , 1234'.

If X has the value 2.5E4 then: St r (X: 10: 0, St) gives St the value , 2500'. 8-bit systems only: a function using the Str procedure must never be called by an expression in a Write or Writeln statement.

Val

Syntax: Val ( St, Var, Code);

Val converts the string expression St to an integer or a real value (depending on the type of Vat) and stores this value in Var. St must be a string expressing a numeric value according to the rules applying to numeric constants (see page 43 ). Neither leading nor trailing spaces are allowed. Var must be an Integer or a Real variable and Code must be an integer variable. If no errors are detected, the variable Code is set to O. Otherwise Code is set to the position of the first character in error, and the value of Var is undefined.

If St has the value '234' then: Val (St, I, Resul t) gives I the value 234 and Result the value 0

If St has the value '12x' then: Val (St, I, Resul t) gives I an undefined value and Result the value 3

If St has the value '2.5E4', and X is a Real variable, then: Val (St, X, Resul t) gives X the value 2500 and Result the value 0

8-bit systems only: a function using the Var procedure must never be called by an expression in a Write or Writeln statement.

70 TURBO Pascal Reference Manual String Functions

String Functions

The following standard string functions are available in TURBO Pascal:

Copy

Syntax: Copy ( St , Pos , Num );

Copy returns a substring containing Num characters from St starting at position Pos. St is a string expression and both Pos and Num are in teger expressions. If Pos exceeds the length of the string, the empty string is returned. If an attempt is made to get characters beyond the end of the string (Le. Pos + Num exceeds the length of the string), only the characters within the string are returned. If Pos is outside the range 1 .. 255, a run time error occurs.

If St has the value 'ABCOEFG' then: Copy ( St , 3,2) returns the value 'CD' Copy (St, 4,10) returns the value 'OEFG' Copy ( St ,4,2) returns the value 'DE'

Concat

Syntax: Concat ( St1 , St2 { , StN } );

The Concat function returns is a string which is the concatenation of its arguments in the order in which they are specified. The arguments may be any number of string expressions separated by commas ( St1, St2 .. StN). If the length of the result is greater than 255, a run-time error oc curs. As explained in page 68 , the + operator can be used to obtain the same result, often more conveniently. Concat is included only to maintain compatibility with other Pascal compilers.

If St1 has the value 'TURBO' and St2 the value 'is fastest' then:

Concat(St1, I PASCAL ',St2)

returns the value 'TURBO PASCAL is fastest'

STRING TYPE 71 String Functions

Length

Syntax: Length ( St);

Returns the length of the string expression St, i.e. the number of char acters in St. The type of the result is integer.

If St has the value '123456789' then: Length (St) returns the value 9

Pos

Syntax: Pos ( Obj, Target);

The Pas function scans the string Target to find the first occurrence of Obj within Target. Obj and Target are string expressions, and the type of the result is integer. The result is an integer denoting the position within Target of the first character of the matched pattern. The position of the first character in a string is 1. If the pattern is not found, Pas re turns O.

If St has the value 'ABCDEFG' then Pos ( 'DE' , St) returns the value 4 Pos ( 'H' , St ) returns the value 0

72 TURBO Pascal Reference Manual Strings and Characters

Strings and Characters

String types and the standard scalar type Char are compatible. Thus, whenever a string value is expected, a char value may be specified in stead and vice versa. Furthermore, strings and characters may be mixed in expressions. When a character is assigned a string value, the length of the string must be exactly one; otherwise a run-time error occurs.

The characters of a string variable may be accessed individually through string indexing. This is achieved by appending an index expression of type integer, enclosed in square brackets, to the string variable.

Examples: Buffer[5] Line[Length(Line)-l] Ord(Line[O] )

As the first character of the string (at index 0) contains the length of the string, Length(String) is the same as Ord(String[O]). If as signment is made to the length indicator, it is the responsibility of the programmer to check that it is less than the maximum length of the string variable. When the range check compiler directive R is active ({ $R + }), code is generated which insures that the value of a string index expression does not exceed the maximum length of the string variable. It is, however, still possible to index a string beyond its current dynamic length. The characters thus read are random, and assignments beyond the current length will not affect the actual value of the string variable.

STRING TYPE 73 Strings and Characters

Notes:

74 TURBO Pascal Reference Manual Chapter 10 ARRAY TYPE

An array is a structured type consisting of a fixed number of com ponents which are all of the same type, called the component type or the base type. Each component can be explicitly accessed by indices into the array. Indices are expressions of any scalar type placed in square brackets suffixed to the array identifier, and their type is called the index type.

Array Definition

The definition of an array consists of the reserved word array followed by the index type, enclosed in square brackets, followed by the reserved word of, followed by the component type.

Examples: type Day = (Mon,Tue,Wed,Thu,Fri,Sat,Sun) var WorkHour array[l .. 8] of Integer; Week : array[l .. 7] of Day;

type Players (Playerl,Player2,Player3,Player4); Hand (One,Two,Pair,TwoPair,Three,Straight, Flush,FullHouse,Four,StraightFlush,RSF); LegalBid 1. .200; Bid array[Players] of LegalBid; var Player array[Players] of Hand; Pot Bid;

An array component is accessed by suffixing an index enclosed in square brackets to the array variable identifier:

Player[Player3] := FullHouse; Pot[Player3] := 100; Player[Player4] := Flush; Pot[Player4] := 50;

ARRAY TYPE 75 Array Definition

As assignment is allowed between any two variables of identical type, entire arrays can be copied with a single assignment statement.

The R compiler directive controls the generation of code which will per form range checks on array index expressions at run-time. The default mode is passive, i.e. { $R-}, and the { $R +} setting causes all index ex pressions to be checked against the limits of their index type.

Multidimensional Arrays

The component type of an array may be any data type, i.e. the com ponent type may be another array. Such a structure is called a multidi mensional array.

Example: type Card (Two,Three,Four,Five,Six,Seven,Eight,Nine, Ten,Knight,Queen,King,Ace); Suit (Hearts,Spade,Clubs,Diamonds); AIICards array[Suit] of array[1 .. 13] of Card; var Deck: AIICards;

A mUlti-dimensional array may be defined more conveniently by specify ing the multiple indices thus:

type AIICards = array[Suit,l .. 13] of Card;

A similar abbreviation may be used when selecting an array component:

Deck[ Hearts, 10] is equivalent to Deck[ Hearts] [10]

It is, of course, possible to define mUlti-dimensional arrays in terms of previously defined array types.

76 TURBO Pascal Reference Manual Multidimensional Arrays

Example: type Pupils string[ 20] ; Class array[l .. 30] of Pupils; School array[l .. 100] of Class; var J,P,Vacant Integer ClassA, ClassB Class; NewTownSchool: School;

After these definitions, all of the following assignments are legal:

ClassA[J]:='Peter'; NewTownSchool[5][21]:='Peter Brown'; NewTownSchool [8, J] : =NewTownSchool [7, J]; {pupil no. Jchangcd class} ClassA[ Vacant] : =ClassB[ P]; {pupil no. Pchanges Class and number}

Character Arrays

Character arrays are arrays with one index and components of the stan dard scalar type Char. Character arrays may be thought of as strings with a constant length.

In TURBO Pascal, character arrays may participate in string expres sions, in which case the array is converted into a string of the length of the array. Thus, arrays may be compared and manipulated in the same way as strings, and string constants may be assigned to character ar rays, as long as they are of the same length. String variables and values computed from string expressions cannot be assigned to character ar rays.

Predefined Arrays

TURBO Pascal offers two predefined arrays of type Byte, called Mem and Port, which are used to access CPU memory and data ports. These are discussed in chapters 20,21, and 22.

ARRAY TYPE 77 Predefined Arrays

Notes:

78 TURBO Pascal Reference Manual Chapter 11 RECORD TYPE

A record is a structure consisting of a fixed number of components, called fields. Fields may be of different type and each field is given a name, the field identifier, which is used to select it.

Record Definition

The definition of a record type consists of the reserved word record succeeded by a field list and terminated by the reserved word end. The field list is a sequence of record sections separated by semi-colons, each consisting of one or more identifiers separated by commas, fol lowed by a colon and either a type identifier or a a type descriptor. Each record section thus specifies the identifier and type of one or more fields.

Example: type DaysOfMonth l. .31; Date = record Day: DaysOfMonth; Month: (Jan,Feb,Mar,Apr,May,Jun, Ju1y,Aug,Sep,Oct,Nov,Dec); Year: 1900 .. 1999; end; var Birth: Date; WorkDay: array[l .. 5] of date;

Day, Month, and Year are field identifiers. A field identifier must be unique only within the record in which it is defined. A field is referenced by the variable identifier and the field identifier separated by a period.

Examples:

Birth.Month := Jun; Birth.Year := 1950; WorkDay[Current] := WorkDay[Current-1];

RECORD TYPE 79 Record Definition

Note that, similar to array types, assignment is allowed between entire records of identical types. As record components may be of any type, constructs like the following record of records of records are possible:

type Name record FamilyName: string[32]; ChristianNames: array[l .. 3] of string[16]; end; Rate = record NormalRate, OverTime, NightTime, Weekend: Integer end; Date record Day: 1. .31; Month: (Jan,Feb,Mar,Apr,May,Jun, July,Aug,Sep,Oct,Nov,Dec); Year: 1900 .. 1999; end; Person record ID: Name; Time: Date; end; Wages record Individual: Person; Cost: Rate; end

var Salary, Fee: Wages;

Assuming these definitions, the following assignments are legal:

Salary := Fee; Salary.Cost.Overtime := 950; Salary.lndividual.Time := Fee.lndividual.Time; Salary.lndividual.ID.FamilyName := 'Smith'

80 TURBO Pascal Reference Manual With Statement

With Statement

The use of records as described above does sometimes result in rather lengthy statements; it would often be easier if we could access individu al fields in a record as if they were simple variables. This is the function of the with statement: it 'opens up' a record so that field identifiers may be used as variable identifiers.

A with statement consists of the reserved word with followed by a list of record variables separated by commas followed by the reserved word do and finally a statement.

Within a with statement, a field is designated only by its field identifier, i.e. without the record variable identifier:

with Salary do begin Individual := NewEmployee; Cost := StandardRates; end;

Records may be nested within with statements, i.e. records of records may be 'opened' as shown here:

with Salary, Individual, ID do begin FamilyName := 'Smith'; ChristianNames[l] 'James'; end

This is equivalent to:

with Salary do with Individual do with ID do

The maximum 'depth' of this nesting of with sentences, i.e. the max imum number of records which may be 'opened' within one block, depends on your implementation and is discussed in chapters 20, 21, and 22.

RECORD TYPE 81 Variant Records

Variant Records

The syntax of a record type also provides for a variant part, i.e. alterna tive record structures which allows fields of a record to consist of a different number and different types of components, usually depending on the value of a tag field.

A variant part consists of a tag-field of a previously defined type, whose values determine the variant, followed by labels corresponding to each possible value of the tag field. Each label heads a field list which defines the type of the variant corresponding to the label.

Assuming the existence of the type: Origin = (Citizen, Alien);

and of the types Name and Date, the following record allows the field CitizenShip to have different structures depending on whether the value of the field is Citizen or Alien: type Person record PersonName: Name; BirthDate: Date; case CitizenShip: Origin of Citizen: (BirthPlace: Name); Alien: (CountryOfOrigin: Name; DateOfEntry: Date; PermittedUntil: Date; PortOfEntry: Name); end;

In this variant record definition, the tag-field is an explicit field which may be selected and updated like any other field. Thus, if Passenger is a variable of type Person, statements like the following are perfectly legal:

Passenger. CitizenShip := Citizen; with Passenger, PersonName do if' Ci tizenShip = Alien then wri teln( FamilyName) ;

82 TURBO Pascal Reference Manual Variant Records

The fixed part of a record, i.e. the part containing the common fields, must always precede the variant part. In the above example, the fields PersonName and BirthDate are the fixed fields. A record can only have one variant part. In a variant, the parentheses must be present, even if they will enclose nothing.

The maintenance of tag field values is the responsibility of the program mer and not of TURBO Pascal. Thus, in the Person type above, the field DateOfEntry can be accessed even if the value of the tag field CitizenShip is not Alien. Actually, the tag field identifier may be omitted altogether, leaving only the type identifier. Such record variants are known as free unions, as opposed to record variants with tag fields which are called discriminated unions. The use of free unions is infre quent and should only be practiced by experienced programmers.

RECORD TYPE 83 Variant Records

Notes:

84 TURBO Pascal Reference Manual Chapter 12 SET TYPE

A set is a collection of related objects which may be thought of as a whole. Each object in such a set is called a member or an element of the set. Examples of sets could be:

1) All integers between 0 and 100 2) The letters of the alphabet 3) The consonants of the alphabet

Two sets are equal if and only if their elements are the same. There is no ordering involved, so the sets [1,3,5], [5,3,1] and [3,5,1] are all equal. If the members of one set are also members of another set, then the first set is said to be included in the second. In the examples above, 3) is included in 2).

There are three operations involving sets, similar to the operations addi tion, multiplication and subtraction operations on numbers:

The union (or sum) of two sets A and B (written A + B) is the set whose members are members of either A or B. For instance, the un ion of [1,3,5,7] and [2,3,4] is [1,2,3,4,5,7].

The intersection (or product) of two sets A and B (written A *B) is the set whose members are the members of both A and B. Thus, the in tersection of [1,3,4,5,7] and [2,3,4] is [3,4].

The relative complement of B with respect to A (written A-B) is the set whose members are members of A but not of B. For instance, [1,3,5,7]-[2,3,4] is [1,5,7].

Set Type Definition

Although in mathematics there are no restrictions on the objects which may be members of a set, Pascal only offers a restricted form of sets. The members of a set must all be of the same type, called the base type, and the base type must be a simple type, i.e. any scalar type ex cept real. A set type is introduced by the reserved words set of followed by a simple type.

SET TYPE 85 Set Type Definition

Examples: type DaysOfMonth = set of o .. 31; WorkWeek = set of (Mon, Tues, Wed, Th, Fri) ; Letter = set of 'A' .. ' Z' ; AdditiveCo1ors = set of (Red,Green,B1ue); Characters = set of Char;

In TURBO Pascal, the maximum number of elements in a set is 256, and the ordinal values of the base type must be within the range 0 through 255.

Set Expressions

Set values may be computed from other set values through set expres sions. Set expressions consist of set constants, set variables, set con structors, and set operators.

Set Constructors

A set constructor consists of one or more element specifications, separated by commas, and enclosed in square brackets. An element specification is an expression of the same type as the base type of the set, or a range expressed as two such expressions separated by two consecutive periods (.. ).

Examples: ['T', 'U', 'R', 'B', '0'] [X, Y] [X .. Y] [1. .5] ['A' .. 'Z', 'a' .. 'z', '0' .. '9'] [1,3 .. 10,12] [ ]

The last example shows the empty set, which, as it contains no expres sions to indicate its base type, is compatible with all set types. The set [1 .. 5] is equivalent to the set [1,2,3,4,5]. If X> Y then [X .. Y] denotes the empty set.

86 TURBO Pascal Reference Manual Set Expressions

Set Operators

The rules of composition specify set operator precedency according to the following three classes of operators:

1) * Set intersection.

2) + Set union. Set difference.

3) Test on equality. <> Test on inequality. >= True if all members of the second operand are included in the first operand. <= True if all members of the first operand are included in the second operand. IN Test on set membership. The second operand is of a set type, and the first operand is an expression of the same type as the base type of the set. The result is true if the first operand is a member of the second operand, otherwise it is false.

Set disjunction (when two sets contain no common members) may be expressed as: A * B = [];

that is, the intersection between the two sets is the empty set. Set ex pressions are often useful to clarify complicated tests. For instance, the test:

if (Ch-'T') or (Ch.'U') or (Ch.'R') or (Ch.'B') or (Ch.'O')

can be expressed much clearer as:

Ch in [' T' , 'U' , 'R' , 'B' , '0' ]

And the test:

if (Ch >= '0' ) and (Ch <= '9' ) then .

is better expressed as:

if Ch in[ '0' .. '9'] then ...

SET TYPE 87 Set Assignments

Set Assignments

Values resulting from set expressions are assigned to set variables us ing the assignment operator . - .

Examples: type ASCII = set of O.. 127; var NoPrint,Print,AllChars: ASCII; begin A11Chars := [0 .. 127]; NoPrint := [0 .. 31,127]; Print A11Chars - NoPrint; end.

88 TURBO Pascal Reference Manual Chapter 13 TYPED CONSTANTS

Typed constants are a TURBO specialty. A typed constant may be used exactly like a variable of the same type. Typed constants may thus be used as 'initialized variables', because the value of a typed constant is defined, whereas the value of a variable is undefined until an assignment is made. Care should be taken, of course, not to assign values to typed constants whose values are actually meant to be constant.

The use of a typed constant saves code if the constant is used often in a program, because a typed constant is included in the program code only once, whereas an untyped constant is included every time it is used.

Typed constants are defined like untyped constants (see page 48 ), ex cept that the definition specifies not only the value of the constant but also the type. In the definition the typed constant identifier is succeeded by a colon and a type identifier, which is then followed by an equal sign and the actual constant.

Unstructured Typed Constants

An unstructured typed constant is a constant defined as one of the scalar types:

const NumberOfCars: Integer = 1267; Interest: Real = 12.67; Heading: string[7] = 'SECTION'; Xon: Char = "Q;

Contrary to untyped constants, a typed constant may be used in place of a variable as a variable parameter to a procedure or a function. As a typed constant is actually a variable with a constant value, it cannot be used in the definition of other constants or types. Thus, as Min and Max are typed constants, the following construct is illegal:

TYPED CONSTANTS 89 Unstructured Typed Constants

const Min: Integer = 0; Max: Integer = 50; type Range: array[Min .. Max] of integer

Structured Typed Constants

Structured constants comprise array constants, record constants, and set constants. They are often used to provide initialized tables and sets for tests, conversions, mapping functions, etc. The following sections describe each type in detail.

Array Constants The definition of an array constant consists of the constant identifier succeeded by a colon, and either a type definition or the type identifier of a previously defined array type followed by an equal sign, and the constant value expressed as a set of constants separated by commas and enclosed in parentheses. Examples: type Status = (Active,Passive,Waiting); StringRep = array[Status] of string[7]; const Stat: StringRep = ('active', 'passive', 'waiting');

The example defines the array constants Stat, which may be used to convert values of the scalar type Status into their corresponding string representations. The components of Stat are: Stat[Active] 'active' Stat[Passive] = 'passive' Stat[Waiting] = 'waiting'

The component type of an array constant may be any type except File types and Pointer types. Character array constants may be specified both as single characters and as strings. Thus, the definition:

90, TURBO Pascal Reference Manual Structured Typed Constants

const Digits: array[O .. 9] of Char = ('0',' 1', '2', '3', '4', '5', '6', '7', '8', '9');

may be expressed more conveniently as:

const Digits: array[O .. 9] of Char , 0123456789' ;

Multi-dimensional Array Constants

MUlti-dimensional array constants are defined by enclosing the con stants of each dimension in separate sets of parentheses, separated by commas. The innermost constants correspond to the rightmost dimen sions.

Example: type Cube = array[O .. 1,0 .. 1,0 .. 1] of integer; const Maze: Cube = (( ( 0, 1 ) , (2,3) ) , ( ( 4, 5 ) , ( 6, 7) ) ) ; begin Writeln(Maze[O,O,O], , 0' ); Writeln(Maze[O,O,l], , l' ); Writeln(Maze[O,l,O], , 2') ; Writeln(Maze[O,l,l], , 3' ); Writeln(Maze[l,O,O], , 4') ; Writeln(Maze[l,O,l], , 5' ); Writeln(Maze[l,l,O], , 6') ; Writeln(Maze[l,l,l], , 7') ; end.

Record Constants

The declaration of a record constant consists of the constant identifier succeeded by a colon, and either a type definition or the type identifier of a previously defined record type followed by an equal sign, and the constant value expressed as a list of field constants separated by semicolons and enclosed in parentheses.

Typed Constants 91 Structured Typed Constants

Examples: type Point record x, Y, Z: integer; end; OS = (CPM80,CPM86,MSDOS,Unix); U1 = (CCP,SomethingEIse,MenuMaster); Computer record OperatingSystems: array[l .. 4] of OS; User1nterface: U1; end; const Origo: Point = (X:O; Y:O; Z:O); SuperComp: Computer = (OperatingSystems: (CPM80,CPM86,MSDOS,Unix); User1nterface: MenuMaster); Planel: array[I .. 3] of Point = ((X:l;Y:4;Z:5),(X:lO;Y:-78;Z:45),(X:lOO;Y:lO;Z:-7));

The field constants must be specified in the same order as they appear in the definition of the record type. If a record contains fields of file types or pointer types, then constants of that record type cannot be specified. If a record constant contains a variant, then it is the responsibility of the programmer to specify only the fields of the valid variant. If the variant contains a tag field, then its value must be specified.

Set Constants

A set constant consists of one or more element specifications separated by commas, and enclosed in square brackets. An element specification must be a constant or a range expression consisting of two constants separated by two consecutive periods (.. ).

Example: type Up ... set of 'A' .. 'Z'; Low = set of 'a' .. 'z'; const UpperCase: Up = ['A' .. 'Z']; Vocals Low = ['a','e','i','o','u','y']; Delimiter: set of Char = [' ' .. 'I',':' .. '?','[' .. '",'{' .. ' I];

92 TURBO Pascal Reference Manual Chapter 14 FILE TYPES

Files provide a program with channels through which it can pass data. A file can either be a disk file, in which case data is written to and read from a magnetic device of some type, or a logical device, such as the pre-defined files Input and Output which refer to the computer's stan dard I/O channels; the keyboard and the screen.

A file consists of a sequence of components of equal type. The number of components in a file (the size of the file) is not determined by the definition of the file; instead the Pascal system keeps track of file accesses through a file pointer, and each time a component is written to or read from a file, the file pointer of that file is advanced to the next component. As all components of a file are of equal length, the position of a specific component can be calculated. Thus, the file pointer can be moved to any component in the file, providing random access to any ele ment of the file.

File Type Definition

A file type is defined by the reserved words file of followed by the type of the components of the file, and a file identifier is declared by the words file of, followed by the identifier of a previously defined file type.

Examples: type ProductName = string[80]; Product = file of record Name: ProductName; ItemNumber: Real; InStock: Real; MinStock: Real; Supplier: Integer; end; var ProductFile: Product; ProductNames: file of ProductName;

FILE TYPES 93 File Type Definition

The component type of a file may be any type, except a file type. (that is, with reference to the example above, file of Product is not allowed). File variables may appear in neither assignments nor expressions.

Operations on Files The following sections describe the procedures available for file han dling. The identifier FilVar used throughout denotes a file variable identifier declared as described above.

Assign Syntax: Assign(FilVar, Stt);

Str is a string expression yielding any legal file name. This file name is assigned to the file variable FilVar, and all further operation on FilVar will operate on the disk file Str. Assign should never be used on a file which is in use.

Rewrite

Syntax: Rewrite(FiIVat);

A new disk file of the name assigned to the file variable FilVar is created and prepared for processing, and the file pointer is set to the beginning of the file, i.e. component no. O. Any previously existing file with the same name is erased. A disk file created by rewrite is initially empty, i.e. it contains no elements.

The Reset and Rewrite procedures have a second optional parameter in Turbo Pascal 3.0. This parameter may be used with untyped files and allows you to specify the number of bytes per block. For example, you may specify a block size of 1 byte and perform a BlockRead of 128 blocks and achieve the same result as reading one block of 128 bytes.

The advantage of this second parameter is that your program no longer has to deal with truncating or bloating a file because the file was not divisible by 128 bytes.

94 TURBO Pascal Reference Manual Operations on Files

Reset Syntax: Reset(FilVary;

The disk file of the name assigned to the file variable FilVar is prepared for processing, and the file pointer is set to the beginning of the file, i.e. component no. O. FilVar must name an existing file, otherwise an 110 er ror occurs. This procedure also has a second, optional, parameter. See the Rewrite procedure above for more information. Read Syntax: Read(FilVar, Vary;

Var denotes one or more variables of the component type of FilVar, separated by commas. Each variable is read from the disk file, and fol lowing each read operation, the file pointer is advanced to the next com ponent.

Write Syntax: Write(FilVar, Vary;

Var denotes one or more variables of the component type of FilVar, separated by commas. Each variable is written to the disk file, and fol lowing each write operation, the file pointer is advanced to the next component.

Seek Syntax: Seek(FiIVar, n);

Seek moves the file pointer is moved to the n'th component of the file denoted by FilVar. n is an integer expression. The position of the first component is O. Note that in order to expand a file it is possible to seek one component beyond the last component. The statement Seek(FilVar, FileSize(FilVar));

thus places the file pointer at the end of the file (FileSize returns the number of components in the file, and as the components are numbered from zero, the returned number is one greater than the number of the last component).

FILE TYPES 95 Operations on Files

Flush

Syntax: Flush(FilVa,,;

Flush empties the internal sector buffer of the disk file FilVar, and thus assures that the sector buffer is written to the disk if any write opera tions have taken place since the last disk update. Flush also insures that the next read operation will actually perform a physical read from the disk file. Flush should never be used on a closed file.

Syntax: Close(FilVa,,;

The disk file associated with FilVar is closed, and the disk directory is updated to reflectthe new status ofthe file. It is always necessary to Close a file, even if it has only been read from-you would otherwise quickly run out of file handles.

Erase

Syntax: Erase(FilVa,,;

The disk file associated with FilVar is erased. If the file is open, i.e. if the file has been reset or rewritten but not closed, it is good programming practice to close the file before erasing it.

Rename

Syntax: Rename(FiIVar, St,,;

The disk file associated with FilVar is renamed to a new name given by the string expression Str. The disk directory is updated to show the new name of the file, and further operations on FilVar will operate on the file with the new name. Rename should never be used on an open file.

96 TURBO Pascal Reference Manual Operations on Files

Notice that it is the programmer's responsibility to assure that the file named by Str does not already exist. If it does, multiple occurrences of the same name may result. The following function returns True if the file name passed as a parameter exists, otherwise it returns False:

type Name=string[66];

function Exist(FileName: Name): boolean; Var Fil: file; begin Assign(Fil, FileName); {$I-} Reset (Fil ) ; close(Fil); {$I+ } Exist := (IOresult 0) end; File Standard Functions

The following standard functions are applicable to files:

EOF

Syntax: EOF(FilVar};

A Boolean function which returns True if the file pointer is positioned at the end of the disk file, i.e. beyond the last component of the file. If not, EOF returns False.

FilePos

Syntax: FilePos(FiIVar};

An integer function which returns the current position of the file pointer. The first component of a file is O.

FILE TYPES 97 File Standard Functions

FileSize

Syntax: FileSize(FilVal);

An integer function which returns the size of the disk file expressed as the number of components in the file. If FileSize(FilVal) is zero, the file is empty.

Using Files

Before using a file, the Assign procedure must be called to assign the file name to a file variable. Before input and/or output operations are performed, the file must be opened with a call to Rewrite or Reset. This call will set the file pointer to pOint to the first component of the disk file, i.e. FilePos(FilVar) = O. After Rewrite, FileSize(FilVar) is O.

A disk file can be expanded only by adding components to the end of the existing file. The file pointer can be moved to the end of the file by executing the following sentence: Seek(FilVar, FileSize(FilVar));

When a program has finished its input/output operations on a file, it should always call the Close procedure. Failure to do so may result in loss of data, as the disk directory is not properly updated.

The program below creates a disk file called PRODUCTS.DTA, and writes 100 records of the type Product to the file. This initializes the file for subsequent random access (Le. records may be read and written anywhere in the file).

98 TURBO Pascal Reference Manual Using Files

program InitProductFile; const MaxNumberOfProducts = 100; type ProductName = string[20]; Product = record Name: ProductName; ItemNumber: Integer; InStock: Real; Supplier: Integer; end; var ProductFile: file of Product; ProductRec: Product; I: Integer; begin Assign(ProductFile, 'PRODUCT.DTA'); Rewrite(ProductFile); {open the file and delete any data} with ProductRec do begin Name := "; InStock :- 0; Supplier := 0; for I := 1 to MaxNumberOfProducts do begin ItemNumber := I; Write(ProductFile,ProductRec); end; end; Close(ProductFile); end.

The following program demonstrates the use of Seek on random files. The program is used to update the ProductFile created by the program in the previous example.

FILE TYPES 99 Using Files

prograa UpDateProductFile; const MaxNumberOfProducts - 100; type ProductName - string[20]; Product - record Name: ProductName; ItemNumber: Integer; InStock: Real; Supplier: Integer; end; var ProductFile: rile or Product; ProductRec: Product; I, Pnr: Integer; begin Assign(ProductFile, 'PRODUCT.DTA'); Reset(ProductFile); Cl rScr; Write('Enter product number (O~ stop) '); Readln(Pnr); while Pnr in [l .. MaxNumberOfProducts] do begin Seek(ProductFile,Pnr-l); Read(ProductFile,ProductRec); with ProductRec do begin Write('Enter name of product (' ,Name:20,') '); Readln(Name); Write('Enter number in stock (' ,InStock:20:0,') '); Readln(InStock); Write('Enter supplier number (' ,Supplier:20, ') '); Readln(Supplier); ItemNumber:-Pnr; end; Seek(ProductFile,Pnr-l); Write(ProductFile,ProductRec); ClrScr; Writeln; Write('Enter product number (0- stop) '); Readln(Pnr); end; Close(ProductFile); end.

100 TURBO Pascal Reference Manual Text Files

Text Files

Unlike all other file types, text tiles are not simply sequences of values of some type. Although the basic components of a text file are charac ters, they are structured into lines, each line being terminated by an end-ot-line marker (a CR/LF sequence). The file is further ended by an end-ot-tile marker (a Ctrl-Z). As the length of lines may vary, the position of a given line in a file cannot be calculated. Text files can therefore only be processed sequentially. Furthermore, input and output cannot be per formed simultaneously to a text file.

Operations on Text Files

A text file variable is declared by referring to the standard type identifier Text. Subsequent file operations must be preceded by a call to Assign and a call to Reset or Rewrite must furthermore precede input or output operations.

Rewrite is used to create a new text file, and the only operation then al lowed on the file is the appending of new components to the end of the file. Reset is used to open an existing file for reading, and the only operation allowed on the file is sequential reading. When a new textfile is closed, an end-of-file mark is automatically appended to the file.

Character input and output on text files is made with the standard pro cedures Read and Write. Lines are processed with the special text file operators Readln, Writeln, and Eoln.

ReadLn

Syntax: Readln(Filva,,;

Skips to the beginning of the next line, i.e. skips all characters up to and including the next CR/LF sequence.

WriteLn

Syntax: WriteLn(Filva,,;

Writes a line marker, i.e. a CR/LF sequence, to the textfile.

FILE TYPES 101 Text Files

Eoln

Syntax: Eoln(Filvar);

A Boolean function which returns True if the end of the current line has been reached, i.e. if the file pointer is positioned at the CR character of the CR/LF line marker. If EOF(Filvar) is true, Eoln(Filvar) is also true.

SeekEoln

Syntax: SeekEoln(FiIVar);

Similar to Eoln, except that it skips blanks and TABs before it tests for an end-of-Iine marker. The type of the result is boolean.

SeekEof

Syntax: SeekEof(FilVar);

Similar to EOF, except that it skips blanks, TABs, and end-of-Iine mark ers (CR/LF sequences) before it tests for an end-of-file marker. The type of the result is boolean.

When applied to a text file, the EOF function returns the value True if the file pointer is positioned at the end-of-file mark (the CTRL/Z char acter ending the file). The Seek and Flush procedures and the FilePos and FileSize functions are not applicable to text files.

The following sample program reads a text file from disk and prints it on the pre-defined device Lst which is the printer. Words surrounded by Ctrl-S in the file are printed underlined:

102 TURBO Pascal Reference Manual Text Files

program TextFileDemo; var FilVar: Text; Line, ExtraLine: string[ 255] ; I: Integer; UnderLine: Boolean; FileName: string[ 14] ; begin UnderLine := False; Write( 'Enter name of file to list: '); Readln(FileName); Assign(FilVar,FileName); Reset (Fil Var) ; while not Eof(FilVar) do begin Readln(FilVar,Line); I := 1; ExtraLine := "; for I := 1 to Length(Line) do begin if Line[I]<>AS then begin Write(Lst,Line[I]); if UnderLine then ExtraLine := ExtraLine+' , else ExtraLine := ExtraLine+' '; end else UnderLine := not UnderLine; end; Write(Lst,AM); Writeln(Lst,ExtraLine); end; {while not Eo f} end.

Further extensions of the procedures Read and Write, which facilitate convenient handling of formatted input and output, are described on pages 108 and 111, respectively.

FILE TYPES 103 Text Files

Logical Devices

In TURBO Pascal, external devices such as terminals, printers, and modems are regarded as logical devices, and are treated like text files. The following logical devices are available:

CON: The console device. Output is sent to the operating system's console output device, usually the CRT, and input is obtained from the console input device, usually the keyboard. This means that each Read or Readln from a text file assigned to the CON: device will input an entire line into a line buffer, and that the operator is provided with a set of editing facilities during line input. For more details on console input, please refer to pages 105 and 108.

TRM: The terminal device. Output is sent' to the operating system's console output device, usually the CRT, and input is obtained from the console input device, usually the keyboard. Input characters are echoed, unless they are control characters. The only control character echoed is a car riage return (CR), which is echoed as CR/LF.

KBD: The keyboard device (input only). Input is obtained from the operating system's console input device, usually the keyboard. Input is not echoed.

LST: The list device (output only). Output is sent to the operating system's list device, typically the line printer.

AUX: The auxiliary device. In PC/MS-DOS, this is COM1:; in CP/M it is RDR: and PUN:.

USR: The user device. Output is sent to the user output routine, and input is obtained from the user input routine. For further details on user input and output, please refer to pages 209 ,241 ,and 272 .

These logical devices may be accessed through the pre-assigned files discussed on page 105 or they may be assigned to file variables, exactly like a disk file. There is no difference between Rewrite and Reset on a file assigned to a logical device, Close performs no function, and an at tempt to Erase such a file will cause an I/O error.

104 TURBO Pascal Reference Manual Text Files

The standard functions Eot and Eoln operate differently on logical dev ices than on disk files. On a disk file, Eot returns True when the next character in the file is a Ctrl-Z, or when physical EOF is encountered, and Eoln returns True when the next character is a CR or a Ctrl-Z. Thus, Eot and Eoln are in fact 'look ahead' routines.

As you cannot look ahead on a logical device, Eoln and Eot operate on the last character read instead of on the next character. In effect, Eot returns True when the last character read was a Ctrl-Z, and Eoln re turns True when the last character read was a CR or a Ctrl-Z. The fol lowing table provides an overview of the operation of Eoln and Eot.

On Files On Logical Devices

Eoln is true if is next character if current character CR or Ctrl-Z or if is CR or Ctrl-Z EOF is true

Eof is true if next character is if current character Ctrl-Z or if physical is Ctrl-Z EOF is met

Table 14-1: Operation ot EOLN and Eot

Similarly, the Readln procedure works differently on logical devices than on disk files. On a disk file, Readln reads all characters up to and includ ing the CR/LF sequence, whereas on a logical device it only reads up to and including the first CR. The reason for this is again the inability to 'look ahead' on logical devices, which means that the system has no way of knowing what character will follow the CR.

Standard Files

As an alternative to assigning text files to logical devices as described above, TURBO Pascal offers a number of pre-declared text files which have already been assigned to specific logical devices and prepared for processing. Thus, the programmer is saved the reset/rewrite and close processes, and the use of these standard files further saves code:

FILE TYPES 105 Text Files

Input The primary input file. This file is assigned to either the CON: device or to the TRM: device (see below for further detail). Output The primary output file. This file is assigned to either the CON: device or to the TRM: device (see below for further detail). Con Assigned to the console device (CON:). Trm Assigned to the terminal device (TRM:) . . Kbd Assigned to the keyboard device (KBD:). Lst Assigned to the list device (LST:). Aux Assigned to the auxiliary device (AUX:). Usr Assigned to the user device (USR:).

Notice that the use of Assign, Reset. Rewrite, and Close on these files is illegal.

When the Read procedure is used without specifying a file identifier, it always inputs a line, even if some characters still remain to be read from the line buffer, and it ignores Ctrl-Z, forcing the operator to terminate the line with RETURN. The terminating RETURN is not echoed, and internal ly the line is stored with a Ctrl-Z appended to the end of it. Thus, when less values are specified on the input line than there are parameters in the parameter list, any Char variables in excess will be set to Ctrl-Z, strings will be empty, and numeric variables will remain unaltered.

The B compiler directive is used to control this 'forced read' feature above. The default state is {$B +}, and in this state, read statements without a file variable will always cause a line to be input from the con sole. If a {$B-} compiler directive is placed at the beginning of the pro gram (before the declaration part), the shortened version of read will act as if the input standard file had been specified, Le.:

Read(v1,v2, ... ,vn) equals Read(input,v1,v2, ... ,vn)

In this case, lines are only input when the line buffer has been emptied. The {$S-} state follows the definition of Standard Pascal 110, whereas the default {$S +} state, not conforming to the standard in all aspects, provides better control of input operations.

If you don't want input echoed to the screen, you should read from the standard file Kbd: Read(Kbd, Var)

106 TURBO Pascal Reference Manual Text Files

As the standard files Input and Output are used very frequently, they are chosen by default if no file identifier is stated. The following list shows the abbreviated text file operations and their equivalents:

Write(Ch) Write(Output, Ch) Read(Ch) Read(lnput, Ch) Writeln Writeln(Output) Readln Readln(lnput) Eof Eof(lnput) Eoln Eoln(lnput)

The following program shows the use of the standard file Lst to list the file ProductFile (see page 99) on the printer:

program ListProductFile; const MaxNumberOfProducts - 100; type ProductName = string[20); Product = record Name: ProductName; ItemNumber: Integer; InStock: Real; Supplier: Integer; end; var ProductFile: file of Product; ProductRec: Product; I: Integer; begin Assign(ProductFile, 'PRODUCT.DTA'); Reset(ProductFile); for I := 1 to MaxNumberOfProducts do begin Read(ProductFile,ProductRec); with ProductRec do begin if Name<>" then Writeln(Lst, 'Item: ',ItemNumber:5,' " Name:20, From: " Supplier:5, , Now in stock: ',InStock:O:O); end; end; Close(ProductFile); end.

FILE TYPES 107 Text Input and Output

Text Input and Output

Input and output of data in readable form is done through text files as described on page 101. A text file may be assigned to any device, i.e. a disk file or one of the standard I/O devices. Input and output on text files is done with the standard procedures Read, Readln, Write, and Wri teln which use a special syntax for their parameter lists to facilitate max imum flexibility of input and output.

In particular, parameters may be of different types, in which case the I/O procedures provide automatic data conversion to and from the basic Char type of text files.

If the first parameter of an I/O procedure is a variable identifier representing a text file, then I/O will act on that file. If not, I/O will act on the standard files Input and Output. See page 105 for more detail.

Read Procedure

The Read procedure provides input of characters, strings, and numeric data. The syntax of the Read statement is: Read(Varl,Var2, ... ,VarN) or Read(FilVar,Varl,Var2, ... ,VarN)

where Var1, Var2, ... , VarN are variables of type Char, String, Integer or Real. In the first case, the variables are input from the standard file Input, usually the keyboard. In the second case, the variables are input from the text file which is previously assigned to FilVar and prepared for reading.

With a variable of type Char, Read reads one character from the file and assigns that character to the variable. If the file is a disk file, Eoln is true if the next character is a CR or a Ctrl-Z, and Eof is true if the next char acter is a Ctrl-Z, or physical end-of-file is met. If the file is a logical dev ice (including the standard files Input and Outpuf), Eoln is true if the character read was a CR or if Eof is True, and Eof is true if the charac ter read was a Ctrl-Z.

108 TURBO Pascal Reference Manual Text Input and Output

With a variable of type string, Read reads as many characters as al lowed by the defined maximum length of the string, unless Eoln or Eat is reached first. Eoln is true if the character read was a CR or if Eat is True, and Eat is true if the last character read is a Ctrl-Z, or physical end-of-file is met.

With a numeric variable (Integer or Rea~, Read expects a string of char acters which complies with the format of a numeric constant of the relevant type as defined on page 43 . Any blanks, TABs, CRs, or LFs preceding the string are skipped. The string must be no longer than 30 characters, and it must be followed by a blank, a TAB, a CR, or a Ctrl-Z. If the string does not conform to the expected format, an I/O error oc curs. Otherwise the numeric string is converted to a value of the ap propriate type and assigned to the variable. When reading from a disk file, and the input string is ended with a blank or a TAB, the next Read or Readln will read that blank or TAB. For both disk files and logical devices, Eoln is true if the string was ended with a CR or a Ctrl-Z, and Eat is true if the string was ended with a Ctrl-Z.

A special case of numeric input is when Eoln or Eat is true at the be ginning of the Read (e.g. if input from the keyboard is only a CR). In that case no new value is assigned to the variable, and the variable retains its former value.

If the input file is assigned to the console device (CON:), or if the stan dard file Input is used in the { $B + } mode (default), special rules apply to the reading of variables. On a call to Read or Readln, a line is input from the console and stored into a buffer, and the reading of variables then uses this buffer as the input source. This allows for editing during entry. The following editing facilities are available:

BACKSPACE and DEL Backspaces one character position and deletes the character there. BACKSPACE is usually generated by pressing the key marked BS or BACKSPACE or by pressing Ctrl-H. DEL is usually generated by the key thus marked, or in some cases RUB or RUBOUT.

Esc and Ctrl-X Backspaces to the beginning of the line and erases all characters input.

File Types 109 Text Input and Output

Ctrl-D Recalls one character from the last input line.

Ctrl-R Recalls the last input line.

RETURN and Ctrl-M Terminates the input line and stores an end-of-line marker (a CR/LF se quence) in the line buffer. This code is generated by pressing the key marked RETURN or ENTER. The CR/LF is not echoed to the screen.

Ctrl-Z Terminates the input line and stores an end-of-file marker (a Ctrl-Z char acter) in the line buffer.

The input line is stored internally with a Ctrl-Z appended to the end of it. Thus, if fewer values are specified on the input line than the number of variables in Reads parameter list, any Char variables in excess will be set to Ctrl-Z, Strings will be empty, and numeric variables will remain un changed.

The maximum number of characters that can be entered on an input line from the console is 127 by default. However, you may lower this limit by assigning an integer in the range 0 through 127 to the predefined vari able BufLen.

Example: Write('File name (max. 14 chars): '); BufLen:=14; Read(Fi1eName);

Notice that assignments to BufLen affect only the immediately following Read. After that, BufLen is restored to 127.

Readln Procedure

The Readln procedure is identical to the Read procedure, except that after the last variable has been read, the remainder of the line is skipped. I.e., all characters up to and including the next CR/LF se quence (or the next CR on a logical device) are skipped. The syntax of the procedure statement is:

110 TURBO Pascal Reference Manual Text Input and Output

Readln(Varl,Var2, ... ,VarN) or Readln(FilVar,Varl,Var2, ... ,VarN)

After a Readln, the following Read or Readln will read from the begin ning of the next line. Readln may also be called without parameters: Readln or Readln(FilVar)

in which case the remaining of the line is skipped. When Readln is read ing from the console (standard file Input or a file assigned to CON:), the terminating CR is echoed to the screen as a CR/LF sequence, as op posed to Read.

Write Procedure

The Write procedure provides output of characters, strings, boolean values, and numeric values. The syntax of a Write statement is:

Write(Var1, Var2, ... , VarN) or Write{FilVar, Var1, Var2, ... , VarN)

where Var1, Var2, ... , VarN (the write parameters) are variables of type Char, String, Boolean, Integer or Real, optionally followed by a colon and an integer expression defining the width of the output field. In the first case, the variables are output to the standard file Output, usually the screen. In the second case, the variables are output to the text file which is previously assigned to FilVar.

The format of a write parameter depends on the type of the variable. In the following descriptions of the different formats and their effects, the symbols:

I, m, n denote Integer expressions, R denotes a Real expression, Ch denotes a Char expression, S denotes a String expression, and B denotes a Boolean expression.

File Types 111 Text Input and Output

Write Parameters

Ch The character Ch is output.

Ch:n The character Ch is output right-adjusted in a field which is n characters wide, i.e. Ch is preceded by n - 1 blanks.

S The string S is output. Arrays of characters may also be output, as they are compatible with strings.

S:n The string S is output right-adjusted in a field which is n characters wide, i.e. S is preceded by n - Length(S) blanks. a Depending on the value of a, either the word TRUE or the word FALSE is output.

a:n Depending on the value of a, either the word TRUE or the word FALSE is output right-adjusted in a field which is n characters wide.

The decimal representation of the value of I is output.

I:n The decimal representation of the value of I is output right-adjusted in a field which is n characters wide.

R The decimal representation of the value of R is output in a field 18 char acters wide, using floating point format. For R > = 0.0, the format is:

uu#.##########E*##

For R < 0.0, the format is:

u-#.##########E*##

where u represents a blank, # represents a digit, and * represents ei ther plus or minus.

R:n The decimal representation of the value of R is output, right adjusted in a field n characters wide, using floating point format. For R > = 0.0:

blanks#.digitsE*##

112 TURao Pascal Reference Manual Text Input and Output

For R < 0.0:

blanks-#.digitsE*##

where blanks represents zero or more blanks, digits represents from one to ten digits, # represents a digit, and * represents either plus or minus. As at least one digit is output after the decimal point, the field width is minimum 7 characters (8 for R < 0.0).

R:n:m The decimal representation of the value of R is output, right adjusted, in a field n characters wide, using fixed point format with m digits after the decimal point. No decimal part, and no decimal point, is output if m is O. m must be in the range 0 through 24; otherwise floating point for mat is used. The number is preceded by an appropriate number of blanks to make the field width n.

Writeln Procedure

The Writeln procedure is identical to the Write procedure, except that a CR/LF sequence is output after the last value. The syntax of the Writeln statement is:

Writeln(Var1, Var1, Var2, ... , VarN) or Writeln(FilVar, Var1, Var2, ... , VarN)

A Writeln with no write parameters outputs an empty line consisting of a CR/LF sequence:

Writeln or Writeln(FilVar)

File Types 113 Untyped Files

Untyped Files

Untyped files are low-level lID channels primarily used for direct access to any disk file using a record size of 128 bytes.

In input and output operations to untyped files, data is transferred directly between the disk file and the variable, thus saving the space re quired by the sector buffer required by typed files. An untyped file vari able therefore occupies less memory than other file variables. As an un typed file is furthermore compatible with any file, the use of an untyped file is therefore to be preferred if a file variable is required only for Erase, Rename or other non-input/output operations.

An untyped file is declared with the reserved word file:

var DataFile: file;

BlockRead / BlockWrite

All standard file handling procedures and functions except Read, Write, and Flush are allowed on untyped files. Read and Write are replaced by two special high-speed transfer procedures: BlockRead and Block Write. The syntax of a call to these procedures is:

BlockRead(FiIVar, Var, Recs) BlockWrite(FiIVar, Var, Recs)

BlockRead(FiIVar, Var, Recs, Result) BlockWrite(FilVar, Var, Recs, Result)

where FilVar variable identifier of an untyped file, Var is any variable, and Recs is an integer expression defining the number of 128-byte records to be transferred between the disk file and the variable. The op tional parameter Result returns the number of records actually transferred.

114 TURBO Pascal Reference Manual Untyped Files

The transfer starts with the first byte occupied by the variable Var. The programmer must insure that the variable Var occupies enough space to accommodate the entire data transfer. A call to BlockRead or BlockWrite also advances the file pointer Recs records.

A file to be operated on by BlockRead or BlockWrite must first be prepared by Assign and Rewrite or Reset. Rewrite creates and opens a new file, and Reset opens an existing file. After processing, Close should be used to ensure proper termination.

The standard function EOF works as with typed files. So do standard functions FilePos and FileSize and standard procedure Seek, using a component size of 128 bytes (the record size used by BlockRead and Block Write).

The following program uses untyped files to copy files of any type. Notice the use of the optional fourth parameter on BlockRead to check the number of records actually read from the source file.

program FileCopy; const RecSize 128; BufSize 200; var Source, Dest: File; SourceName, DestName: string[ 14]; Buffer: array[l .. RecSize,l .. BufSize] of Byte; RecsRead: Integer; begin Write( 'Copy from: '); Readln(SourceName); Assign(Source, SourceName); Reset(Source); Write(' To: '); Readln(DestName); Assign(Dest, DestName); Rewri te (Dest) ; repeat BlockRead(Source,Buffer,BufSize,RecsRead); BlockWrite(Dest,Buffer,RecsRead); until RecsRead = 0; Close(Source); Close(Dest); end.

File Types" 115 I/O checking

I/O checking

The I compiler directive is used to control generation of runtime I/O error checking code. The default state is active, i.e. {$I +} which causes calls to an I/O check routine after each I/O operation. I/O errors then cause the program to terminate, and an error message indicating the type of error is displayed.

If I/O checking is passive, i.e. { $1 -}, no run time checks are per formed. An I/O error thus does not cause the program to stop, but suspends any further I/O until the standard function 10result is called. When this is done, the error condition is reset and I/O may be per formed again. It is now the programmer's responsibility to take proper action according to the type of I/O error.' A zero returned by IOresult in dicates a successful operation, anything else means that an error oc curred during the last 1/0 operation. Appendix G lists all 110 error messages and their Numbers. Notice that as the error condition is reset when 10resuit is called, subsequent calls to 10resuit will return zero until the next I/O error occurs.

The IOresult function is very convenient in situations where a program halt is an unacceptable result of an I/O error, like in the following exam ple which continues to ask for a file name until the attempt to reset the file is successful (Le. until an existing file name is entered): procedure OpenlnFile; begin repeat Write( 'Enter name of input file'); Readln(InFileName); Assign(InFile, InFileName); {$I-} Reset(InFile) {$I+} ; OK := (IOresult = 0); if not OK then Writeln( 'Cannot find file ',InFileName); until OK; end;

116 TURBO Pascal Reference Manual I/O checking

When the I directive is passive ({ $I-}). the following standard procedures should be followed by a check of IOresult to ensure proper error han dling:

• Append Close Read Seek Assign Erase ReadLn Write Block Read Execute Rename WriteLn BlockWrite Flush Reset Chain • GetOir Rewrite • ChOir • MkOir • RmOir

* PC-OOS/MS-OOS only.

File Types 117 I/O checking

Notes:

118 TURBO Pascal Reference Manual Chapter 15 POINTER TYPES

Variables discussed up to now have been static, i.e. their form and size is pre-determined, and they exist throughout the entire execution of the block in which they are declared. Programs, however, frequently need the use of a data structure which varies in form and size during execu tion. Dynamic variables serve this purpose as they are generated as the need arises and may be discarded after use.

Such dynamic variables are not declared in an explicit variable declara tion like static variables, and they cannot be referenced directly by identifiers. Instead, a special variable containing the memory address of the variable is used to point to the variable. This special variable is called a .pointer variable.

Defining a Pointer Variable

A pointer type is defined by the pointer symbol A succeeded by the type identifier of the dynamic variables which may be referenced by pointer variables of this type.

The following shows how to declare a record with associated pointers. The type Person Pointer is declared as a pointer to variables of type PersonRecord: type PersonPointer = APersonRecord; PersonRecord = record Name: string[50]; Job: string[50]; Next: PersonPointer; end; var FirstPerson, LastPerson, NewPerson: PersonPointer;

POINTER TYPES 119 Allocating Variables (New)

As shown above, the type identifier in a pointer type definition may refer to an identifier that is not yet defined. However, the identifier must be defined somewhere within the same block of type declarations. In other words the following is illegal: type PersonPointer=APersonRecord; var Dummy : char; type PersonRecord = record

By removing the variable declaration between the two blocks of type declarations the above would be correct. The variables FirstPerson, LastPerson and NewPerson are thus pointer variables which can point to records of type PersonRecord. As shown above, the type identifier in a point type definition may refer to an identifier which is not yet defined (as long as both are in the same type declaration part).

Allocating Variables (New)

Before it makes any sense to use any of these pointer variables we must, of course, have some variables to point at. New variables of any type are allocated with the standard procedure New. The procedure has one parameter which must be a pOinter to variables of the type we want to create.

A new variable of type PersonRecord can thus be created by the state ment: New{FirstPerson);

which has the effect of having FirstPerson point at a dynamically allocat ed record of type PersonRecord.

120 TURBO Pascal Reference Manual Mark and Release

Assignments between pOinter variables can be made as long as both pointers are of identical type. Pointers of identical type may also be compared using the relational operators = and < >, returning a Boolean result (True or False).

The pointer value nil is compatible with all pointer types. nil points to no dynamic variable, and may be assigned to pointer variables to indicate the absence of a usable pointer. nil may also be used in comparisons.

Variables created by the standard procedure New are stored in a stack like structure called the heap. The TURBO Pascal system controls the heap by maintaining a heap pOinter which at the beginning of a program is initialized to the address of the first free byte in memory. On each call to New, the heap pointer is moved towards the top of free memory the number of bytes corresponding to the size of the new dynamic variable.

Mark and Release

When a dynamic variable is no longer required by the program, the stan dard procedures Mark and Release are used to reclaim the memory allo cated to these variables. The Mark procedure assigns the value of the heap pointer to a variable. The syntax of a call to Mark is: Mark(Var) ;

where Var is a pointer variable. The Release procedure sets the heap pointer to the address contained in its argument. The syntax is:

Release (Var) ;

where Var is a pointer variable, previously set by Mark. Release thus discards al/ dynamic variables above this address, and cannot release the space used by variables in the middle of the heap. If you want to do that, you should use Dispose (see page 124 ) instead of Mark/Release.

The standard function MernA vail is available to determine the available space on the heap at any given time. Further discussion is deferred to chapters 20, 21, and 22.

POINTER TYPES 121 Using Pointers

Using Pointers

Supposing we have used the New procedure to create a series of records of type PersonRecord (as in the example on the following page) and that the field Next in each record points at the next PersonRecord created, then the following statements will go through the list and write the contents of each record (FirstPerson pOints to the first person in the list):

while FirstPerson <> nil do with FirstPerson h do begin Writeln(Name,' is a ',Job); FirstPerson := Next; end;

FirstPerson".Name may be read as FirstPerson's.Name, i.e. the field Name in the record pointed to by FirstPerson.

The following program example demonstrates the use of pointers to maintain a list of names and related job descriptions. Names and job desires will be read in until a blank name is entered. Then the entire list is printed. Finally, the memory used by the list is released for other use. The pOinter variable HeapTop is used only for the purpose of recording and

storing the initial value of the heap pointer. Its definition as a A Integer (pointer to integer) is thus totally arbitrary.

122 TURBO Pascal Reference Manual Using Pointers

procedure Jobs; type PersonPointer = APersonRecord; PersonRecord = record Name: string[50]; Job: string[50]; Next: PersonPointer; end; var HeapTop: Alnteger; FirstPerson, LastPerson, NewPerson: PersonPointer; Name: string[50]; begin FirstPerson nil; Mark(HeapTop); repeat Write( 'Enter name: '); Readln(Name); if Name <> " then begin New( NewPerson) ; NewPersonA.Name := Name; Write( 'Enter profession: '); Readln(NewPersonA.Job); Writeln; if FirstPerson = nil then FirstPerson := NewPerson else LastPersonA.Next := NewPerson; LastPerson := NewPerson; A LastPerson • Next: = nil; end; until Name="; Writeln; while FirstPerson <> nil do with FirstPersonA do begin Writeln(Name,' is a ',Job); FirstPerson := Next; end; Release(HeapTop); end.

POINTER TYPES 123 Dispose

Dispose

Instead of Mark and Release, standard Pascal's Dispose procedure may be used to reclaim space on the heap.

NOTICE that Dispose and Mark/Release use entirely different ap proaches to heap management - and never shall the twain meet! Any one program must use either Dispose or Mark/Release to manage the heap. Mixing them will produce unpredictable results.

The syntax is:

Dispose (Var) ;

where Var is a pointer variable.

Dispose allows dynamic memory used by a specific pointer variable to be reclaimed for new use, as opposed to Mark and Release which releases the entire heap from the specified pointer variable and upward.

Suppose you have a number of variables which have been allocated on the heap. The following figure illustrates the contents of the heap and the effect of Dispose(Var3) and Mark(Var3)/ Release(Var3) :

Heap After After Dispose Mark/Release

Varl Varl Varl Var2 Var2 Var2 Var3 Var4 Var4 Var5 Var5 Var6 Var6 HiMem Var7 Var7

Figure 15-1: Using Dispose

124 TURBO Pascal Reference Manual Dispose

After Disposing a pointer variable, the heap may thus consist of a number of memory areas in use interspersed by a number of free areas. Subsequent calls to New will use these if the new pointer variable fits into the space.

GetMem

The standard procedure GetMem is used to allocate space on the heap. Unlike New, which allocates as much space as required by the type pointed to by its argument, GetMem allows the programmer to control the amount of space allocated. GetMem is called with two parameters: GetMem(PVar, I)

where PVar is any pointer variable, and I is an integer expression giving the number of bytes to be allocated.

FreeMem

Syntax: FreeMem;

The FreeMem standard procedure is used to reclaim an entire block of space on the heap. It is thus the counterpart of GetMem. FreeMem is called with two parameters: FreeMem(PVar, I);

where PVar is any pointer variable, and I is an integer expression giving the number of bytes to be reclaimed, which must be exactly the number of bytes previously allocated to that variable by GetMem.

Pointer Types" 125 MaxAvail

MaxAvail

Syntax: MaxAvail;

The MaxA vail standard function returns the size of the largest consecu tive block of free space on the heap. On 16-bit systems this space is in in number of paragraphs (16 bytes each); on a-bit systems it is in bytes. The result is an Integer, and if more than· 32767 paragraphs/bytes are available, MaxAvail returns a negative number. The correct number of free paragraphs/bytes is then calculated as 65536.0 + MaxAvail. Notice the use of a real constant to generate a Real result, as the result is greater than Maxlnt.

Hints

Note that no range checking is done on pointers. It is the responsibility of the programmer to ensure that a pOinter pOints to a legal address.

If you have difficulties using pointers, a drawing of what you are attempting to do often clears up things.

126 TURBO Pascal Reference Manual Chapter 16 PROCEDURES AND FUNCTIONS

A Pascal program consists of one or more blocks, each of which may again consist of blocks, etc. One such block is a procedure, another is a function (in common called subprograms). Thus, a procedure is a separate part of a program, and it is activated from elsewhere in the program by a procedure statement (see page 56). A function is rather similar, but it computes and returns a value when its identifier, or desig nator, is encountered during execution (see page 54).

Parameters

Values may be passed to procedures and functions through parameters. Parameters provide a substitution mechanism which allows the logic of the subprogram to be used with different initial values, thus producing different results.

The procedure statement or function designator which invokes the sub program may contain a list of parameters, called the actual parameters. These are passed to the formal parameters specified in the subprogram heading. The order of parameter passing is the order of appearance in the parameter lists. Pascal supports two different methods of parameter passing: by value and by reference. These two methods determine the effect that changes of the formal parameters have on the actual parameters.

When parameters are passed by value, the formal parameter represents a local variable in the subprogram, and changes of the formal parameters have no effect on the actual parameter. The actual parameter may be any expression, including a variable, with the same type as the corresponding formal parameter. Such parameters are called value parameters and are declared in the subprogram heading as in the following example. This and the following examples show procedure headings; see page 137 for a description of function headings.

procedure Example(Numl,Num2: Number; Strl,Str2: Txt);

PROCEDURES AND FUNCTIONS 127 Parameters

Number and Txt are previously defined types (e.g. Integer and string[255]), and Num1, Num2, Str1, and Str2 are the formal parame ters to which the value of the actual parameters are passed. The types of the formal and the actual parameters must correspond.

Notice that the type of the parameters in the parameter part must be specified as a previously defined type identifier. Thus, the construct:

procedure Select(Model: array[l .. 500] of Integer);

is not allowed. Instead, the desired type should be defined in the type definition of the block, and the type identifier should then be used in the parameter declaration:

type Range ~ array[l .. 500] of Integer;

procedure Select(Model: Range);

When a parameter is passed by reference, the formal parameter in fact represents the actual parameter throughout the execution of the sub program. Any changes made to the formal parameter is thus made to the actual parameter, which must therefore be a variable. Parameters passed by reference are called a variable parameters, and are declared as follows: prooedure Example (var Numl , Num2 : Number)

Value parameters and variable parameters may be mixed in the same procedure as in the following example:

prooedureExample(varNuml,Num2:Number;Strl,Str2:Txt);

in which Num1 and Num2 are variable parameters and Str1 and Str2 are value parameters.

All address calculations are done at the time of the procedure call. Thus, if a variable is a component of an array, its index expression(s) are evaluated when the subprogram is called.

Notice that file parameters must always be declared as variable parame ters.

128 TURBO Pascal Reference Manual Parameters

When a large data structure, such as an array, is to be passed to a sub program as a parameter, the use of a variable parameter will save both time and storage space, as the only information then passed on to the subprogram is the address of the actual parameter. A value parameter would require storage for an extra copy of the entire data structure, and the time involved in copying it.

Relaxations on Parameter Type Checking

Normally, when using variable parameters, the formal and the actual parameters must match exactly. This means that subprograms employ ing variable parameters of type String will accept only strings of the ex act length defined in the subprogram. This restriction may be overridden by the V compiler directive. The default active state { $V + } indicates strict type checking, whereas the passive state { $V-} relaxes the type checking and allows actual parameters of any string length to be passed, irrespective of the length of the formal parameters.

Example: program Encoder; {$V-} type WorkString = string[255]; var Linel: string[80]; Line2: string[lOO]; prooedure Encode (var LineToEncode: WorkString) ; var I: Integer; begin for I := 1 to Length(LineToEncode) do LinetoEncode[I] Chr(Ord(LineToEncode[I])-30); end; begin Linel 'This is a secret message'; Encode(Linel) ; Line2 := 'Here is another (longer) secret message'; Encode(Line2); end.

PROCEDURES AND FUNCTIONS 129 Parameters

Untyped Variable Parameters

If the type of a formal parameter is not defined, i.e. the type definition is omitted from the parameter section of the subprogram heading, then that parameter is said to be untyped. Thus, the corresponding actual parameter may be any type.

The untyped formal parameter itself is incompatible with all types, and may be used only in contexts where the data type is of no significance, for example as a parameter to Addr, BlockReadjWrite, FiIIChar, or Move, or as the address specification of absolute variables.

The SwitchVar procedure in the following example demonstrates the use of untyped parameters. It moves the contents of the variable A 1 to A2 and the contents of A2 to A 1.

prooedure SwitchVar (varAlp,A2p; Size: Integer); type A = array[l .. MaxInt] of Byte; var AI: A absolute Alp; A2: A absolute A2p; Tmp: Byte; Count: Integer; begin for Count := 1 to Size do begin Tmp := Al[Count]; Al[Count] := A2[Count]; A2[Count] := Tmp; end; end;

Assuming the declarations: type Matrix = array[l .. 50,1 .. 25] of Real; var TestMatrix,BestMatrix: Matrix;

then SwitchVar may be used to switch values between the two ma- trices: .

SWitchVar(TestMatrix,BestMatrix, SizeOf(Matrix));

130 TURBO Pascal Reference Manual Procedures

Procedures

A procedure may be either pre-declared (or 'standard') or user-declared, i.e. declared by the programmer. Pre-declared procedures are parts of the TURBO Pascal system and may be called with no further declara tion. A user-declared procedure may be given the name of a standard procedure; but that standard procedure then becomes inaccessible within the scope of the user declared procedure.

Procedure Dec/aration

A procedure declaration consists of a procedure heading followed by a block which consists of a declaration part and a statement part.

The procedure heading consists of the reserved word procedure fol lowed by an identifier which becomes the name of the procedure, op tionally followed by a formal parameter list as described on page 127 .

Examples: procedure LogOn; procedure Position(X,Y: Integer); prooedure Compute (var Data: Matrix; Scale: Real) ;

The declaration part of a procedure has the same form as that of a pro gram. All identifiers declared in the formal parameter list and the declara tion part are local to that procedure, and to any procedures within it. This is called the scope of an identifier, outside which they are not known. A procedure may reference any constant, type, variable, pro cedure, or function defined in an outer block.

The statement part specifies the action to be executed when the procedure is invoked, and it takes the form of a compound statement (see page 57). If the procedure indentifier is used within the statement part of the procedure itself, the procedure will execute recursively. (CP/M-SO only: Notice that the A compiler directive must be passive {$A-} when recursion is used; see Appendix C.)

The next example shows a program which uses a procedure and passes a parameter to this procedure. As the actual parameter passed to the procedure is in some instances a constant (a simple expression), the formal parameter must be a value parameter.

PROCEDURES AND FUNCTIONS 131 Procedures

program Box; var I: Integer; procedure DrawBox(XI,YI,X2,Y2: Integer); var I: Integer; begin GotoXY( Xl, YI) ; tor I : = Xl to X2 do wri te ( '-' ) ; for I := YI+I to Y2 do begin GotoXY(XI,I); Write('! '); GotoXY(X2,I); Write('! '); end; GotoXY(XI,Y2); for I :- Xl to X2 do Write('-'); end; { of procedure DrawBox } begin ClrScr; for I := I to 5 do DrawBox(I*4,I*2,IO*I,4*I); DrawBox(I,I,80,23); end.

Often the changes made to the formal parameters in the procedure should also affect the actual parameters. In such cases variable parame ters are used, as in the following example:

prooedure Swi tch (var A,B: Integer); Var Tmp: Integer; begin Tmp := A; A := B; B := Tmp; end;

When this procedure is called by the statement:

Switch(I,J);

the values of I and J will be switched. If the procedure heading in Switch was declared as:

procedure Switch(A,B: Integer);

i.e. with a value parameter, then the statement Switch (I, J) would not change I and J.

132 TURBO Pascal Reference Manual Procedures

Standard Procedures

TURBO Pascal contains a number of standard procedures. These are:

1) .string handling procedures (described on pages 71 pp), 2) file handling procedures (described on pages 94, 101, and 114). 3) procedures for allocation of dynamic variables (described on pages 120 and 125 ), and 4) input and output procedures (described on pages 108 pp).

In addition to these, the following standard procedures are available, provided that the associated commands have been installed for your ter minal (see pages 12 pp):

C/rEo/

Syntax: ClrEol;

Clears all characters from the cursor position to the end of the line without moving the cursor.

C/rScr

Syntax: ClrScr;

Clears the screen and places the cursor in the upper left-hand corner. Be aware that some screens also reset the video-attributes when clearing the screen, possibly disturbing any user-set attributes.

Crt/nit

Syntax: Crtlnit;

Sends the Terminal Initialization String defined in the installation pro cedure to the screen.

PROCEDURES AND FUNCTIONS 133 Procedures

CrtExit

Syntax: CrtExit;

Sends the Terminal Reset String defined in the installation procedure to the screen.

De/ay

Syntax: Delay( Time);

The Delay procedure creates a loop which runs for approx. as many mil liseconds as defined by its argument Time which must be an integer. The exact time may vary somewhat in different operating environments.

De/Line

Syntax: DelUne;

Deletes the line containing the cursor and moves all lines below one line up.

InsLine

Syntax: InsUne;

Inserts an empty line at the cursor position. All lines below are moved one line down and the bottom line scrolls off the screen.

GatoXY

Syntax: GotoXY(Xpos, Ypos);

Moves the cursor to the position on the screen specified by the integer expressions Xpos (horizontal value, or column) and Ypos (vertical value, or row). The upper left comer (home position) is (1,1).

134 TURBO Pascal Reference Manual Procedures

Exit

Syntax: Exit;

Exits the current block. When exit is executed in a subroutine, it causes the subroutine to return. When it is executed in the statement part of a program, it causes the program to terminate. A call to Exit may be com pared to a goto statement addressing a label just before the end of a block.

Halt

Syntax: Halt;

Stops program execution and returns to the operating system.

In PC/MS-DOS, Halt may optionally pass a integer parameter specifying the return code of the program. Halt without a parameter corresponds to Halt(O). The return code may be examined by the parent process us ing an MS-DOS system function call or through an ERRORLEVEL test in an MS-DOS batch file.

LowVideo

Syntax: LowVideo;

Sets the screen to the video attribute defined as 'Start of Low Video' in the installation procedure, i.e. 'dim' characters.

Norm Video

Syntax: NormVideo;

Sets the screen to the video attribute defined as 'Start of Normal Video' in the installation procedure, i.e. the 'normal' screen mode.

Randomize

Syntax: Randomize;

Initializes the random number generator with a random value.

PROCEDURES AND FUNCTIONS 135 Procedures

Move

Syntax: Move(var1, var2,Num);

Does a mass copy directly in memory of a specified number of bytes. var1 and var2 are two variables of any type, and Num is an integer ex pression. The procedure copies a block of Num bytes, starting at the first byte occupied by var1 to the block starting at the first byte occu pied by var2. You may notice the absence of explicit 'moveright' and 'moveleft' procedures. This is because Move automatically handles pos sible overlap during the move process.

Fi//Char

Syntax: FillChar( Var, Num, Value);

Fills a range of memory with a given value. Var is a variable of any type, Num is an integer expression, and Value is an expression of type Byte or Char. Num bytes, starting at the first byte occupied by Var, are filled with the value Value.

136 TURBO Pascal Reference Manual Functions

Functions

Like procedures, functions are either standard (pre-declared) or declared by the programmer.

Function Declaration

A function declaration consists of a function heading and a block which is a declaration part followed by a statement part.

The function heading is equivalent to the procedure heading, except that the heading must define the type of the function result. This is done by adding a colon and a type to the heading as shown here: function KeyHit: Boolean; funotion Compute (var Value: Sample) : Real; function Power(X,Y: Real): Real;

The result type of a function must be a scalar type (Le. Integer, Real, Boolean, Char, declared scalar or subrange), a string type, or a pointer type.

The declaration part of a function is the same as that of a procedure.

The statement part of a function is a compound statement as described on page 57 . Within the statement part at least one statement assigning a value to the function identifier must occur. The last assignment exe cuted determines the result of the function. If the function designator appears in the statement part of the function itself, the function will be invoked recursively. (CP/M-SO only: Notice that the A compiler directive must be passive { $A-} when recursion is used, see Appendix C.)

PROCEDURES AND FUNCTIONS 137 Functions

The following example shows the use of a function to compute the sum of a row of integers from I to J.

function RowSum(I,J: Integer): Integer; function SimpleRowSum(S: Integer): Integer; begin SimpleRowSum := S*(S+l) div 2; end; begin RowSum := SimpleRowSum(J)-SimpleRowSum(I-l); end;

The function SimpleRowSum is nested within the function RowSum. SimpleRowSum is therefore only available within the scope of RowSum.

The following program is the classical demonstration of the use of a re cursive function to calculate the factorial of an integer number:

{$A-} {A- directive allows recursion in CP/M-80 version} program Factorial; var Number: Integer; function Factorial(Value: Integer): Real; begin if Value = 0 then Factorial := 1 else Factorial := Value * Factorial(Value-l); end; begin Read( Number) ; Writeln(AM,Number,'! = ',Factorial(Number)); end.

Note that the type used in the definition of a function type must be pre viously specified as a type identifier. Thus, the construct:

function LowCase(Line: UserLine): string[80);

is not allowed. Instead, a type identifier should be associated with the type string[BOj, and that type identifier should then be used to define the function result type, for example:

type Str80 = string[80];

function LowCase(Line: UserLine): Str80;

138 TURBO Pascal Reference Manual Functions

Because of the implementation of the standard procedures Write and Writeln, a function using any of the standard procedures Read, Readln, Write, or Writeln, must never be called by an expression within a Write or Writeln statement. In a-bit systems this is also true for the standard procedures Str and Val.

Standard Functions

The following standard (pre-declared) functions are implemented in TURBO Pascal:

1) string handling functions (described on pages 71 pp), 2) file handling functions (described on pages 94 and 101), 3) pointer related functions (described on pages 120 and 125).

Arithmetic Functions

Abs

Syntax: Abs(Num);

Returns the absolute value of Num. The argument Num must be either Real or Integer, and the result is of the same type as the argument.

ArcTan

Syntax: ArcTan(Num);

Returns the angle, in radians, whose tangent is Num. The argument X must be either Real or Integer, and the result is Real.

Cos

Syntax: Cos(Num);

Returns the cosine of Num. The argument Num is expressed in radians, and its type must be either Real or Integer. The result is of type Real.

PROCEDURES AND FUNCTIONS 139 Functions

Exp

Syntax: Exp(Num);

Returns the exponential of Num, i.e. enum. The argument Num must be either Real or Integer, and the result is Real.

Frac

Syntax: Frac(Num);

Returns the fractional part 01 Num, i.e. Frac(Num) = Num - Int(Num). The argument Num must be either Real or Integer, and the result is Real.

Int

Syntax: Int(Num);

Returns the integer part of Num, i.e. the greatest integer number less than or equal to Num, if Num > = 0, or the smallest integer number greater than or equal to Num, if Num < O. The argument Num must be either Real or Integer, and the result is Real.

Syntax: Ln(Num);

Returns the natural logarithm of Num. The argument Num must be ei ther Real or Integer, and the result is Real.

Sin

Syntax: Sin(Num);

Returns the sine of Num. The argument Num is expressed in radians, and its type must be either Real or Integer. The result is of type Real.

140 TURBO Pascal Reference Manual Functions

Sqr

Syntax: Sqr(Num};

Returns the square of Num, i.e. Num It Num. The argument Num must be either Real or Integer, and the result is of the same type as the argu ment.

Sqrt

Syntax: Sqrt(Num};

Returns the square root of Num. The argument Num must be either Real or Integer, and the result is Real.

Scalar Functions

Pred

Syntax: Pred(Num};

Returns the predecessor of Num (if it exists). Num is of any scalar type.

Succ

Syntax: Succ(Num};

Returns the successor of Num (if it exists). Num is of any scalar type.

Odd

Syntax: Odd(Num};

Returns boolean True if Num is an odd number, and False if Num is even. Num must be of type Integer.

PROCEDURES AND FUNCTIONS 141 Functions

Transfer Functions

The transfer functions are used to convert values of one scalar type to that of another scalar type. In addition to the following functions, the re type facility described on page 65 serves this purpose.

Chr

Syntax: Chr(Num);

Returns the character with the ordinal value given by the integer expres sion Num. Example: Chr(65) returns the character 'A'.

Ord

Syntax: Ord( Vat);

Returns the ordinal number of the value Var in the set defined by the type Var. Ord(Var) is equivalent to Integer(Var) (see Type Conversions on page 65. Var may be of any scalar type, except Real, and the result is of type Integer.

Round

Syntax: Round(Num);

Returns the value of Num rounded to the nearest integer as follows: if Num > = 0, then Round(Num) = Trunc(Num + 0.5), and if Num < 0, then Round(Num) = Trunc(Num - 0.5). Num must be of type Real, and the result is of type Integer.

Trunc

Syntax: Trunc(Num);

Returns the greatest integer less than or equal to Num, if Num > = 0, or the smallest integer greater than or equal to Num, if Num < 0. Num must be of type Real, and the result is of type Integer.

142 TURBO Pascal Reference Manual Functions

Miscellaneous Standard Functions

Syntax: Hi(/);

The low order byte of the result contains the high order byte of the value of the integer expression I. The high order byte of the result is zero. The type of the result is Integer.

KeyPressed

Syntax: KeyPressed

Returns boolean True if a key has been pressed at the console, and False if no key has been pressed. The result is obtained by calling the operating system console status routine. When using KeyPressed, both the C and U compiler directives should be turned off {$C-,U-} (at the top of your program) or your program may "miss" keystrokes. For more information on compiler directives, refer to Appendix C.

The predefined global variable CBREAK is a boolean flag that represents the current value ofthe C compiler directive. By assigning this variable a boolean value within your programs, you can control the user's ability to use CTRL-C and CTRL-S during screen lID. This can be used in conjunction with the C compiler to easily control the program during runtime.

Syntax: Lo(/);

Returns the low order byte of the value of the integer expression I with the high order byte forced to zero. The type of the result is Integer.

Random

Syntax: Random;

Returns a random number greater than or equal to zero and less than one. The type is Real. This function should not be passed a parameter less than 1 because it will return a run-time error if anything less than 1 is passed to it.

PROCEDURES AND FUNCTIONS 143 Functions

Random(Num)

Syntax: Random(Num);

Returns a random number greater than or equal to zero and less than Num. Num and the random number are both Integers.

ParamCount

Syntax: ParamCount;

This integer function returns the number of parameters passed to the program in the command line buffer. Space and tab characters serve as separators.

ParamStr

Syntax: ParamStr(l\I);

This string function returns the Nth parameter from the command line buffer.

SizeOf

Syntax: SizeOf(Name);

Returns the number of bytes occupied in memory by the variable or type Name. The result is of type Integer.

Swap

Syntax: Swap(Num);

The Swap function exchanges the high and low order bytes of its in teger argument Num and returns the resulting value as an integer.

Example: Swap($1234) returns $3412 (values in hex for clarity).

144 TURBO Pascal Reference Manual Forward References

UpCase

Syntax: UpCase(ch);

Returns the uppercase equivalent of its argument ch which must be of type Char. If no uppercase equivalent exists, the argument is returned unchanged.

Forward References

A subprogram is forward declared by specifying its heading separately from the block. This separate subprogram heading is exactly the same as the normal heading, except that it is terminated by the reserved word forward. The block follows later within the same declaration part. Notice that the block is initiated by a copy of the heading, specifying only the name and no parameters, types, etc.

Example: program Catch22; var X: Integer; function Up(Var I: Integer): Integer; forward; function Down(Var I: Integer): Integer; begin I := I div 2; Writeln(I); if I <> 1 then I := Up(I); end; function Up; begin while I mod 2 <> 0 do begin I := 1*3+1; Write1n(I); end; I := Down(I); end; begin Write( 'Enter any integer: '); Read1n(X) ; X : = Up(X); Write( 'Ok. Program stopped again.'); end.

When the program is executed and you enter, for example, a 6, it outputs:

Procedures and Functions" 145 Forward References

3 10 5 16 8 4 2 1 Ok. Program stopped again.

The above program is actually a more complicated version of the follow ing program:

program Catch222; Var X: Integer; begin Write( 'Enter any integer: '); Readln(X) ; while X <> 1 do begin if X mod 2 0 then X := X div 2 else X := X*3+1; Wri teln(X); end; Write( 'Ok. Program stopped again.'); end.

It may interest you to know that it cannot be proved if this small and very simple program actually will stop for any integer!

146 TURBO Pascal Reference Manual Chapter 17 INCLUDING FILES

The fact that the TURBO editor performs editing only within memory lim its the size of source code handled by the editor. The I compiler direc tive can be used to circumvent this restriction, as it provides the ability to split the source code into smaller 'lumps' and put it back together at compile-time. The include facility also aids program clarity, as commonly used subprograms, once tested and debugged, may be kept as.a 'li brary' of files from which the necessary files can be included in any oth er program.

The syntax for the I compiler directive is:

{$I filename}

where filename is any legal file name. Leading spaces are ignored and lower case letters are translated to upper case. If no file type is specified, the default type .PAS is assumed. This directive must be specified on a line by itself.

Examples: {$Ifirst. pas} {$I COMPUTE. MOD} {$iStdProc }

Notice that a space must be left between the file name and the closing brace if the file does not have a three-letter extension; otherwise the brace will be taken as part of the name.

To demonstrate the use of the include facility, let us assume that in your 'library' of commonly used procedures and functions you have a file called STUPCASE.FUN. It contains the function StUpCase which is called with a character or a string as parameter and returns the value of this parameter with any lower case letters set to upper case.

INCLUDING FILES 147 INCLUDING FILES

File STUPCASE.FUN: function StUpCase(St: AnyString): AnyString; Var I: Integer; begin for I := 1 to Length(St) do St [I] : = UpCase (St [I] ) ; StUpCase := St end;

In any future program you write which requires this function to convert strings to upper case letters, you need only include the file at compile time instead of duplicating it into the source code: program Include Demo; type InData= string[80]; AnyString= string[255]; Var Answer: InData; {$I STUPCASE.FUN} begin Re adLn ( Answe r ) ; Writeln(StUpCase(Answer)); end.

This method not only is easier and saves space; it also makes program updating quicker and safer, as any change to a 'library' routine will au tomatically affect all programs including this routine.

Notice that TURBO Pascal allows free ordering, and even multiple oc currences, of the individual sections of the declaration part. You may thus e.g. have a number of files containing various commonly used type definitions in your 'library' and include the ones required by different pro grams.

A!! compHer directives except Band C are local to the file in which they appear, i.e. if a compiler directive is set to a different value in an included file, it is reset to its original value upon return to the including file. Band C directives are always global. Compiler directives are described in Appendix C.

Include files cannot be nested, i.e. one include file cannot include yet another file and then continue processing.

148 TURBO Pascal Reference Manual Chapter 18 OVERLAY SYSTEM

The overlay system lets you create programs much larger than can be accommodated by the computer's memory. The technique is to collect a number of subprograms (procedures and functions) in one or more files separate from the main program file, which will then be loaded automati cally one at a time into the same area in memory.

The following drawing shows a program using one overlay file with five overlay subprograms collected into one overlay group, thus sharing the same memory space in the main program:

Main program Overlay file

Main program code Overlay procedure 1

Overlay area Overlay procedure 2

Overlay procedure 3

Overlay procedure 4 Main program code Overlay procedure 5

Figure 18-1 Principle of Overlay System

a VERLA Y SYSTEM 149 OVERLA Y SYSTEM

When an overlay procedure is called, it is automatically loaded into the overlay area reserved in the main program. This 'gap' is large enough to accommodate the largest of the overlays in the group. The space re quired by the main program is thus reduced by roughly the sum of all subprograms in the group less the largest of them.

In the example above, overlay procedure 2 is the largest of the five pro cedures and thus determines the size of the overlay area in the main code. When it is loaded into memory, it occupies the entire overlay area:

Main program Overlay file

Main program code Overlay procedure 1

Overlay procedure 3

Overlay procedure 4 Main program code Overlay procedure 5

Figure 18-2: Largest Overlay Subprogram Loaded

150 TURBO Pascal Reference Manual a VERLA Y SYSTEM

The smaller subprograms are loaded into the same area of memory, each starting at the first address of the overlay area. Obviously they oc cupy only part of the overlay area; the remainder is unused:

Main program Overlay file

Main program code Overlay procedure 1

Overlay procedure 2

Overlay procedure 4 Main program code Overlay procedure 5

Figure 18-3: Smaller Overlay Subprogram Loaded

As procedures 1, 3, 4, and 5 execute in the same space as used by pro cedure 2, it is clear that they require no additional space in the main pro gram. It is also clear that none of these procedures must ever call each other, as they are never present in memory simultaneously.

There could be many more overlay procedures in this group of overlays; in fact the total size of the overlay procedures could substantially exceed the size of the main program. And they would still require only the space occupied by the largest of them.

The tradeoff for this extra room for program code is the addition of disk access time each time a procedure is read in from the disk. With good planning, as discussed on page 155, this time is negligible.

a VERLA Y SYSTEM 151 Creating Overlays

Creating Overlays

Overlay subprograms are created automatically, simply by adding the reserved word overlay to the declaration of any procedure or function: overlay procedure Initialize; and overlay function TimeOfDay: Time;

When the compiler meets such a declaration, code is no longer output to the main program file, but to a separate overlay file. The name of this file will be the same as that of the main program, and the type will be a number designating the overlay group, ranging from 000 through 099.

Consecutive overlay subprograms will be grouped together. I.e. as long as overlay subprograms are not separated by any other declaration, they belong to the same group and are placed in the same overlay file.

Example 1: overlay procedure One; begin end; overlay procedure Two; begin end;

overlay procedure Three; begin end;

These three overlay procedures will be grouped together and placed in the same overlay file. If they are the first group of overlay subprograms in a program, the overlay file will be no. 000.

The three overlay procedures in the following example will be placed in consecutive overlay files, .000 and .001, because of the declaration of a non-overlay procedure Count separating overlay procedures Two and Three.

152 TURBO Pascal Reference Manual Creating Overlays

The separating declaration may be any declaration, for example a dum my type declaration, if you want to force a separation of overlay areas.

Example 2: overlay procedure One; begin

end;

overlay procedure Two; begin

end;

procedure Count; begin

end

overlay procedure Three; begin

end;

A separate overlay area is reserved in the main program code for each overlay group, and the following files will be created:

Main program Overlay files

file. 000 Main program code overlay procedure One Overlay area a < overlay procedure Two procedure Count file. 001

Overlay area 1 overlay procedure Three

Main program code

Figure 18-4: Multiple Overlay Files

OVERLA Y SYSTEM 153 Nested Overlays

Nested Overlays

Overlay subprograms may be nested, i.e. an overlay subprogram may it self contain overlay subprograms which may contain overlay subpro grams, etc.

Example 3: program OverlayDemo;

overlay procedure One; begin

end;

overlay procedure Two; overlay procedure Three; begin

end; begin

end;

In this example, two overlay files will be created. File .000 contains over lay procedures One and Two, and an overlay area is reserved in the main program to accommodate the largest of these. Overlay file .001 contains overlay procedure Three which is local to overlay procedure TwO, and an overlay area is created in the code of overlay procedure Two:

Main program Overlay files Overlay files

Main program code file.OOO

overlay procedure One

Overlay area / overlay procedure Two file.OOl ------Hoverlay procedure \ Overlay area Three Main program code ------Procedure code

Figure 18-5: Nested Overlay Files

154 TURBO Pascal Reference Manual Automatic Overlay Management

Automatic Overlay Management

An overlay subprogram is loaded into memory only when called. On each call to an overlay subprogram, a check is first made to see if that subprogram is already present in the overlay area. If not, it will automati cally be read in from the appropriate overlay file.

Placing Overlay Files

During compilation, overlay files will be placed on the logged drive, i.e. on the same drive as the main program file (.COM or .CMD file).

During execution, the system normally expects to find its overlay files on the logged drive. This may be changed as described on pages 196 (PC/MS-DOS), 233 (CP/M-86), and 265 (CP/M-80).

Efficient Use of Overlays

The overlay technique, of course, adds overhead to a program by ad ding some extra code to manage the overlays, and by requiring disk accesses during execution. Overlays, therefore, should be carefully planned.

In order not to slow down execution excessively, an overlay subprogram should not be called too often, or - if one is called often - it should at least be called without intervening calls to other subprograms in the same overlay file in order to keep disk accesses at a minimum. The ad ded time will of course vary greatly, depending on the actual disk configuration. A 5 1/4" floppy will add much to the run-time, a hard disk much less, and a RAM-disk will add very little time.

To save as much space as possible in the main program, one group of overlays should contain as many individual subprograms as possible. From a pure space-saving point of view, the more subprograms you can put into a single overlay file, the better. The overlay space used in the main program needs only to accommodate the largest of these subprograms the rest of the subprograms have a free ride in the same area of memory. This fact must be weighed against the time considerations discussed above.

a VERLA Y SYSTEM 155 Restrictions Imposed on Overlays

Restrictions Imposed on Overlays

Data Area

Overlay subprograms in the same group share the same area in memory and thus cannot be present simultaneously. They must therefore not call each other. Consequently, they may share the same data area which further adds to the space saved when using overlays (CP/M-SO version only).

In example 1 on page 152, none of the procedures may therefore call each other. In example 2, however, overlay procedures One and Two may call overlay procedure Three, and overlay procedure Three may call each of the other two, because they are in separate files and conse quently in separate overlay areas in the main program.

Forward Declarations

Overlay subprograms may not be forward declared. This restriction is easily circumvented, however, by forward declaring an ordinary subpro gram which then in turn calls the overlay subprogram.

Recursion

Overlay subprograms cannot be recursive. Also this restriction may be circumvented by declaring an ordinary recursive subprogram which then in turn calls the overlay subprogram.

Externals

Overlay subprograms may not be external procedures or functions.

Run-Time Errors

Run-time errors occurring in overlays are found as usual, and an ad dress is issued by the error handling system. This address, however, is an address within the overlay area, and there is no way of knowing which overlay subprogram was actually active when the error occurred.

156' TURBO Pascal Reference Manual Restrictions Imposed on Overlays

Run-time errors in overlays, therefore, cannot always be readily found with the Options menu's 'Find run-time error' facility. What 'Find run time error' will point out is the first occurrence of code at the specified address. This, of course, may be the place of the error, but the error may as well occur in a subsequent subprogram within the same overlay group.

This it not a serious limitation, however, as the type of error and the way it occurs generally indicates in which subprogram the error happened. The way to locate the error precisely is to place the suspected subprogram as the first subprogram ofthe overlay group. "Find run-time error" will then work.

The best thing to do is not to place subprograms in overlays until they have been fully debugged!

o VERLA Y SYSTEM 157 Restrictions Imposed on Overlays

Notes:

158 TURBO Pascal Reference Manual Chapter 19 IBM PC GOODIES

This chapter applies to the IBM PC-versions only, and the functions described can be expected to work on IBM PC and compatibles onlyl If you have problems on a compatible, it's not as compatible as you thought.

Screen Mode Control TURBO provides a number of procedures to control the PC's various screen modes.

Windows The window routines let you declare a smaller part of the screen to be your actual work area, protecting the rest of the screen from being overwritten.

Basic graphics These built-in graphics routines let you plot points and draw lines in different colors.

Extended graphics A set of external graphics routines allow for more advanced graphics. One simple statement includes these routines in your programs.

Turtlegraphics The same external machine language file also provides you with turtle graphics routines.

Sound Standard procedures are provided which let you use the PC's sound capabilities in an easy way.

Keyboard A number of the special keys of the IBM keyboard are installed as pri mary commands for the editor. These commands are listed on page 186, and you may add more if you wish. The secondary WordS tar com mands are still available.

IBM PC GOODIES 159 Screen Mode Control

Screen Mode Control

The IBM PC gives you a choice of screen modes, each with its own characteristics. Some display characters, some display graphics, and they all have different capabilities of showing colors. TURBO Pascal sup ports all these screen formats and provides an easy way of using them.

The following screen modes are available:

TextMode 25 lines of 40 or 80 characters GraphColorMode 320x200 dots color graphics GraphMode 320x200 dots black & white graphics (color on an RGB monitor) HiRes 640x200 dots black + one color graphics

Text Modes

In text mode, the PC will display 25 lines of either 40 or 80 characters. The procedure to invoke this mode is named TextMode and is called as follows:

TextMode; TextMode(BW40); BW40 is an integer constant with the value 0 TextMode(BW80); BW80 is an integer constant with the value 2 TextMode(C40); C40 is an integer constant with the value 1 TextMode(C80); C80 is an integer constant with the value 3

The first example with no parameters invokes the text mode which was active last, or the one that is currently active. The next two examples activate black and white text modes with 40 and 80 characters on each line. The final two examples activate color text modes with 40 and 80 characters on each line. Calling TextMode will clear the screen.

TextMode should be called before exiting a graphics program in order to return the system to text mode.

160 TURBO Pascal Reference Manual Screen Mode Control

C%r Modes

In the color text modes, each character may be chosen to be one of 16 colors, and the background may be one of 8 colors. The colors are re ferred to by the numbers 0 through 15. To make things easier, TURBO Pascal includes 16 pre-defined integer constants which may be used to identify colors by names:

Dark colors Light colors 0: Black 8: DarkGray 1: Blue 9: LightBlue 2: Green 10: LightGreen 3: Cyan 11: LightCyan 4: Red 12: LightRed 5: Magenta 13: LightMagenta 6: Brown 14: Yellow 7: LightGray 15: White

Table 19-1: Text Mode Color Scale

Characters and background may be any of these colors. Notice that some monitors do not recognize the intensity signal used to create the eight light colors. On such monitors, the light colors will be displayed as their dark equivalents.

TextColor

Syntax: TextColor(Color);

This procedure selects color of the characters. Color is an integer ex pression in the range 0 through 15, selecting character colors from the table given above.

Examples: TextColor( 1); selects blue characters TextColor(Yellow); selects yellow characters

The characters may be made to blink by adding 16 to the color number. There is a pre-defined constant Blink for this purpose:

TextColor(Red + Blink); selects red, blinking characters

IBM PC GOODIES 161 Screen Mode Control

TextBackground

Syntax: TextBackground( Color);

This procedure selects color of the background, that is, the cell immedi ately surrounding each character; the entire screen consists of 40 or 80 by 25 such cells. Color is an integer expression in the range 0 through 7, selecting character colors from the table given above.

Examples: TextBackground(4); selects red background TextBackground(Magenta); selects magenta background

Cursor Position

In text mode, two functions will tell you where the cursor is positioned on the screen:

WhereX

Syntax: WhereX;

This integer function returns the X-coordinate of the current cursor posi tion.

WhereY

Syntax: WhereY;

This integer function returns the Y-coordinate of the current cursor posi tion.

162 TURBO Pascal Reference Manual Screen Mode Control

Graphics Modes

With a standard IBM graphics video board, or one that is compatible, TURBO will do graphics. Three modes are supported:

GraphColorMode 320x200 dots color graphics GraphMode 320x200 dots black & white graphics HiRes 640x200 dots black + one color graphics

The upper, left corner of the screen is coordinate 0,0. X coordinates stretch to the right, V coordinates downward. All drawing is "clipped," that is, anything displayed outside the screen will be ignored (except when the turtlegraphics' Wrap is in effect).

Activating one of the graphics modes will clear the screen. The stan dard procedure ClrScr works only in text mode, so the way to clear a graphics screen is to activate a graphics mode, possibly the one that's already active. With extended graphics and turtlegraphics, however, there is a ClearScreen procedure which clears the active window.

Graphics can be mixed with text. In 320 x 200 modes, the screen can display 40 x 25 characters and in 640 x 200 mode, it can display 80 x 25 characters.

The TextMode procedure should be called before exiting a graphics pro gram in order to return the system to text mode, see page 160).

GraphC%rMode

Syntax: GraphColorMode;

This standard procedure activates the 320x200 dots color graphics screen giving you X-coordinates between 0 and 319 and V-coordinates between 0 and 199. Drawings may use colors selected from the palette described on page 165.

IBM PC GOODIES 163 Screen Mode Control

GraphMode

Syntax: GraphMode;

This standard procedure activates the 320x200 dots black and white graphics screen giving you X-coordinates between 0 and 319 and Y coordinates between 0 and 199. On a RGB monitor like the IBM Color/Graphics Display, however, even this mode displays colors from a limited palette as shown on page 166.

HiRes

Syntax: HiRes;

This standard procedure activates the 640x200 dots high resolution graphics screen giving you X-coordinates between 0 and 639 and Y coordinates between 0 and 199. In high resolutions graphics, the back ground (screen) is always black, and you draw in one color set by the HiRes Color standard procedure.

HiResColor

Syntax: HiResColor( Colot};

This standard procedure selects the color used for drawing in high reso lution graphics. Color is an integer expression in the range 0 through 15. The background (screen) is always black. Changing HiRes Color causes anything already on the screen to change to the new color.

Examples: HiResColor (7) ; selects light gray HiResColor(Blue); selects blue

The new color may be chosen from the following 16 colors:

164 TURBO Pascal Reference Manual Screen Mode Control

Dark colors Light colors

0: Black 8: DarkGray 1: Blue 9: LightBlue 2: Green 10: LightGreen 3: Cyan 11: LightCyan 4: Red 12: LightRed 5: Magenta 13: LightMagenta 6: Brown 14: Yellow 7: LightGray 15: White

Table 19-2: High Resolution Graphics Color Scale

Some monitors do not recognize the intensity signal used to create the eight light colors. On such monitors, the light colors will be dis-played as their dark equivalents.

Palette

Syntax: Palette(N);

This procedure activates the color palette indicated by the integer expres sion N, which is a parameter that specifies the number of the palette. Four color palettes exist, each containing three colors (1-3) and a fourth color (0) which is always equal to the background color (see later):

Color number: 0 2 3

Palette 0 Background Green Red Brown Palette 1 Background Cyan Magenta LightGray Palette 2 Background LightGreen LightRed Yellow Palette 3 Background LightCyan LightMagenta White

Table 19-3: Color Palettes in Color Graphics

IBM PC GOODIES" 165 Screen Mode Control

The graphics routines will use colors from this palette. They are called with a parameter in the range 0 through 3, and the color actually used is selected from the active palette:

Plot(X,Y,2) will plot a red point when palette 0 is active. Plot(X,Y,3) will plot a yellow point when palette 2 is active. Plot(X,Y,O) will plot a pOint in the active background color, in effect erasing that point.

Once a drawing is on the screen, a change of palette will cause all colors on the screen to change to the colors of the new palette. Only three colors plus the color of the background may thus be displayed simultaneously.

The GraphMode supposedly displays only black and white graphics, but on an AGB monitor, like the IBM Color/Graphics Display, even this mode displays the following limited palette:

Color number: o 2 3

Palette 0 Background Blue Red LightGray Palette 1 Background LightBlue LightRed White

Table 19-4: Color Palettes in B/W Graphics

GraphBackground

Syntax: GraphBackground( Color);

This standard procedure sets. the the background color, that is the en tire screen, to any of 16 colors. Color is an integer expression in the range 0 through 1

GraphBackground(O); sets the screen to black GraphBackground(ll); sets the screen to light cyan

The following color numbers and pre-defined constants are available:

166 TURBO Pascal Reference Manual Screen Mode Control

Dark colors Light colors

0: Black 8: DarkGray 1: Blue 9: LightBlue 2: Green 10: LightGreen 3: Cyan 11: LightCyan 4: Red 12: LightRed 5: Magenta 13: LightMagenta 6: Brown 14: Yellow 7: LightGray 15: White

Table 19-5: Graphics Background Color Scale

Some monitors do not recognize the intensity signal used to create the eight light colors. On such monitors, the light colors will be displayed as their dark equivalents.

IBM PC GOODIES 167 Windows

Windows

TURBO Pascal lets you declare windows anywhere on the screen. When you write in such a window, the window behaves exactly as if you were using the entire screen, leaving the rest of the screen untouched.

Text Windows

The Window procedure allows you to define any area on the screen as the active window in text mode:

Window(Xl,Yl,X2,Y2);

where X1 and Y1 are the absolute coordinates ofthe upper left corner ofthe window, and X2 and Y2 are the absolute coordinates of the lower right corner. The minimum size of the text window is 1 column by 1 line.

The default window is 1,1,80,25 in aD-column modes and 1,1,40,25 in 40-column modes, that is, the entire screen.

All screen coordinates (except the window coordinates themselves) are relative to the active window. This means that after the statement:

Window(20,8,60,17);

which defines the center portion of the physical screen to be your active window, screen coordinates 1,1 (upper left corner) are now the upper left corner of the window, not of the physical screen:

168 TURBO Pascal Reference Manual Windows

Figure 19-1: Text Windows

The screen outside the window is simply not accessible, and the window behaves as it were the entire screen. You may insert, delete, and scroll lines, and lines will wrap around if too long.

Graphics Windows

The GraphWindow procedure allows you to define an area of the screen as the active window in any of the graphics modes:

GraphWindow(Xl,Yl,X2,Y2);

where X1 and Y1 are the absolute coordinates ofthe upper left corner of the window, and X2 and Y2 are the absolute coordinates of the lower right corner.

The default graphics window is 0,0,319,199 in 320x200-dot modes and 0,0,639,199 in 640x200-dot mode, that is, the entire screen.

ALL screen coordinates are relative to the active window-not to the physical screen. For example, after:

GraphWindow(50,lOO,200,lBO);

coordinate 0,0 is in the upper left corner of the window.

Windows cause graphics to be 'clipped', that is, if you for example Draw between two coordinates outside the window, only the part of the line that falls within the window will be shown:

IBM PC GOODIES 169 Windows

Figure 19-2: Graphics Windows

170 TURBO Pascal Reference Manual Basic Graphics

Basic Graphics

In each of the graphics modes, TURBO Pascal provides standard pro cedures which will plot points at specified coordinates and draw lines between two coordinates:

Plot

Syntax: Plot(X, Y, Color);

Plots a point at the screen coordinates specified by X and Y in the color specified by Color. X, Y, and Color are integer expressions. Draw

Syntax: Draw(X1 ,Y1 ,X2,Y2,Color);

Draws a line between the screen coordinates specified by X1, Y1 and X2, Y2 in the color specified by Color. All parameters are integer expres sions.

IBM PC GOODIES 171 Extended Graphics

Extended Graphics

TURBO Pascal comes with a set of external machine language routines that can be included in TURBO programs during compilation. They pro vide extended graphics commands as described in the following.

The external graphics routines are contained in the file GRAPH.BIN. The file GRAPH.P contains the necessary external declarations, and the ex tended graphics routines are included in a TURBO program simply by using this statement to include the GRAPH.P file in the program:

{$I GRAPH. P }

C%rTab/e

Syntax: ColorTable(C1,C2,C3,C4);

ColorTable supplements Palette by defining a color 'translation table' which lets the current color of any given pOint determine the new color of that pOint when it is written again. The default color table value is (0,1,2,3), which means that when a point is written on the screen, it does not change the color that's already there:

color 0 becomes color 0 color 1 becomes color 1 color 2 becomes color 2 color 3 becomes color 3

The table (3,2,1,0) would cause

color 0 to become color 3 color 1 to become color 2 color 2 to become color 1 color 3 to become color 0

that is, all colors would be reversed. The PutPic procedure always uses the color table; all other draw procedures use the table if a color of - 1 is specified, for example:

Plot(X,Y,-l);

172 TURBO Pascal Reference Manual Extended Graphics

Arc

Syntax: Arc(X, Y,Angle,Radius,Color);

Draws an arc of Angle degrees, starting at the position given by X, Y, with a radius given by Radius. If Angle is positive, the arc turns clock wise; if it is negative, the arc turns counterclockwise. If Color is from 0 through 3, the pen color is selected from the color palette (see page 165); if it is - 1, the color is selected from the color translation table defined by the ColorTable procedure (page 172).

Circle

Syntax: Circle(X, Y,Radius,Color);

Draws a circle in the color given by Color with its center at X, Y and a ra dius as specified by Radius.

The radius of the circle is the same in the horizontal and vertical axes. In 320 x 200 mode this draws a perfect circle, as the display is almost linear. In 640 x 200 mode, however, circles appear as ellipses.

If Color is from 0 through 3, the pen color is selected from the color palette (see page 165 ); if it is - 1, the color is selected from the color translation table defined by the ColorTable procedure (page 172).

GetPic

Syntax: GetPic(Buffer,X1, Y1 ,X2, Y~;

Copies the contents of a rectangular area defined by the integer expres sions X1, Y1,X2, Y2 into the variable Buffer, which may be of any type. X1, Y1 represent the upper left corner and X2,Y2 represent the lower right corner of the area to be stored in Buffer.

The minimum buffer size in bytes required to store the image is calculat ed as:

320 x 200 modes: Size = ((Width + 3) div 4)*Height*2 + 6

640 x 200 modes: Size = ((Width + 7) div 8)*Height + 6

IBM PC GOODIES .. 173 Extended Graphics

where:

Width = abs(x1-x2) + 1 and Height = abs(y1-y2) + 1

Note that it the responsibility of the programmer to ensure that the buffer is large enough to accommodate the entire transfer.

The first 6 bytes of the buffer constitute a three word header (three in tegers). After the transfer, the first word contains 2 in 320 x 200 mode or 1 in 640 x 200 mode. The second word contains the width of the im age and third contains the height. The remaining bytes contain the data. Data is stored with the leftmost pixels in the most significant bits of the bytes. At the end of each row, the remaining bits of the last byte are skipped.

PutPic

Syntax: PutPic(Buffer,X, Y);

Copies the contents of the variable Buffer onto a rectangular area on the screen. The integer expressions X and Y define the lower left-hand corner of the picture area. Buffer is a variable of any type, in which a picture has previously been stored by GetPic. Each bit in the buffer is converted to a color according to the color map before it is written to the screen.

GetDotColor

Syntax: GetDotColor(X, Y);

This integer function returns the color value of the dot located at coordi nate X, Y. Values of 0 through 3 may be returned in 320 x 200 dot graphics, and 0 or 1 in 640 x 200 dot graphics. If X, Y is outside the win dow, GetDotColor returns - 1 .

174 TURBO Pascal Reference Manual Extended Graphics

FillScreen

Syntax: FiIIScreen( Colo,,;

Fills the entire active window with the color specified by the integer ex pression Color. If Color is in the range 0 through 3, the color will be selected from the color palette, if it is -1, the color table will be used. This allows for dramatic effects; with a color table of 3,2,1,0, for exam ple, FiIIScreen( - 1) will invert the entire image within the active window.

FillShape

Syntax: FiIIShape(X, Y,FiIIColor,BorderColo,,;

Fills an area of any shape with the color specified by the integer expres sion FiIIColor which must be in the range 0 through 3. The color transla tion table is not supported. The shape must be entirely enclosed by the color specified by BorderColor, if not, Fil/Shape will 'spill' onto the area outside the shape. X and Yare the coordinates of a point within the im age to be filled.

FillPattern

Syntax: FiIIPattern(X1, Y1,X2, Y2,Colo,,;

Fills a rectangular area defined by the coordinates X1, Y1 ,X2, Y2 with the pattern defined by the Pattera procedure. The pattern is replicated both horizontally and vertically to fill the entire area. Bits of value 0 cause no change to the display, whereas bits of value 1 cause a dot to be written using the color selected by Color.

IBM PC GOODIES 175 Extended Graphics

Pattern

Syntax: Pattern(f?;

Defines the pattern used by the FiIIPattem procedure. The pattern is an 8 x 8 matrix defined by the P parameter which must be of type ar ray[0 .. 7] of Byte. Each byte corresponds to a horizontal line in the pat tern, and each bit corresponds to a pixel. The following shows some sample patterns and the hexadecimal value of each line in the matrix. A hyphen represents a binary 0, and an asterisk represents a binary 1. * * $44 * * * * $AA * - * $88 - * - * - * - * $55 * * $11 * * * * $AA - - * * - $22 - * - * - * - * $55 * * $44 * * * * $AA * - * - $88 - * - * - * - * $55 * * $11 * * * * $AA * - * - $22 - * - * - * - * $55 To use the first pattern, the slanted lines, the following typed constant could be declared and passed as a parameter to Pattem: const Lines: array[0 .. 7] of Byte = ($44,$88,$11,$22,$44,$88,$11,$22);

When the pattern is used by the FillPattem procedure, low bits cause no change to the display, high bits cause a dot to be written.

176 TURBO Pascal Reference Manual Turtlegraphics

Turtlegraphics

The external file GRAPH.BIN that contains the extended graphics rou tines mentioned in the previous section also contains the TURBO Turtle graphics routines, so whenever you include the graphics declaration file GRAPH.P:

{$I GRAPH. P }

you also have access to the turtlegraphics described in the following.

TURBO Turtlegraphics is based on the 'turtle' concept devised by S. Papert and his co-workers at MIT. To make graphics easy for those of us who might have difficulty understanding cartesian coordinates, Papert et al. invented the idea of a 'turtle' that could 'walk' a given distance and turn through a specified angle, drawing a line as it went along. Very sim ple algorithms in this system can create more interesting images than an algorithm of the same length in cartesian coordinates.

Like the other graphics routines, turtlegraphics operate within a window. This window is set to the entire screen by default but the Window or TurtleWindow procedures can be used to define only part of the screen as the active graphics area, safeguarding the rest from being overwrit ten. Turtlegraphics and ordinary graphics can be used simultaneously, and they share a common window.

The TURBO Turtlegraphics routines operate on turtle coordinates. The turtle's home position (0,0) in this coordinate system is always in the middle of the active window, with positive values stretching to the right (X) and upwards (Y), and negative values stretching to the left (X) and downwards (Y):

IBM PC GOODIES 177 Turtlegraphics

Figure 19-3: Turtle Coordinates

The range of coordinates on a full screen is:

320 x 200 modes: X = - 159 .. 0.. 160, Y = - 99 .. 0 .. 100 640 x 200 mode: X = - 319 .. 0.. 320, Y = - 99 .. 0.. 100

but the actual range will be limited to the size of the active window. Coordinates outside the active window are legal, but will be ignored. This means that drawings are 'clipped' to the limits of the active win dow.

Back

Syntax: Back(Dis~;

Moves the turtle backwards the distance given by the integer expres sion Dist from its current position in the direction opposite to the turtle's current heading while drawing a line in the current pen color (if Dist is is negative, the turtle moves forwards).

178 TURBO Pascal Reference Manual Turtlegraphics

ClearScreen

Syntax: ClearScreen;

This procedure clears the active window and homes the turtle.

Forwd

Syntax: Forwd(Dis~;

Moves the turtle forwards the distance given by the integer expression Dist from its current po~ition in the direction the turtle is currently facing, while drawing a line in the current pen color (if Dist is negative, the turtle moves backwards). Heaalng

Syntax: Heading;

The Heading function returns an integer in the range 0 .. 359 giving the direction in which the turtle is currently pointing. 0 is upwards, and in creasing angles represent headings in clockwise direction.

Hide Turtle

Syntax: HideTurtle;

Hides the turtle, so that it is not shown on the screen. This is the initial state of the turtle, so to see the turtle, you must first call the ShowTurtle procedure.

Home

Syntax: Home;

This procedure puts the turtle to its home position at turtle coordinates 0,0 (the middle of the active window), and points it in heading 0 (up wards).

IBM PC GOODIES 179 Turtlegraphics

No Wrap

Syntax: NoWrap;

This procedure disables the turtle from "wrapping," that is, reappearing at the opposite side of the active window if it exceeds the window boun dary. NoWrap is the system's initial value.

PenDown

Syntax: PenDown;

This procedure 'puts the pen down' so that when the turtle moves, it draws a line. This is the initial status of the pen.

Pen Up

Syntax: PenUp;

This procedure 'lifts the pen' so the turtle moves without drawing a line.

SetHeading

Syntax: SetHeading(Angle);

Turns the turtle to the angle specified by the integer expression Angle. 0 is upwards, and increasing angles represent clockwise rotation. If Angle is not in the range 0 .. 359, it is converted into a number in that range.

Four integer constants are pre-defined to easily turn the turtle in the four main directions: North = 0 (up), East = 90 (right), South = 180, and West = 270 (left).

180 TURBO Pascal Reference Manual Turtlegraphics

Se tPen Color

Syntax: SetPenColor( Color,;

Selects the color of the 'pen', that is, the color that will be used for drawing when the turtle moves. Color is an integer expression yielding a value between -1 and 3. If Color is from 0 through 3, the pen color is selected from the color palette (see page 165); if it is - 1, the color is selected from the color translation table defined by the ColorTable pro cedure (page 172).

SetPosition

Syntax: SetPosition(X, Y);

Moves the turtle to the location with coordinates given by the integer ex pressions X and Y without drawing a line.

ShowTurtle

Syntax: ShowTurtle;

Displays the turtle as a small triangle. The turtle is initially hidden, so to see the turtle, you must first call this procedure.

TurnLeft

Syntax: TurnLeft(Angle);

Turns the turtle Angle degrees from its current direction. Positive angles turn the turtle to the left, negative angles turn it to the right.

TurnRight

Syntax: TurnRight(Angle);

Turns the turtle Angle degrees from its current direction. Positive angles turn the turtle to the right, negative angles turn it to the left.

IBM PC GOODIES 181 Turtlegraphics

Turtle Window

Syntax: TurtleWindow(X, Y, W,H);

The TurtleWindow procedure defines an area of the screen as the active graphics area in any of the graphics modes, exactly as does the Win dow procedure. Turtle Window, however, lets you define the window in terms of turtle coordinates, which are more natural to use in turtlegraph ics. X and Yare the screen coordinates of the center of the window; W is its width, and H is its height.

The default TurtleWindow is 159,99,320,200 in 320x200-dot modes and 319,99,640,200 in 640x200-dot mode, that is, the entire screen. If the turtlewindow is defined to fall partly outside the physical screen, it is clipped at the edges of the physical screen.

Turtlegraphics are 'clipped' to the active window, that is, if you move the turtle outside the active window, it will not be shown and it will not draw.

When the window is set (whether by TurtleWindow or by Window, the turtle is initialized to its Home position and heading. Changing screen mode resets the window to the entire screen.

Turtlegraphics operate in turtle coordinates. The turtle's home position (0,0) in this coordinate system is always in the middle of the active win dow, with positive values stretching to the right (X) and upwards (Y), and negative values stretching to the left (X) and downwards (Y):

182 TURBO Pascal Reference Manual Turtlegraphics

Figure 19-4: Turtle Coordinates

The range of coordinates on a full screen is:

320 x 200 modes: x = -159 .. 0 .. 160, Y = -99 .. 0 .. 100 640 x 200 mode: X = -319 .. 0 .. 320, Y = -99 .. 0 .. 100

but the actual range will be limited to the size of the active window.

Coordinates outside the active window are legal, but will be ignored. This means that drawings are 'clipped' to the limits of the active window, and anything drawn outside of the active window is lost.

Turtle There

Syntax: TurtleThere;

This boolean function returns True if the turtle is visible in the active window (after a ShowTurtle), otherwise it returns False.

TurtleDelay

Syntax: TurtleDelay(Ms);

This procedure sets a delay in milliseconds between each step of the turtle. Normally, there is no delay.

IBM PC GOODIES 183 Turtlegraphics

Wrap

Syntax: Wrap;

After a call to this procedure, the turtle will re-appear at the opposite side of the active window when it exceeds the window boundary. Use No Wrap to return to normal.

Xeor

Syntax: Xcor;

This function returns the integer value of the turtle's current X coordinate.

Year

Syntax: Y cor;

This function returns the integer value of the turtle's current Y coordinate.

184 TURBO Pascal Reference Manual Sound

Sound

The PC's speaker is accessed through the standard procedure Sound:

Sound( I);

where I is an integer expression specifying the frequency in Hertz. The specified frequency will be emitted until the speaker is turned off with a call to the NoSound standard procedure:

NoSound

The following example program will emit a 440-Hertz beep for half a second: begin Sound ( 440 ) ; Oelay(500); NoSound; end.

IBM PC GOODIES 185 Editor Command Keys

Editor Command Keys

In addition to the WordStar commands, the editing keys of IBM PC key board have been implemented as primary commands. This means that while e.g. Ctrl-E, Ctrl-X, Ctrl-S, and Ctrl-D still move the cursor up, down, left, and right, you may also use the arrows on the numeric keypad. The following table provides an overview of available editing keys, their functions, and their WordStar-command equivalents:

ACTION PC-KEY COMMAND

Character left Left arrow Ctrl-S Character right Right arrow Ctrl-D Word left Ctrl-left arrow Ctrl-A Word right Ctrl-right arrow Ctrl-F Line up Up arrow Ctrl-E Line down Down arrow Ctrl-X Page up PgUp Ctrl-R Page down PgDn Ctrl-C To left on line Home Ctrl-Q-S To right on line End Ctrl-Q-D To top of page Ctrl-Home Ctrl-Q-E To bot tom of page Ctrl-End Ctrl-Q-X To top of file Ctrl-PgUp Ctrl-Q-R To end of file Ctrl-PgDn Ctrl-Q-C Insert mode on/off Ins Ctrl-V Mark block begin F7 Ctrl-K-B Mark block end Fa Ctrl-K-K Tab Ctrl-I

Table 19-6: IBM PC Keyboard Editing Keys

Note that while maintaining WordStar compatibility in the commands, some function keys have different meanings in WordStar and TURBO.

186 TURBO Pascal Reference Manual Chapter 20 PC-DOS AND MS-DOS

This chapter describes features of TURBO Pascal specific to the PC-DOS and MS-DOS implementations. The information presented on pages 187- 209 will help you use Turbo Pascal efficiently. The remainder of the chapter will be of interest to experienced programmers; it describes such things as machine language routines, technical aspects of the compiler, etc.

Tree-Structured Directories

On the Main Menu

The DOS structured directories are supported by TURBO's main menu:

Logged drive: A Active directory: \ Work file: Main file:

Edit Compile Run Save Dir Quit compiler Options Text: 0 bytes Free: 62903 bytes

> •

Figure 20-1: TURBO Main Menu

PC-DOS AND MS-DOS 187 Tree-Structured Directories

Notice the addition of the A command which lets you change the Active directory using the same path description as with the CHOIR command of DOS. The currently active directory is shown after the colon.

DOS uses a backslash: \ to refer to the ROOT directory, as shown in the example. The rest of directories have names just like files, that is a 1-8 letter name optionally followed by a period and a 1-3 letter type. Each directory can contain ordinary files or other directories.

Files in this system of directories are referenced by a path name in addi tion to the file name. A path name consists of the names of the direc tories leading to the file, separated by backslashes. The complete refer ence to a file called INVADERS.PAS in the directory TURBO is thus: \TURBO\INVADERS.PAS

The first backslash indicates that the path starts from the root directory. If you were logged on some other directory, and you wanted to move to the TURBO directory, you would press A and enter: \TURBO

In every sub-directory you will see two special entries in a DIR listing: and. . The one period serves to identify this directory as a sub-directory. The two periods is a reference to the directory's 'parent' directory. These two periods may be used in a directory path; if, for example, you are logged on a sub-directory of TURBO, you may re turn to TURBO by pressing A and then entering the two periods.

188 TURBO Pascal Reference Manual Tree-Structured Directories

Directory-related procedures

TURBO Pascal provides the following procedures to manipulate the tree-structured directories of MS-DOS.

ChOir

Syntax: ChDir( St);

Changes the current directory to the path specified by the string expres sion St. Also changes the logged drive if St contains a file name. For example: ChDir( 'B:\PROG');

MkDir

Syntax: MkDir( St);

Creates a new sub-directory as specified by the path given by the string expression St. The last item in the path must be a non-existing filename.

RmDir

Syntax: RmDir(St);

Removes the sub-directory specified by the path given by the string ex pression St.

GetDir

Syntax: GetDir(Dr,St);

Returns the current directory of the drive indicated by Dr in the string variable St. Dr is an integer expression where 0 = logged drive, 1 = A, etc. Please note that you can use I/O error trapping to determine whether any of the directory-related procedures were executed successfully (see I/O checking in Chapter 14).

PC-DOS AND MS-DOS 189 Compiler Options

Compiler Options

The 0 command selects the following menu from which you may view and change some default values of the compiler. It also provides a help ful function to find runtime errors in programs compiled into object code files.

compile -> Memory Com-file cHn-file command line Parameter: Find run-time error Quit

Figure 20-2: Options Menu

Memory / Com file / cHn-file

The three commands M, C, and H select the compiler mode, i.e. where to put the code which results from the compilation. Memory is the de fault mode. When active, code is produced in memory and resides there ready to be activated by a Run command. .

Com-file is selected by pressing C. The arrow moves to point to this line. The compiler writes code to a file with the same name as the Work file (or Main file, if specified) and the file type .COM. This file contains the program code and Pascal runtime library, and may be activated by typ ing its name at the console.

cHain-file is selected by pressing H. The arrow moves to point to this line. The compiler writes code to a file with the same name as the Work file (or Main file, if specified) and the file type .CHN. This file contains the program code but no Pascal library and must be activated from another TURBO Pascal program with the Chain procedure (see page 193).

When the Com mode is selected, four additional lines will appear on the screen:

190 TURBO Pascal Reference Manual Compiler Options

mlnlmum cOde segment size: XXXX paragraphs (max.YYYY) minimum Data segment size: XXXX paragraphs (max.YYYY) mInimum free dynamic memory: XXXX paragraphs mAximum free dynamic memory: XXXX paragraphs

Figure 20-3: Memory Usage Menu

The use of these commands is described in the following sections.

Minimum Code Segment Size

The O-command is used to set the minimum size of the code segment for a .COM using Chain or Execute. As discussed on page 193 , Chain and Execute do not change the base addresses of the code, data, and stack segments, and a 'root' program using Chain or Execute must therefore allocate segments of sufficient size to accommodate the larg est segments in any Chained or Executed program.

Consequently, when compiling a 'root' program, you must set the value of the Minimum Code Segment Size to at least the same value as the largest code segment size of the programs to be chained/executed from that root. The required values are obtained from the status printout ter minating any compilation. The values are in hexadecimal and specify number of paragraphs, a paragraph being 16 bytes.

Minimum Data Segment Size

The D-command is used to set the minimum size of the data segment for a .COM using Chain or Execute. As discussed above, a 'root' pro gram using these commands must allocate segments of sufficient size to accommodate the largest data of any Chained or Executed program.

Consequently, when compiling a 'root' program, you must set the value of the Minimum Data Segment Size to at least the same value as the largest data segment size of the programs to be chained/executed from that root. The required values are obtained from the status printout ter minating any compilation. The values are in hexadecimal and specify number of paragraphs, a paragraph being 16 bytes.

PC-DOS AND MS-DOS 191 Compiler Options

Minimum Free Dynamic Memory

This value specifies the minimum memory size required for stack and heap. The value is in hexadecimal and specifies a number of paragraphs, a paragraph being 16 bytes.

Maximum Free Dynamic Memory

This value specifies the maximum memory size allocated for stack and heap. It must be used in programs which operate in a mUlti-user environ ment to assure that the program does not allocate the entire free memory. The value is in hexadecimal and specifies a number of paragraphs, a para graph being 16 bytes.

Command Line Parameters

The P-command lets you enter one or more parameters which are passed to your program when running it in Memory mode, just as if they had been entered on the DOS command line. These parameters may be accessed through the ParamCount and ParamStr functions.

Find Run-time Error

When you run a program compiled in memory, and a run-time error oc curs, the editor is invoked, and the error is automatically pOinted out. This, of course, is not possible if the program is in a .COM file or an .CHN file. Run time errors then print out the error code and the value of the program counter at the time of the error:

Run-time error 01, PC=lB56 Program aborted

Figure 20-4: Run-time Error Message

To find the place in the source text where the error occurred, enter the F command. When prompted for the address, enter the address given by the error message:

Enter PC: IB56

Figure 20-5: Find Run-time Error 192 TURBO Pascal Reference Manual Compiler Options

The place in the source text is now found and pointed out exactly as if the error had occurred while running the program in memory.

Notice that locating errors in programs using overlays can be a bit more tricky, as explained on page 156.

Standard Identifiers

The following standard identifiers are unique to the DOS implementa tions:

CSeg LongFilePos MemW PortW DSeg LongFileSize MsDos SSeg Intr LongSeek Ofs Seg

Chain and Execute

TURBO Pascal provides two procedures Chain and Execute which allow TURBO programs to activate other TURBO programs. The syntax of the procedure calls are:

Chain(FilVar') Execute( FilVar')

where FilVar is a file variable of any type, previously assigned to a disk file with the standard procedure Assign. If the file exists, it is loaded into memory and executed.

The Chain procedure is used only to activate special TURBO Pascal .CHN files, i.e. files compiled with the cHn-file option selected on the Options menu (see page 190). Such a file contains only program code; no Pascal library, it uses the Pascal library already present in memory. Chain files must have the same compiler directives as the main module. The Execute procedure is used to activate any TURBO Pascal .COM file. If the disk file does not exist, an I/O error occurs. This error is treated as described on page 116. When the I compiler directive is passive ({$I-}), program execution continues with the statement following the failed Chain or Execute statement, and the IOresult function must be called prior to further I/O.

PC-DOS AND MS-DOS 193 Chain and Execute

Data can be transferred from the current program to the chained pro gram either by shared global variables or by absolute address variables.

To ensure overlapping, shared global variables should be declared as the very first variables in both programs, and they must be listed in the same order in both declarations. Furthermore, both programs must be compiled to the same size of code and data segments (see page 191). When these conditions are satisfied, the variables will be placed at the same address in memory by both programs, and as TURBO Pascal does not automatically initialize its variables, they may be shared.

Example: Program MAIN. COM: program Main; var Txt: string[ 80] ; CntPrg: file; begin Write( 'Enter any text: '); Readln(Txt); Assign(CntPrg, 'ChrCount.chn'); Chain( CntPrg); end.

Program CHRCOUNT.CHN: program ChrCount; var Txt: string[80]; NoOfChar, NoOfUpc, I: Integer;

begin NoOfUpc := 0; NoOfChar := Length(Txt); for I := 1 to length(Txt) do if Txt [ I] in [ , A'. .' Z ' ] then NoOfUpc : = Succ (NoOfUpc) ; Write( 'No of characters in entry: ',NoOfChar); Writeln('. No of upper case characters: " NoOfUpc,'.'); end.

194 TURBO Pascal Reference Manual Chain and Execute

The safest way to ensure that chain and execute files share data correctly is to place all global constant, type and variable declarations in a single include file. Then, include this "declaration module" in all the chain and execute programs:

program MainModule; {$I DECLARE. INC All constant, type & variable declarations} begin

Chain( ... ); {chain to ChainModule}

end.

program ChainModule ; {$I DECLARE. INC All constant, type & variable declarations} begin

Execute ( ... ); {re-Ioad MainModule}

end.

If you want a TURBO program to determine whether it was invoked by eXecute or directly from the DOS command line, you should use an ab solute variable at address Cseg:$80. This is the command line length byte, and when a program is called from DOS, it contains a value between 0 and 127. When eXecuting a program, therefore, the calling program should set this variable to something higher than 127. When you then check the variable in the called program, a value between 0 and 127 indicates that the program was called from DOS, a higher value that it was called from another TURBO program.

Chaining and eXecuting TURBO programs does not alter the memory al location state. The base addresses and sizes of the code, data and stack segments are not changed; Chain and Execute only replace the program code in the code segment. 'Alien' programs, therefore, cannot be initiated from a TURBO program.

It is important that the first program which executes a Chain statement allocates enough memory for the code, data, and stack segments to accommodate the largest .CHN program. This is done by using the Options menu to change the minimum code, data and free memory sizes (see page 190).

PC-DOS AND MS-DOS 195 Overlays

Note: Refer to Appendix N (general question section) for a "cookbook" method of compiling to .CHN files.

Note that neither Chain nor Execute can be used in direct mode, that is, from a program run with the compiler options switch in position Memory (page 190). Overlays

During execution, the system normally expects to find its overlay files on the logged drive and current directory. The OvrPath procedure may be used to change this default value. .

OvrPath Procedure

Syntax: OvrPath(Path};

where Path is a string expression specifying a subdirectory path (see page 188 for an explanation of DOS directory paths). On subsequent calls to overlay files, the files will be expected in the specified directory. Once an overlay file has been opened in one directory, future calls to the same file will look in the same directory. The path may optionally specify a drive (A:, B:, etc.).

The current directory is identified by a single period. OvrPath{'.') thus causes overlay files to be sought on the current directory.

Example: program OvrTest; overlay procedure ProcA; begin Writeln('Overlay A'); end; overlay procedure ProcB; begin Writeln( 'Overlay B'); end;

196 TURBO Pascal Reference Manual Overlays

procedure Dummy; begin {Dummy procedure to separate the overlays into two groups} end;

overlay procedure ProcC; begin Writeln( 'Overlay C'); end; begin OvrPath( '\subl'); ProcA; OvrPath( , . ' ); ProcC; OvrPath( '\subl'); ProcB; end.

The first call to OvrPath specifies overlays to be sought on the subdirec tory \sub1. The call to ProcA therefore causes the first overlay file (con taining the two overlay procedures ProcA and ProcB) to be opened on this directory.

Next, the OvrPath('.') statement specifies that following overlays are to be found on the current directory. The call to ProcC opens the second overlay file here.

The following ProcB statement calls an overlay procedure in the first overlay file; to ensure that it is sought on the \sub1 directory, the OvrPath('\sub 1 ') statement must be executed before the call.

PC-DOS AND MS-DOS 197 Files

Files

File Names

A file name in DOS consists of a path of directory names, separated by backslashes, leading up to the desired directory, and followed by the actual file name:

Drive: \ Dimame\ ... \ Dimame\ Filename

If the path begins with a backslash, it starts in the root directory; other wise, it starts in the logged drive.

The Drive and path specific~tion is optional. If omitted, the file is as sumed to reside on the logged drive.

The FileName consists of a name of one through eight letters or digits, optionally followed by a period and a file type of one through three letters or digits.

Number of Open Files

The maximum number of files that may be open at any given time can be specified using the F compiler directive. The directive, {$FIO}. sets a maximum limit of 10 files that can be opened simultaneously. Two important notes about file handles:

When your computer is booted, DOS sets the maximum number offiles that can be opened by an application program. It reads the CONFIG.SYS file in the root directory of the booted drive and looks for the "FILES = "statement. The maximum number of files that can be opened is 20. However, DOS uses 5 of these file handles itself, thus leaving a maximum of 15 for your program. To claim all available handles, your CONFIG.SYS file must have the statement: FILES = 20. If you do not specify the files statement, a default of 8 will be allowed (5 of which are used by DOS) and your program will be limited to 3 files open at any given time.

A file handle is allocated by a Reset, Rewrite or Append statement. If no handle is available, an I/O error F3 will occur ("TOO MANY FILES"). A file

198 TURBO Pascal Reference Manual Files

handle is released (and thus made available to your program again) by a Close statement:

Assign(f, 'TEST'); {Open the file: } Reset(f) ; {allocates a file handle}

Close (f) ; {releases file handle

Please note that even a file used only for reading must be closed in order to again make its handle available to the program. Note that even though the F compiler directive has been used to allo cate sufficient file space, you may still experience a 'too many open files' error condition, if the operating system runs out of file buffers. If that happens, you should supply a higher value for the 'files = xx' parameter in the CONFIG.SYS file. The default value is usually 8. For further detail, please refer to your MS-DOS documentation.

Extended File Size

The following three additional file routines exist to accommodate the ex tended range of records in DOS. These are:

LongFileSize function, LongFilePos function, and LongSeek procedure

They correspond to their Integer equivalents FileSize, FilePosition, and Position but operate with Rea/s. The functions thus return results of type Real, and the second parameter of the LongSeek procedure must be an expression of type Real.

File of Byte

In the CP/M implementations, access to non-TURBO files (except text files) must be done through untyped files because the two first bytes of typed TURBO files always contain the number of components in the file. This is not the case in the DOS versions, however, and a non-turbo file may therefore be declared as a file of byte and accessed randomly with Seek, Read, and Write.

PC-DOS AND MS-DOS 199 Files

Untyped Files

An optional second parameter on Reset and ReWrite may be used to specify the block size to be used by BlockRead and Block Write. For ex ample: Assign(InFile, 'INDATA'); Reset(InFile,BlockSize);

where BlockSize is an integer expression.

Flush Procedure

The Flush procedure has no effect with typed files in DOS, as DOS typed file variables do not employ a sector buffer.

Truncate Procedure

Syntax: Truncate(FilVa,,;

This procedure truncates the file identified by FilVar at the current posi tion of the file pointer, that is, records beyond the file pointer are cut away. Truncate also prepares the file for subsequent output.

Text Files

Buffer Size

The text file buffer size is 128 bytes by default. This is adequate for most applications, but heavily I/O-bound programs, as for example a copy program, will benefit from a larger buffer, as it will reduce disk head movement.

You are therefore given the option to specify the buffer size when de claring a text file: VAR TextFile: Text[$800];

declares a text file variable with a buffer size of 2K bytes.

200 TURBO Pascal Reference Manual Files

Append Procedure

Syntax: Append(FilVa,,;

The disk file assigned to the file variable FilVar is opened, and the file pointer is moved to the end of the file. The only operation allowed after Append is appending of new components.

Flush Procedure

The Flush procedure causes the file buffer to be flushed when used with text files.

Logical Devices

The following additional logical devices are provided:

INP: Refers to the MS-DOS standard input file (standard handle number 0).

our: Refers to the MS-DOS standard output file (standard handle number 1).

ERR: Refers to the MS-DOS standard error output file (standard handle number 2).

These devices may also be used with typed and untyped files.

The MS-DOS operating system itself also provides a number of logical devices, for instance 'CON', 'LST' and 'AUX'. TURBO Pascal will treat these devices as if they were disk files, with one exception: when a text file is opened, using Reset, Rewrite or Append, TURBO Pascal asks MS-DOS for the status of the file. If MS-DOS reports that the file is a device, TURBO Pascal disables the buffering that normally occurs on textfiles, and all 1/0 operations on the file are done on a character by character basis.

The D compiler option may be used to disable this check. The default state of the D option is {$D +}, and in this state, device checks are made. In the {$D -} state, no checks are made and all device 1/0 operations are buffered. In this case, a call to the flush standard pro cedure will ensure that the characters you have written to a file have ac tually been sent to it.

PC-DOS AND MS-DOS 201 Files

I/O redirection

PC/MS-DOS TURBO Pascal supports the I/O redirection feature provid ed by the MS-DOS operating system. In short, I/O redirection allows you to use disk files as the standard input source and/or standard output destination. Furthermore, a program supporting I/O redirection can be used as a filter in a pipe. Details on I/O redirection, filters, and pipes, are found in the MS-DOS documentation.

I/O redirection is enabled through the G (get) and P (put) compiler direc tives. The G directive controls the input file and the P directive controls the output file. The G and P directives both require an integer argument, which defines the size of the input or output buffer. The default buffer sizes are zero, and with these, Input and Output will refer to the CON: or the TRM: device.

If a non-zero input buffer is defined, for instance ($G256}, the standard Input file will refer to the MS-DOS standard input handle. Likewise, if a non-zero output buffer is defined, for instance ($P1024}, the standard Output file will refer to the MS-DOS standard output handle. The 0 com piler directive (see page 201) applies to such non-zero-buffer Input and Output files. The P and G compiler directives must be placed at the be ginning of a program to have any effect, i.e. before the declaration part.

The following program demonstrates re-directed I/O. It will read charac ters from the standard input file, keep a count of each alphabetical char acter (A through Z), and output a frequency distribution graph to the standard output file:

{$G512,P512,D-} program CharacterFrequencyCounter; const Bar #223; var Count: array[65 .. 90] of Real; Ch: Char; I,Graph: Integer; Max, Total: Real; begin Max :- 0; Total := 0; for I := 65 to 90 do Count[I] := 0; while not EOF do

202 TURBO Pascal Reference Manual Files

begin Read(Ch) ; if Ord(Ch) > 127 then Ch := Chr(Ord(Ch)-128); Ch :a UpCase(Ch); if Ch in [ , A' . . 'Z' J then begin Count [Ord( Ch)] : = Count [Ord( Ch)] +1; if Count[Ord(Ch)] > Max then Max := Count[Ord(Ch)]; Total := Total +1; end; end; Write1n(' Count %'); for I : = 65 to 90 do begin Write(Chr(I),': ',Count[I] :5:0, Count[I]*100/Total:5:0,' '); for Graph: = 1 to Round ( Count[ I J*63/Max) do Write(Bar) ; Write1n; end; Writeln( 'Total', Total:5:0); end.

If the program is compiled into a file called COUNT.COM, then the MS DOS command:

COUNT < TEXT.DOC > CHAR.CNT

will read the file TEXT. DOC and output the graph to the file CHAR.CNT.

Absolute Variables

Variables may be declared to reside at specific memory addresses, and are then called absolute. This is done by adding to the variable declara tion the reserved word absolute followed by two Integer constants specifying a segment and an offset at which the variable is to be locat ed:

var Abc: Integer absolute $OOOO:$OOEE; Def: Integer absolute $OOOO:$OOFO;

PC-DOS AND MS-DOS 203 Absolute Variables

The first constant specifies the segment base address, and the second constant specifies the offset within that segment. The standard identifiers CSeg and DSeg may be used to place variables at absolute addresses within the code segment (C8eg) or the data segment (08eg):

Special: array[l .. CodeSize]ofbyteabsoluteCSeg:$05F3;

Absolute may also be used to declare a variable "on top" of another variable, i.e. to declare that a variable should start at the same address as another variable. When absolute is followed by the identifier of a variable or parameter, the new variable will start at the address of that variable parameter.

Example: var Str: string[32]; StrLen: Byte absolute Str;

This declaration specifies that the variable StrLen should start at the same address as the variable Str, and as the first byte of a string vari able contains the length of the string, StrLen will contain the length of Str. Notice that an absolute variable declaration may only specify one identifier. Further details on space allocation for variables are found on page 216.

Absolute Address Functions

The following functions provide information about program variable ad dresses and system pointers.

Addr

Syntax: Addr(Name);

Returns the address in memory of the first byte of the variable with the identifier Name. If Name is an array, it may be subscribed, and if Name is a record, specific fields may be selected. The value returned is a 32 bit pointer consisting of a segment address and an offset.

204 TURBO Pascal Reference Manual Absolute Address Functions

Dfs

Syntax: Ofs(Name);

Returns the offset in the segment of memory occupied by the first byte of the variable, procedure or function with the identifier Name. If Name is an array, it may be subscribed, and if Name is a record, specific fields may be selected. The value returned is an Integer.

Seg

Syntax: Seg(Name);

Returns the address of the segment containing the first byte of the vari able with the identifier Name. If Name is an array, it may be subscribed, and if Name is a record, specific fields may be selected. The value re turned is an Integer.

Cseg

Syntax: Cseg;

Returns the base address of the Code segment. The value returned is an Integer.

Dseg

Syntax: Dseg;

Returns the base address of the Data segment. The value returned is an Integer.

Sseg

Syntax: Sseg;

Returns the base address of the Stack segment. The value returned is an Integer.

PC-DOS AND MS-DOS 205 Predefined Arrays

Predefined Arrays

TURBO Pascal offers four predefined arrays of type Byte, called Mem, MemW, Port and PortW which are used to access CPU memory and data ports.

MemArray

The predefined arrays Mem and MemWare used to access memory. Each component of the array Mem is a byte, and each component of the array

MemW is a word (two bytes, LSB first). The index must be an address specified as the segment base address and an offset separated by a colon and both of type 'Integer.

The following statement assigns the value of the byte located in seg ment 0000 at offset $0081 to the variable Value Va1ue:=Mem[0000:$0081]; Mern[ 0000: $0081] : = Value;

While the following statement: Value :=MernW[Seg(Var) : Ofs(Var)];

places the value of the Integer variable Value in the memory location oc cupied by the two first bytes of the variable Var.

Port Array

The Port and PortW array are used to access the data ports of the 8086/88 CPU. Each element of the array represents a data port, with the index corresponding to port numbers. As data ports are selected by 16-bit addresses the index type is Integer. When a value is assigned to a component of Port or PortW it is output to the port specified. When a component of port is referenced in an expression, its value is input from the port specified. The components of the Port array are of type Byte and the components of PortWare of type Integer.

Example: Port[56] :=10;

206 TURBO Pascal Reference Manual Pointer Related Items

The use of the port array is restricted to assignment and reference in expressions only, i.e. components of Port and PortW cannot be used as variable parameters to procedures and functions. Furthermore, opera tions referring to the entire port array (reference without index) are not allowed. With Statements

With statements may be nested to a maximum of 9 levels.

Pointer Related Items MemAvail The standard function MemA vail is available to determine the available space on the heap at any given time. The result is an Integer specifying the number of available paragraphs on the heap (a paragraph Is 16 bytes). Pointer Values In very special circumstances it can be of interest to assign a specific value to a pointer variable without using another pointer variable or it can be of interest to obtain the actual value of a pointer variable.

Assigning a Value to a Pointer The standard function Ptr can be used to assign specific values to a pointer variable. The function returns a 32 bit pOinter consisting of a segment address and an offset.

Example: POinter:=Ptr(Cseg,$80); Obtaining The Value of a Pointer A pOinter value is represented as a 32 bit entity and the standard func tion Ord can therefore not be used to obtain its value. Instead the func tions Ofs and Seg must be used.

The following statement obtains the value of the pointer P (which is a segment address and an offset):

A SegmentPart:=Seg(p ); A OffsetPart:=Ofs(P );

PC-DOS AND MS-DOS 207 DOS Function Calls

DOS Function Calls

For the purpose of making DOS system calls, TURBO Pascal introduces a procedure MsDos, which has a record as parameter:

MsDos(Record) ;

Details on DOS system calls and BIOS routines are found in the IBM DOS Technical Reference Manual.

The parameter to MsDos must be of the type:

record AX,BX,CX,DX,BP,SI,DI,DS,ES,F1ags: Integer; end;

or, alternatively:

reoord oase Integer of 1: (AX,BX,CX,DX,BP,SI,DI,DS,ES,F1ags: Integer); 2: (AL,AH,BL,BH,CL,CH,DL,DH Byte); end;

Before TURBO makes the DOS system call, the registers AX, BX, ex, OX, BP, SI, 01, OS, and ES are loaded with the values specified in the record parameter. When DOS has finished operation the MsDos pro cedure will restore the registers to the record thus making any results from DOS available.

The following example shows how to use an MsDos function call to get the time from DOS:

procedure Timer (var Hour, Min, Sec, Frac: Integer) ; type RegPack record AX,BX,CX,DX,BP,SI,DI,DS,ES,F1ags: Integer; end; var Regs: Regpack;

208 TURBO Pascal Reference Manual DOS Function Calls

begin with Regs do begin AX := $2COO; MsDos (Regs) ; Hour hi (CX); Min lo(CX); Sec hi(DX); Frac lo(DX); end;

end; {procedure Timer}

User Written I/O Drivers

For some applications it is practical for a programmer to define his own input and output drivers, i.e. routines which perform input and output of characters to and from an external device. The following drivers are part of the TURBO environment, and used by the standard I/O drivers (although they are not available as standard procedures or functions):

function ConSt boolean; { 11 } function Con In: Char; { 8 } procedure ConOut (Ch: Char); { 2 } procedure LstOut (Ch: Char); { 5 } procedure AuxOut (Ch: Char); { 4 } function AuxIn: Char; { 3 } procedure UsrOut (Ch: Char); { 2 } function Usrln: Char; { 8 }

The ConSt routine is called by the function KeyPressed, the Conln and ConOut routines are used by the CON:, TRM:, and KBD: devices, the LstOut routine is used by the LST: device, the AuxOut and AuxIn rou tines are used by the AUX: device, and the UsrOut and Usrln routines are used by the USR: device.

By default, these drivers are assigned to the DOS system calls as shown in curly brackets in the above listing of drivers.

PC-DOS AND MS-DOS 209 User Written I/O Drivers

This, however, may be changed by the programmer by assigning the address of a self-defined procedure or driver function to one of the following standard variables: Variable Contains the address of the

ConStPtr ConSt function ConlnPtr Conln function ConOutPtr ConOut procedure LstOutPtr LstOut procedure AuxOutPtr AuxOut procedure AuxlnPtr AuxIn function UsrOutPtr UsrOut procedure UsrlnPtr Usrln function

A user defined driver procedure or driver function must match the definitions given above, i.e. a ConSt driver must be a boolean function, a Conln driver must be a char function, etc.

External Subprograms

The reserved word external is used to declare external procedures and functions, typically procedures and functions written in machine code. External must be followed by a string constant specifying the name of a file in which executable machine code for the external procedure or function must reside. The default file type is .COM.

During compilation of a program containing external functions or pro cedures, the associated files are loaded and placed in the object code. As it is impossible to know in advance exactly where in the object code the external code will be placed this code must be relocatable, and no references must be made to the data segment. Furthermore the exter nal code must save the registers BP, es, DS and SS and restore these before executing the RET instruction.

An external subprogram has no block, i.e. no declaration part and no statement part. Only the subprogram heading is specified, immediately followed by the reserved word external and a filename specifying where to find the executable code for the subprogram.

210 TURBO Pascal Reference Manual External Subprograms

Example: procedure DiskReset; external 'DSKRESET'; function IOstatus: boolean; external 'IOSTAT';

An external file may contain code for more than one subprogram. The first subprogram is declared as described above, and the following are declared by specifying the identifier of the first subprogram followed by an integer constant specifying an offset, enclosed in square brackets. The entry point of each subprogram is the address of the first subprogram plus the offset.

Example: procedure Coml; external' SERIAL. BIN' ; function ComlStat: Boolean; external Coml[3]; procedure ComlIn: Char; external Coml[6]; procedure ComlOut: Char; external Coml[9];

The above example loads the file SERIAL.BIN into the program code, and defines four procedures called Com1, Com 1Stat, Comlln, and Com10ut with entry points at the base address of the external code plus 0, 3, 6 and 9, respectively. When an external file contains several subprograms, the first part of the code is typically a jump table, as as sumed in the example. In that way, the entry points of the subprograms remain unchanged if the external file is modified.

Parameters may be passed to external subprograms, and the syntax is exactly the same as that of calls to ordinary procedures and functions:

procedure Plot(X,Y: Integer); external 'PLOT'; procedure QuickSort(var List: PartNo); external 'QS';

External subprograms and parameter passing is discussed further on page 221.

In-line Machine Code

TURBO Pascal features the inline statements as a very convenient way of inserting machine code instructions directly into the program text. An inline statement consists of the reserved word inline followed by one or more code elements separated by slashes and enclosed in parentheses.

PC-DOS AND MS-DOS .. 211 In-line Machine Code

A code element is built from one or more data elements, separated by plus (+) or minus (-) signs. A data element is either an integer con stant, a variable identifier, a procedure identifier, a function identifier, or a location counter reference. A location counter reference is written as an asterisk (*).

Example: inline (101$2345/count+1/sort-*+2);

Each code element generates one byte or one word (two bytes) of code. The value of the byte or the word is calculated by adding or subtracting the values of the data elements according to the signs that separate them. The value of a variable identifier is the address (or offset) of the variable. The value of a procedure or function identifier is the address (or offset) of the procedure or function. The value of a location counter reference is the address (or offset) of the location counter, i.e. the ad dress at which to generate the next byte of code.

A code element will generate one byte of code if it consists of integer constants only, and if its value is within the a-bit range (0 .. 255). If the value is outside the a-bit range, or if the code element refers to variable, procedure, or function identifiers, or if the code element contains a loca tion counter reference, one word of code is generated (least significant byte first).

The '<' and '>' characters may be used to override the automatic size selection described above. If a code element starts with a '<' character, only the least significant byte of the value is coded, even if it is a 16-bit value. If a code element starts with a ' > ' character, a word is always coded, even though the most significant byte is zero.

Example: inline «$1234/>$44);

This inline statement generates three bytes of code: $34, $44, $00.

212 TURBO Pascal Reference Manual In-line Machine Code

lative to the BP (base page) register, the use of which automatically causes the stack segment to be selected. The base segment of typed constants is the code segment, which is accessible through the CS register. Inllne statements should not attempt to access variables that are not declared in the main program or in the current subprogram.

The following example of an inline statement generates machine code that will convert all characters in its string argument to upper case.

procedure UpperCase(var Strg: Str) ; {Str is type String[255]} begin inline ($C4/$BE/Strgl { LES OI,Strg[BP] $26/$8A/$001 { MOV CL, ES: [01] $FE/$C11 { INC CL $FE/$C91 { L1: DEC CL $74/$131 { JZ L2 $471 { INC 01 $26/$801$30/$611 { CMP ES:BYTE PTR [01], 'a'} $72/$F51 { JB L1 } $26/$801$30/$7AI { CMP ES:BYTE PTR [01], 'z'} $77/$EFI { JA L1 } $26/$801$20/$201 { SUB ES:BYTE PTR [OI],20H} $EB/$E9) ; { JMP SHORT L1 } { L2: } end;

Inline statements may be freely mixed with other statements throughout the statement part of a block, and may use a" CPU registers. Note, however, that the contents of the registers BP, SP, OS, and SS must be the same on exit as on entry.

PC-DOS AND MS-DOS .. 213 Interrupt Handling

Interrupt Handling

Upon entry to an interrupt routine, a couple of precautions should be taken. First, all of the hardware registers should be preserved upon entry to the routine. Also, in order to enable the interrupt routine to access the program's global Data segment, the OS register must be saved and initialized to the correct value. The following inline statement performs these tasks correctly:

Inline($50/$53/$51/$52/$57/$56/$06/$lE/$FB/$2E/$Al/ Dat~Segment/$8E/$D8);

In addition to this inline statement at the beginning of the interrupt handler, a global typed constant must be declared:

oonst Dat~Segment : integer = 0 j and the typed constant must be initialized at run time:

begin Dat~Segment : = Dseg; end;

Upon exit from an interrupt handling routine, some bookkeeping is also necessary. The hardware registers must be restored, OS must be restored, and because Turbo Pascal pushed some registers onto the stack at the beginning of the interrupt handler:

Push BP Mov BP, SP Push SP

The stack must be properly set up before the IRET is executed. The following inline statement performs all these operations:

Inline($lF/$07/$5E/$5F/$5A/$59/$5B/$58/$8B/$E5/ $5D/$CF);

Note that the variable Data-Segment is a global variable equal to Turbo Pascal's variable DSEG.

214 TURBO Pascal Reference Manual Interrupt Handling

An interrupt service procedure must not employ any I/O operations us ing the standard procedures and functions of TURBO Pascal, as the BOOS is not re-entrant. The programmer must initialize the interrupt vector used to activate the interrupt service routine.

Intr procedure

Syntax: Intr(lnterruptNo, Result)

This procedure initializes the registers and flags as specified in the parameter Result which must be of type:

Result - record AX,BX,CX,DX,BP,SI,DI,DS,ES,Flags: Integer; end;

It then makes the ,software interrupt given by the parameter interruptNo which must be an Integer constant. When the interrupt service routine returns control to your program, Result will contain any values returned from the service routine.

PC-DOS AND MS-DOS 215 Internal Data Formats

Internal Data Formats

In the following descriptions, the symbol @ denotes the offset of the first byte occupied by a variable of the given type within its segment. The segment base address can be determined by using the standard function Seg.

Global and local variables, and typed constants occupy different seg ments as follows:

Global variables reside in the data segment and the offset is relative to the DS register.

Local variables reside in the stack segment and the offset is relative to the BP register.

Typed constants reside in the code segment and the offset is relative to the CS register.

All variables are contained within their base segment.

Basic Data Types

The basic data types may be grouped into structures (arrays, records, and disk files), but this structuring will not affect their internal formats.

Scalars

The following scalars are all stored in a single byte: Integer subranges with both bounds in the range 0 .. 255, booleans, chars, and declared scalars with less than 256 possible values. This byte contains the ordinal value of the variable.

The following scalars are all stored in two bytes: Integers, Integer subranges with one or both bounds not within the range 0 .. 255, and de clared scalars with more than 256 possible values. These bytes contain a 2's complement 16-bit value with the least significant byte stored first.

216 TURBO Pascal Reference Manual Internal Data Formats

Rea/s

Reals occupy 6 bytes, giving a floating point value with a 40-bit mantissa and an 8-bit 2's exponent. The exponent is stored in the first byte and the mantissa in the next five bytes with the least significant byte first:

@ Exponent @ +1 LSB of mantissa

@ +5 MSB of mantissa

The exponent uses binary format with an offset of $80. Hence, an ex ponent of $84 indicates that the value of the mantissa is to be multiplied by 2 "($84-$80) = 2 "4 = 16. If the exponent is zero, the floating point value is considered to be zero.

The value of the mantissa is obtained by dividing the 40-bit unsigned in teger by 2"40. The mantissa is always normalized, i.e. the most significant bit (bit 7 of the fifth byte) should be interpreted as a 1. The sign of the mantissa is stored in this bit, however, a 1 indicating that the number is negative, and a 0 indicating that the number is positive.

Strings

A string occupies as many bytes as its maximum length plus one. The first byte contains the current length of the string. The following bytes contain the string with the first character stored at the lowest address. In the table shown below, L denotes the current length of the string, and Max denotes the maximum length:

@ Current length (L) @ +1 First character @ +2 Second character

@ +L Last character @ +L+1 Unused

@ + Max Unused

PC-DOS AND MS-DOS" 217 Internal Data Formats

Sets

An element in a Set occupies one bit, and as the maximum number of elements in a set is 256, a set variable will never occupy more than 32 bytes (256/8).

If a set contains less than 256 elements, some of the bits are bound to be zero at all times and need therefore not be stored. In terms of memory efficiency, the best way to store a set variable of a given type would then be to "cut off" all insignificant bits, and rotate the remaining bits so that the first element of the set would occupy the first bit of the first byte. Such rotate operations, however, are quite slow, and TURBO therefore employs a compromise: Only bytes which are statically zero (i.e. bytes of which no bits are used) are not stored. This method of compression is very fast and in most cases as memory efficient as the rotation method.

The number of bytes occupied by a set variable is calculated as (Max div 8) - (Min div 8) + 1, where Max and Min are the upper and lower bounds of the base type of that set. The memory address of a specific element E is:

MemAddress = @ + (E div 8) - (Min div 8)

and the bit address within the byte at MemAddress is:

BitAddress = E mod 8

where E denotes the ordinal value of the element.

Pointers

A pointer consists of four bytes containing a segment base address and an offset. The two least significant bytes contains the offset and the two most significant bytes the base addres5. Both are stored in memory us ing byte reversed format, i.e. the least significant byte is stored first. The value nil corresponds to two zero words.

218 TURBO Pascal Reference Manual Internal Data Formats

Data Structures

Data structures are built from the basic data types using various struc turing methods. Three different structuring methods exist: Arrays, records, and disk files. The structuring of data does not in any way affect the internal formats of the basic data types.

Arrays

The components with the lowest index values are stored at the lowest memory address. A multi-dimensional array is stored with the rightmost dimension increasing first, e.g. given the array

Board: array[l .. 8,1 .. 8] of Square

you have the following memory layout of its components:

lowest address: Board[l,l] Board[1,2]

Board[1,8] Board[2,1] Board[2,2]

Highest address: Board[8,8]

Records

The first field of a record is stored at the lowest memory address. If the record contains no variant parts, the length is given by the sum of the lengths of the individual fields. If a record contains a variant, the total number of bytes occupied by the record is given by the length of the fixed part plus the length of the largest of its variant parts. Each variant starts at the same memory address.

PC-DOS AND MS-DOS" 219 Internal Data Formats

Disk Files

Disk files are different from other data structures in that data is not stored in internal memory but in a file on an external device. A disk file is controlled through a file interface block (FIB).

File Interface Blocks

The following table shows the format of an FIB:

@+O File handle (LSB). @+1 File handle (MSB). @+2 Record length (LSB) or flags byte. @+3 Record length (MSB) or character buffer. @+4 Buffer offset (LSB). @+5 Buffer offset (MSB). @+6 Buffer size (LSB). @+7 Buffer size (MSB). @+8 Buffer pOinter (LSB). @+9 Buffer pOinter (MSB). @+10 Buffer end (LSB). @+11 Buffer end (MSB). @+12 First byte of file path.

@+75 Last byte of file path.

The word at @ + 0 and @ + 1 contains the 16-bit file handle returned by MS-DOS when the file was opened (or OFFFFH when the file is closed). For typed and untyped files, the word at @ + 2 and @ + 3 con tains the record length in bytes (zero if the file is closed), and bytes @ + 4 to @ + 11 are unused.

For text files, the format of the flags byte at @ + 2 is:

Bit 0 .. 3 File type. Bit 5 Pre-read character flag. Bit 6 Output flag. Bit 7 Input flag.,

File type 0 denotes a disk file, and 1 through 5 denote the TURBO Pas callogicalljO devices (CON:, KBD:, LST:, AUX:, and USR:). Bit 5 is set if the character buffer contains a pre-read character, bit 6 is set if output is allowed, and bit 7 is set if input is allowed.

220 TURBO Pascal Reference Manual Internal Data Formats

The four words from @ + 4 to @ + 11 store the offset address of the buffer, its size, the offset of the next character to read or write, and the offset of the first byte after the buffer. The buffer always resides in the same segment as the FIB, usually starting at @ + 76. When a textfile is assigned to a logical device, only the flags byte and the character buffer are used.

The file path is an ASCII string (a string terminated by a zero byte) of up to 63 characters.

Random Access Files

A random access file consists of a sequence of records, all of the same length and same internal format. To optimize file storage capacity, the records of a file are totally contiguous.

TURBO saves no information about the record length. The programmer must therefore see to it that a random access file is accessed with the correct record length.

The size returned by the standard function Filesize is obtained from the DOS directory.

Text Files

The basic components of a text file are characters, but a text file is furthermore divided into lines. Each line consists of any number of char acters ended by a CR/LF sequence (ASCII $00/ $OA). The file is ter minated by a Ctrl-Z (ASCII $1 B).

Parameters

Parameters are transferred to procedures and functions via the stack which is addressed through SS:SP.

On entry to an external subroutine, the top of the stack always contains the return address within the code segment (a word). The parameters, if any, are located below the return address, i.e. at higher addresses on the stack;

PC-DOS AND MS-DOS .. 221 Internal Data Formats

If an external function has the following subprogram header: function Magic(var R: Real; S: string5): Integer;

then the stack upon entry to Magic would have the following contents:

< Function result > < Segment base address of R > < Offset address of R > < First character of S >

< Last character of S > < Length of S > < Return address > SP

An external subroutine should save the Base Page register (BP) and then copy the Stack Pointer SP into the Base Page register in order to be able to refer to parameters. Furthermore the subroutine should reserve space on the stack for local workarea. This can be obtained by the following instructions: PUSH BP MOV BP,SP SUB SP,WORKAREA

The last instruction will have the effect of adding the following to the stack:

< Return address > BP < The saved BP register > < First byte of local workarea >

< Last byte of local work area > SP

Parameters are accessed via the BP register.

The following instruction will load the length of the string into the AL register:

MOV AL, [BP+4]

222 TURBO Pascal Reference Manual Internal Data Formats

Before executing a RET instruction the subprogram must reset the Stack Pointer and Base Page register to their original values. When exe cuting the RET the parameters may be removed by giving RET a param eter specifying how many bytes to remove. The following instructions should therefore be used when exiting from a subprogram: MOV SP,BP POP BP RET NoOfBytesToRemove

Variable Parameters

With a variable (var) parameter, two words are transferred on the stack giving the base address and offset of the first byte occupied by the actu al parameter.

Value Parameters

With value parameters, the data transferred on the stack depends upon the type of the parameter as described in the following sections.

Scalars

Integers, Booleans, Chars and declared scalars (Le. all scalars except Reals) are transferred on the stack as a word. If the variable occupies only one byte when it is stored, the most significant byte of the parame ter is zero.

Reals

A real is transferred on the stack using six bytes.

Strings

When a string is at the top of the stack, the topmost byte contains the length of the string followed by the characters of the string.

PC-DOS AND MS-DOS .. 223 Internal Data Formats

Sets

A set always occupies 32 bytes on the stack (set compression only ap plies to the loading and storing of sets).

Pointers

A pointer value is transferred on the stack as two words containing the base address and offset of a dynamic variable. The value NIL corresponds to two zero words.

Arrays and Records

Even when used as value parameters, Array and Record parameters are not actually transferred on the stack. Instead, two words containing the base address and offset of the first byte of the parameter are transferred. It is then the responsibility of the subroutine to use this in formation to make a local copy of the variable.

Function Results

User written external functions must remove all parameters and the function result from the stack when they return. Additionally, such functions must return their results exactly as specified in the following:

Values of scalar types, except Reals, must be returned in the AX regis ter. If the result is only one byte then AH should be set to zero. Boolean functions must return the function value by setting the Z flag (Z = False, NZ = True). If NZ = True, the AX register must be set to $01.

Reals must be returned on the stack with the exponent at the lowest address. This is done by not removing the function result variable when returning.

Sets must be returned on the top of the stack according to the format described above. On exit SP must point at the byte containing the string length.

Pointer values must be returned in DX:AX.

224 TURBO Pascal Reference Manual Internal Data Formats

The Heap and The Stacks

During execution of TURBO Pascal program the following segments are allocated for the program:

a Code Segment, a Data Segment, and a Stack Segment

Two stack-like structures are maintained during execution of a program: the heap and the stack.

The heap is used to store dynamic variables, and is controlled with the standard procedures New, Mark, and Release. At the beginning of a program, the heap pointer HeapPtr is set to low memory in the stack segment and the heap grows upwards towards the stack. The pre defined variable HeapPtr contains the value of the heap pointer and al lows the programmer to control the position of the heap.

The stack is used to store local variables, intermediate results during evaluation of expressions and to transfer parameters to procedures and functions. At the beginning of a program, the stack pOinter is set to the address of the top of the stack segment.

On each call to the procedure New and on entering a procedure or func tion, the system checks for collision between the heap and the recursion stack. If a collision has occurred, an execution error results, unless the K compiler directive is passive ({ $K-}).

PC-DOS AND MS-DOS .. 225 Memory Management

Memory Management

When a TURBO program is executed, three segments are allocated for the program: A code segment, a data segment, and a stack segment.

Code segment (CS is the code segment register): CCS:oooo CS: OOFF US-OOS base page CS:OIOO CS: End of run-time library Run-time library code CS: End of run-time lib. CS: End of program code Program code CS: End of program code CS: End of code segment Unused

Data segment (OS is the data segment register):

OS:OOOO OS:End of run-time library work space OS :End ofrun-time lib. work space OS :End of main program variables OS: End of main program vari abIes OS: End of data segment

The unused areas between (CS:EOFP-CS:EOFC and DS:EOFM DS:EOFD) are allocated only if a minimum cOde segment size larger than the required size is specified at compilation. The sizes of the code and data segments never exceed 64K bytes each.

The stack segment is slightly more complicated, as it may be larger than 64K bytes. On entry to the program the stack segment register (SS) and the stack pointer (SP) is loaded so that SS:SP pOints at the very last byte available in the entire segment. During execution of the program SS is never changed but SP may move downwards until it reaches the bottom of the segment, or 0 (corresponding to 64K bytes of stack) if the stack segment is larger than 64K bytes.

The heap grows from low memory in the stack segment towards the ac tual stack residing in high memory. Each time a variable is allocated on the heap, the heap pointer (which is a double word variable maintained by the TURBO run-time system) is moved upwards, and then normal ized, so that the offset address is always between $0000 and $OOOF. Therefore, the maximum size of a single variable that can be allocated on the heap is 65521 bytes (corresponding to $10000 less $OOOF). The total size of all variables allocated on the heap is however only limited by the amount of memory available. The heap pointer is available to the programmer through the HeapPtr standard identifier. HeapPtr is a type less pointer which is compatible with all pOinter types. Assignments to HeapPtr should be exercised only with extreme care.

226 TURBO Pascal Reference Manual Chapter 21 CP/M-86

This chapter describes features of TURBO Pascal specific to the CP/M-a6 implementation. The information presented on pages 227 through 240 will help you use Turbo Pascal efficiently. The remainder of the chapter will be of interest to experienced programmers; it describes such things as machine language routines, technical aspects of the compiler, etc.

Compiler Options

compile -> Memory Cmd-file cHn-file command line Parameter:

Find run-time error Quit

Figure 21-1: Options Menu

Memory / Cmd file / cHn-file

CP/M-86 227 Compiler Options

Cmd-file is selected by pressing C. The arrow moves to point to this line. The compiler writes code to a file with the same name as the Work file (or Main file, if specified) and the file type .CMD. This file contains the program code and Pascal runtime library, and may be activated by typ ing its name at the console.

cHain-file is selected by pressing H. The arrow moves to pOint to this line. The compiler writes code to a file with the same name as the Work file (or Main file, if specified) and the file type .CHN. This file contains the program code but no Pascal library and must be activated from another TURBO Pascal program with the Chain procedure (see page 231).

When the Cmd or cHn mode is selected, four additional lines will appear on the screen:

minimum cOde segment size: XXXX paragraphs (max.YYYY) minimum Data segment size: XXXX paragraphs (max.YYYY) mInimum free dynamic memory: XXXX paragraphs mAximum free dynamic memory: XXXX paragraphs

Figure 21-2: Memory Usage Menu

The use of these commands are described in the following sections.

Minimum Code Segment Size

The O-command is used to set the minimum size of the code segment for a .CMD using Chain or Execute. As discussed on page 231, Chain and Execute do not change the base addresses of the code, data, and stack segments, and a 'root' program using Chain or Execute must therefore allocate segments of sufficient size to accommodate the larg est segments in any Chained or Executed program.

228 TURBO Pascal Reference. Manual Compiler Options

Minimum Data Segment Size

The D-command is used to set the minimum size of the data segment for a .CMD using Chain or Execute. As discussed above, a 'root' program us ing these commands must allocate segments of sufficient size to accom modate the largest data of any Chained or Executed program.

Consequently, when compiling a 'root' program, you must set the value of the Minimum Data Segment Size to at least the same value as the largest data segment size of the programs to be chained/executed from that root. The required values are obtained from the status printout terminating any compilation. The values are in hexadecimal and specify the number of paragraphs, a paragraph being 16 bytes.

Minimum Free Dynamic Memory

This value specifies the minimum memory size required for stack and heap. The value is in hexadecimal and specifies a number of paragraphs, a paragraph being 16 bytes.

Maximum Free Dynamic Memory

This value specifies the maximum memory size allocated for stack and heap. It must be used in programs which operate in a multi-user environ ment like Concurrent CP /M-B6 to assure that the program does not allo cate the entire free memory. The value is in hexadecimal and specifies a number of paragraphs, a paragraph being 16 bytes.

Command Line Parameters

Find Runtime Error

When you run a program compiled in memory, and a runtime error occurs, the editor is invoked, and the error is automatically pointed out. This, of course, is not possible if the program is in a .CMD file or an .CHN file. Run time errors then print out the error code and the value of the program counter at the time of the error:

CP/M-86 229 Compiler Options

Run-time error 01, PC=lB56 Program aborted

Figure 21-3: Run-time Error Message

To find the place in the source text where the error occurred, enter the F command. When prompted for the address, enter the address given by the error message:

Enter PC: IB56

Figure 21-4: Find Run-time Error

The place in the source text is now found and pointed out exactly as if the error had occurred while running the program in memory.

Notice that locating errors in programs using overlays can be a bit more tricky, as explained on page 156.

Standard Identifiers

The following standard identifiers are unique to the 16-bit implementa tions:

Bdos Intr Ofs Seg CSeg MemW PortW SSeg DSeg

230 TURBO Pascal Reference Manual Chain and Execute

Chain and Execute

TURBO Pascal provides two procedures Chain and Execute which allow TURBO programs to activate other TURBO programs. The syntax of the pr~cedure calls are:

Chain(FilVar) Execute(FiIVar)

where FilVar is a file variable of any type, previously assigned to a disk file with the standard procedure Assign. If the file exists, it is loaded into memory and executed.

If the disk file does not exist, an I/O error occurs. This error is treated as described on page 116. When the I compiler directive is passive ({$I-}), program execution continues with the statement following the failed Chain or Execute statement, and the IOresult function must be called prior to further I/O.

Data can be transferred from the current program to the chained pro gram either by shared global variables or by absolute address variables.

To ensure overlapping, shared global variables should be declared as the very first variables in both programs, and they must be listed in the same order in both declarations. Furthermore, both programs must be compiled to the same size of code and data segments (see pages 228 and 229). When these conditions are satisfied, the variables will be placed at the same address in memory by both programs, and as TURBO Pascal does not automatically initialize its variables, they may be shared.

CP/M-86 231 Chain and Execute

Example: Program MAIN.CMD:

program Main; var Txt: string[80] ; CntPrg: file;

begin Write( 'Enter any text: '); Readln(Txt); Assign(CntPrg, 'ChrCount.chn'); Chain( CntPrg); end.

Program CHRCOUNT. CHN:

program ChrCount; var Txt: string[ 80] ; NoOfChar, NoOfUpc, I: Integer;

begin NoOfUpc := 0; NoOfChar := Length(Txt); for I := 1 to length(Txt) do it Txt[ I] in [, A' .. ' Z'] then NoOfUpc : = Succ(NoOfUpc) ; Write( 'No of characters in entry: ',NoOfChar); Writeln('. No of upper case characters: " NoOfUpc,'.'); end.

If you want a TURBO program to determine whether it was invoked by eXecute or directly from the CP/M command line, you should use an ab solute variable at address Dseg:$80. This is the command line length byte, and when a program is called from CP/M, it contains a value between 0 and 127. When eXecuting a program, therefore, the calling program should set this variable to something higher than 127. When you then check the variable in the called program, a value between 0 and 127 indicates that the program was called from CP/M, a higher value that it was called from another TURBO program.

232 TURBO Pascal Reference Manual Chain and Execute

It is important that the first program which executes a Chain statement allocates enough memory for the code, data, and stack segments to ac commodate largest .CHN program. This is done by using the Options menu to change the minimum code, data and free memory sizes (see page 190).

Note that neither Chain nor Execute can be used in direct mode, that is, from a program run with the compiler options switch in position Memory (page 190).

Overlays

During execution, the system normally expects to find its overlay files on the logged drive. The OvrDrive procedure may be used to change this default value.

OvrDrive Procedure

Syntax: OvrDrive(Drive};

where Drive is an integer expression specifying a drive (0 = logged drive, 1 = A:, 2 = B:, etc.). On subsequent calls to overlay files, the files will be expected on the specified drive. Once an overlay file has been opened on one drive, future calls to the same file will look on the same drive.

Example: program OvrTest; overlay procedure ProcA; begin Writeln( 'Overlay A'); end;

CP/M-86 233 Overlays

overlay procedure ProcB; begin Writeln( 'Overlay B'); end; procedure Dummy; begin {Dummy procedure to separate the overlays into two groups} end; overlay procedure Proce; begin Writeln( 'Overlay e'); end; begin OvrDrive(2) ; ProcA; OvrDrive(O) ; Proce; OvrDrive(2) ; ProcB; end.

The first call to OvrDrive specifies overlays to be sought on the B: drive. The call to ProcA therefore causes the first overlay file (containing the two overlay procedures ProcA and ProcB to be opened here.

Next, the OvrDrive(O) statement specifies that following overlays are to be found on the logged drive. The call to ProcC opens the second over lay file here.

The following ProcB statement calls an overlay procedure in the first overlay file; and to ensure that it is sought on the B: drive, the OvrDrive(2) statement must be executed before the call.

234 TURBO Pascal Reference Manual Files

Files File Names

A file name in CP/M consists of one through eight letters or digits, op tionally followed by a period and a file type of one through three letters or digits:

Drive:Name. Type

Text Files

The Seek and Flush procedures and the FilePos and FileSize functions are not applicable to CP/M text files.

Buffer Size

You are therefore given the option to specify the buffer size when de claring a text file:

VAR TextFile: Text[$lOOO];

declares a text file variable with a buffer size of 4K bytes.

CP/M-86 235 Absolute Variables

Absolute Variables

Variables may be declared to reside at specific memory addresses, and are then called absolute. This is done by adding to the variable declaration the reserved word absolute followed by two Integer constants spec ifying a segment and an offset at which the variable is to be located:

var Abc: Integer absolute $OOOO:$OOEE; Def: Integer absolute $OOOO:$OOFO;

Patch: array[l .. PatchSize] of byte absolute CSeg:$05F3;

Absolute may also be used to declare a variable "on top" of another variable, i.e. that a variable should start at the same address as another variable. When absolute is followed by the identifier of a variable or parameter, the new variable will start at the address of that variable parameter.

Example: var Str: string[ 32] ; StrLen: Byte absolute Str;

Further details on space allocation for variables are found on page 246.

236 TURBO Pascal Reference Manual Absolute Address Functions

Absolute Address Functions

The following functions are provided for obtaining information about pro gram variable addresses and system pointers.

Addr

Syntax: Addr(Name)

Returns the address in memory of the first byte of the variable with the identifier Name. If Name is an array, it may be subscribed, and if Name is a record, specific fields may be selected. The value returned is a 32 bit pOinter consisting of a segment address and an offset.

Dis

Syntax: Ofs( Name)

Seg

Syntax: Seg(Name)

Cseg

Syntax: Cseg

Returns the base address of the Code segment. The value returned is an Integer.

CP/M-86 237 Absolute Address Functions

Dseg

Syntax: Dseg

Returns the base address of the Data segment. The value returned is an Integer.

Sseg

Syntax: Sseg

Returns the base address of the Stack segment. The value returned is an Integer.

Predefined Arrays

TURBO Pascal offers four predefined arrays of type Byte, called Mem, MemW, Port and PortW which are used to access CPU memory and data ports.

MemArray

The predefined arrays Mem and MemWare used to access memory. Each component of the array Mem is a byte, and each component of the array MemW is a word (two bytes, LSB first). The index must be an address specified as the segment base address and an offset separated by a colon; both must be of type Integer.

The following statement assigns the value of the byte located in seg ment 0000 at offset $0081 to the variable Value Value:=Mem[OOOO:$0081];

While the following statement: MemW[Seg(Var):Ofs(Var)]:=Value;

places the value of the Integer variable Value in the memory location oc cupied by the two first bytes of the variable Var.

238 TURBO Pascal Reference Manual Predefined Arrays

Port Array

Example: Port[56] :=10;

With Statements

With statements may be nested to a maximum of 9 levels.

Pointer Related Items

MemAvail

The standard function MemAvail is available to determine the available space on the heap at any given time. The result is an Integer specifying the number of available paragraphs on the heap (a paragraph is 16 bytes).

Pointer Values

In very special circumstances it can be of interest to assign a specific value to a pointer variable without using another pointer variable or it can be of interest to obtain the actual value of a pointer variable.

CP/M-86 239 Pointer Related Items

Assigning a Value to a Pointer

The standard function Ptr can be used to assign specific values to a pointer variable. The function returns a 32 bit pOinter consisting of a segment address and an offset.

Example: Pointer:=Ptr(Cseg,$80);

Obtaining The Value of a Pointer

A pointer value is represented as a 32 bit entity and the standard func tion Ord can therefore not be used to obtain its value. Instead the func tions Ofs and Seg must be used.

The following statement obtains the value of the pointer P (which is a segment address and an offset):

A SegmentPart:=Seg(p ); A OffsetPart:=Ofs(P );

Function Calls

For the purpose of calling the CP/M-a6 BOOS, TURBO Pascal intro duces a procedure Bdos, which has a record as parameter.

Details on SODS and BIOS routines are found in the CP/M-86 Operat ing System Manual published by Digital Research.

The parameter to Bdos must be of the type: record AX,BX,CX,DX,BP,SI,DI,DS,ES,Flags: Integer; end;

Before TURBO calls the BOOS, the registers AX, BX, CX, OX, BP, SI, 01, OS, and ES are loaded with the values specified in the record param eter. When the BOOS has finished operation the Bdos procedure will re store the registers to the record thus making any results from the BOOS available.

240 TURBO Pascal Reference Manual User Written I/O Drivers

User Written I/O Drivers

function ConSt boolean; { 6 } function Con In: Char; { 6 } procedure ConOu~Ch: Char); { 6 } procedure LstOu~Ch: Char); { 5 } procedure AuxOu~Ch: Char); { 4 } function AuxIn: Char; { 3 } procedure UsrOu~Ch: Char); { 6 } function Usrln: Char; { 6 }

By default, these drivers are assigned to the BOOS functions as showed in curly braces in the above listing of drivers.

This, however, may be changed by the programmer by assigning the ad dress of a self-defined driver procedure or a driver function to one of the following standard variables:

Variable Contains the address of the

ConStPtr ConSt function ConlnPtr Con In function ConOutPtr ConOut procedure LstOutPtr LstOut procedure AuxOutPtr AuxOut procedure AuxlnPtr AuxIn function UsrOutPtr UsrOut procedure UsrlnPtr Usrln function

CP/M-86 241 User Written I/O Drivers

A user defined driver procedure or driver function must match the definitions given above, i.e. a CanSt driver must be a boolean function, a Conln driver must be a char function, etc.

External Subprograms

The reserved word external is used to declare external procedures and functions, typically procedures and functions written in machine code.

The reserved word external must be followed by a string constant specifying the name of a file in which executable machine code for the external procedure or function must reside.

During compilation of a program containing external functions or pro cedures the associated files are loaded and placed in the object' code. Since it is impossible to know beforehand exactly where in the· object code the external code will be placed this code must be relocatable, and no references must be made to the data segment. Furthermore the external code must save the registers BP, CS, DS and SS and restore these before executing the RET instruction.

The type of the filename is .CMD. Only the code segment of a .CMD file is loaded.

Example: procedure DiskReset; external 'DSKRESET'; function IOstatus: boolean; external 'IOSTAT';

Parameters may be passed to external subprograms, and the syntax is exactly the same as that of calls to ordinary procedures and functions:

procedure Plot(X,Y: Integer); external 'PLOT'; procedure QuickSort(var List: PartNo); external 'QS';

External subprograms and parameter passing is discussed further on page 252.

242 TURBO Pascal Reference Manual In-line Machine Code

In-line Machine Code

Example: inline (10/$2345/count+1/sort-*+2);

A code element will generate one byte of code if it consists of integer constants only, and if its value is within the 8-bit range (0 .. 255). If the value is outside the 8-bit range, or if the code element refers to variable, procedure, or function identifiers, or if the code element contains a loca tion counter reference, one word of code is generated (least significant byte first).

The · <' and · >' characters may be used to override the automatic size selection described above. If a code element starts with a · < ' character, only the least significant byte of the value is coded, even if it is a 16-bit value. If a code element starts with a'> ' character, a word is always coded, even though the most significant byte is zero.

Example: inline «$1234/>$44);

This inline statement generates three bytes of code: $34, $44, $00.

CP/M-86 243 In-line Machine Code

The value of a variable identifier use in a inline statement is the offset address of the variable within its base segment. The base segment of global variables (Le. variables declared in the main program block) is the data segment, which is accessible through the DS register. The base segment of local variables (Le. variables declared within the current sub program) is the stack segment, and in this case the variable offset is re lative to the BP (base page) register, the use of which automatically causes the stack segment to be selected. The base segment of typed constants is the code segment, which is accessible through the CS re gister. inline statements should not attempt to access variables that are not declared in the main program nor in the current subprogram.

The following example of an inline statement generates machine code that will convert all characters in its string argument to upper case.

procedure UpperCase(var Strg: Str) ; {Str is type String[255]} begin inline ($C4/$BE/Strgl { LES OI,Strg[BP] $26/$8A/$001 { MOV CL,ES: [01] $FE/$C11 { INC CL $FE/$C91 { L1: DEC CL $74/$131 { JZ L2 $471 { INC 01 $26/$801$30/$611 { CMP ES:BYTE PTR [01], 'a'} $72/$F51 { JB L1 } $26/$801$30/$7AI { CMP ES:BYTE PTR [01] , 'z'} $77/$EFI { JA L1 } $26/$801$20/$201 { SUB ES:BYTE PTR [OI],20H} $EB/$E9) ; { JMP SHORT L1 } { L2: } end;

Inline statements may be freely mixed with other statements throughout the statement part of a block, and inline statements may use all CPU registers. Note, however, that the contents of the registers BP, SP, DS, and SS must be the same on exit as on entry.

244 TURBO Pascal Reference Manual Interrupt Handling

Interrupt Handling

A TURBO Pascal interrupt routine must manually preserve registers AX, BX, CX, OX, SI, 01, OS and ES. This is done by placing the following in line statement as the first statement of the procedure:

inline ($501$53/$51/$52/$56/$57/$lE/$06/$FB);

The last byte ($FB) is an STI instruction which enables further interrupts - it mayor may not be required. The following in line statement must be the last statement in the procedure:

inline ($07/$lF/$5F/$5E/$5A/$59/$5B/$58/$8B/$E5/$5D/$CF);

This restores the registers and reloads the stack pointer (SP) and the base page register (BP). The last byte ($CF) is an IRET instruction which overrides the RET instruction generated by the compiler.

Note that the data segment register OS, used to access global variables, will not have the correct value when the interrupt service routine is en tered. Therefore, global variables cannot be directly accessed. Typed constants, however, are available, as they are stored in the code seg ment. The way to access global variables in the interrupt service routine is therefore to store the value of Dseg in a typed constant in the main program. This typed constant can then be accessed by the interrupt handler and used to set its OS register.

Intr procedure

Syntax: Intr(lnterruptNo, Result)

This procedure initializes the registers and flags as specified in the parameter Result which must be of type:

Result = record AX,BX,CX,DX,BP,SI,DI,DS,ES,Flags: Integer; end;

CPjM-86 245 Interrupt Handling

It then makes the software interrupt given by the parameter interruptNo which must be an Integer constant. When the interrupt service routine returns control to your program, Result will contain any values returned from the service routine.

Internal Data Formats

Global and local variables, and typed constants occupy different seg ments as follows:

Global variables reside in the data segment and the offset is relative to the OS register.

Local variables reside in the stack segment and the offset is relative to the BP register.

Typed constants reside in the code segment and the offset is relative to the CS register.

All variables are contained within their base segment.

Basic Data Types

The basic data types may be grouped into structures (arrays, records, and disk files), but this structuring will not affect their internal formats.

246 TURBO Pascal Reference Manual Internal Data Formats

Scalars

Rea/s

@ Exponent @+1 LSB of mantissa

@+5 MSB of mantissa

CP/M-86 247 Internal Data Formats

Strings

A string occupies as many bytes as its maximum length plus one. The first byte contains the current length of the string. The following bytes contains the string with the first character stored at the lowest address. In the table shown below, L denotes the current length of the string, and Max denotes the maximum length:

@ Current length (L) @+1 First character @+2 Second character

@+L Last character @+L+1 Unused

@+Max Unused

Sets

An element in a Set occupies one bit, and as the maximum number of elements in a set is 256, a set variable will never occupy more than 32 bytes (256/8).

If a set contains less than 256 elements, some of the bits are bound to be zero at all times and need therefore not be stored. In terms of memory efficiency, the best way to store a set variable of a given type would then be to "cut off" all insignificant bits, and rotate the remaining bits so that the first element of the set would occupy the first bit of the first byte. Such rotate operations, however, are quite slow, and TURBO therefore employs a compromise: Only bytes which are statically zero (Le. bytes of which no bits are used) are not stored. This method of compression is very fast and in most cases as memory efficient as the rotation method.

MemAddress = @ + (E div 8) - (Min div 8)

and the bit address within the byte at MemAddress is:

248 TURBO Pascal Reference Manual Internal Data Formats

BitAddress = E mod 8

where E denotes the ordinal value of the element.

Pointers

A pOinter consists of four bytes containing a segment base address and an offset. The two least significant bytes contains the offset and the two most significant bytes the base address. Both are stored in memory us ing byte reversed format, i.e. the least significant byte is stored first. The value nil corresponds to two zero words.

Data Structures

Arrays

The components with the lowest index values are stored at the lowest memory address. A mUlti-dimensional array is stpred with the rightmost dimension increasing first, e.g. given the array

Board: array[l .. 8,1 .. 8] of Square

you have the following memory layout of its components:

lowest address: Board[l,l] Board[1,2]

Board[1,8] Board[2,1] Board[2,2]

Highest address: Board[8,8]

CP/M-86 249 Internal Data Formats

Records

Disk Files

Disk files are different from other data structures in that data is not stored in internal memory but in a file on an external device. A disk file is controlled through a file interface block (FIB).

File Interface Blocks

The table below shows the format of a FIB:

@+O Flags byte. @+1 Character buffer. @+2 Number of records (LSB) or buffer offset (LSB). @+3 Number of records (MSB) or buffer offset (MSB). @+4 Record length (LSB) or buffer size (LSB). @+5 Record length (MSB) or buffer size (MSB). @+6 Buffer pointer (LSB). @+7 Buffer pointer (MSB). @+8 Current record (LSB) or buffer end (LSB). @+9 Current record (MSB) or buffer end (LSB). @+10 Unused. @+11 Unused. @+12 First byte of CP 1M FCB.

@+47 Last byte of CP/M FCB. @+48 First byte of sector buffer.

@+175 Last byte of sector buffer.

250 TURBO Pascal Reference Manual Internal Data Formats

sector 0, byte 0: Number of records (LSB) sector 0, byte 1: Number of records (MSB) sector 0, byte 2: Record length (LSB) sector 0, byte 3: Record length (MSB)

Text Files

Parameters

Parameters are transferred to procedures and functions via the stack which is addressed through SS:SP.

If an external function has the following subprogram header: ftDKrtian Magic(var R: Real; S: string5): Integer;

then the stack upon entry to Magic would have the following contents:

< Function result > < Segment base address of R > < Offset address of R > < First character of S >

< Last character of·S > < Length of S > < Return address > SP

252 TURBO Pascal Reference Manual Internal Data Formats

The format of the flags byte at @ + 0 is:

Bit 0 .. 3 File type. Bit 4 Read semaphore. Bit 5 Write semaphore or pre-read character flag. Bit 6 Output flag. Bit 7 Input flag.

File type 0 denotes a disk file, and 1 through 5 denote the TURBO Pas cal logical I/O devices (CON:, KBD:, LST:, AUX:, and USR:). For typed files, bit 4 is set if the contents of the sector buffer is undefined, and bit 5 is set if data has been written to the sector buffer. For textfiles, bit 5 is set if the character buffer contains a pre-read character. Bit 6 is set if output is allowed, and bit 7 is set if input is allowed.

For typed and untyped files, the four words from @ + 2 to @ + 9 store the number of records in the file, the record length in bytes, the sector buffer pOinter, and the current record number. For typed files, the sector buffer pointer stores an offset (0 .. 127) in the sector buffer at @ + 48. The FIB of an untyped file has no sector buffer, and so the sector buffer pointer is not used.

For text files, the four words from @ + 2 to @ + 9 store the offset ad dress of the buffer, its size, the offset of the next character to read or write, and the offset of the first byte after the buffer. The buffer always resides in the same segment as the FIB, usually starting at @ + 48. The size of a textfile FIB may be larger than indicated, depending on the size of the buffer. When a textfile is assigned to a logical device, only the flags byte and the character buffer are used.

Random Access Files

A random access file consists of a sequence of records, all of the same length and same internal format. To optimize file storage capacity, the records of a file are totally contiguous. The first four bytes of the first sector of a file contains the number of records in the file and the length of each record in bytes. The first record of the file is stored starting at the fourth byte.

CP/M-86 251 Internal Data Formats

PUSH BP MOV BP,SP SUB SP,WORKAREA

The last instruction will have the effect of adding the following to the stack:

< Return address > BP < The saved BP register > < First byte of local workarea >

< Last byte of local work area > SP

Parameters are accessed via the BP register.

The following instruction will load length of the string into the AL regis ter:

MOV AL, [BP+4]

MOV SP,BP POP BP RET NoOfBytesToRemove

Variable Parameters

With a variable (var) parameter, two words are transferred on the stack giving the base address and offset of the first byte occupied by the actu al parameter.

Value Parameters

With value parameters, the data transferred on the stack depends upon the type of the parameter as described in the following sections.

CP/M-86 253 Internal Data Formats

Scalars

Reals

A real is transferred on the stack using six bytes.

Strings

When a string is at the top of the stack, the topmost byte contains the length of the string followed by the characters of the string.

Sets

A set always occupies 32 bytes on the stack (set compression only ap plies to the loading and storing of sets).

Pointers

A pointer value is transferred on the stack as two words containing the base address and offset of a dynamic variable. The value NIL cor responds to two zero words.

Arrays and Records

254 TURBO Pascal Reference Manual Internal Data Formats

Function Results

User written external functions must remove all parameters and the function result from the stack when they return.

User written external functions must return their results exactly as specified in the following:

Reals must be returned on the stack with the exponent at the lowest address. This is done by not removing the function result variable when returning.

Sets must be returned on the top of the stack according to the format described on page 254. On exit SP must point at the byte containing the string length.

Pointer values must be returned in the DX:AX.

The Heap and The Stacks

During execution of TURBO Pascal program the following segments are allocated for the program:

a Code Segment, a Data Segment, and a Stack Segment

Two stack-like structures are maintained during execution of a program: the heap and the stack.

CP/M-86 255 Internal Data Formats

The stack is used to store local variables, intermediate results during evaluation of expressions and to transfer parameters to procedures and functions. At the beginning of a program, the stack pointer is set to the address of the top of the stack segment.

Memory Management

When a TURBO program is executed, three segments are allocated for the program: A code segment, a data segment, and a stack segment.

Code segment (CS is the code segment register): CS:OOOO - CS:EOFR Run-time library code. CS:EOFR - CS:EOFP Program code. CS:EOFP - CS:EOFC Unused.

Data segment (DS is the data segment register): DS:OOOO - DS:OOFF CP/M-86 base page. DS:OlOO - DS:EOFW Run-time library workspace. DS:EOFW - DS:EOFM Main program block variables. DS:EOFM - DS:EOFD Unused.

The unused areas between (CS:EOFP-CS:EOFC and DS:EOFM DS:EOFD) are allocated only if a minimum cOde segment size larger than the required size is specified at compilat'on. The sizes of the code and data segments never exceed 64K bytes eacrl.

The stack segment is slightly more complicated, as it may be larger than 64K bytes. On entry to the program the atack segment register (SS) and the stack pointer (SP) is loaded so that SS:SP points at the very last byte available in the entire segment. During execution of the program SS is never changed but SP may move downwards until it reaches the bottom of the segment, or 0 (corresponding to 64K bytes of stack) if the stack segment is larger than 64K bytes.

256 TURBO Pascal Reference Manual Memory Management

The heap pointer is available to the programmer through the HeapPtr standard identifier. HeapPtr is a typeless pointer which is compatible with all pointer types. Assignments to HeapPtr should be exercised only with extreme care.

CP/M-86 257 Memory Management

Notes:

258 TURBO Pascal Reference Manual Chapter 22 CP/M-80

This chapter describes features of TURBO Pascal specific to the 8-bit CP/M-80 implementation. It presents two kinds of information:

1) Things you should know to make efficient use of TURBO Pascal. Pages 259 through 272.

2) The rest of the chapter describes things which are only of interest to ex perienced programmers, such as machine language routines, technical aspects of the compiler, etc. eXecute Command

You will find an additional command on the main TURBO menu in the CP/M-80 version: eXecute. It lets you run other programs from within TURBO Pascal, for example copying programs, word processors - in fact anything that you can run from your operating system. When enter ing X, you are prompted:

Command: -

You may now enter the name of any program which will then load and run normally. Upon exit from the program, control is re-transferred to TURBO Pascal, and you return to the TURBO prompt> (command line parameters are allowed). compiler Options

The 0 command selects the following menu on which you may view and change some default values of the compiler. It also provides a helpful function to find runtime errors in programs compiled into object code files.

CP/M-8D 259 compiler Options

compile -> Memory Com-file cHn-file

Find run-time error Quit

Figure 22-1: Options Menu

Memory / Com file / cHn-file

The three commands M, C, and H select the compiler mode, i.e. where to put the code which results from the compilation.

Memory is the default mode. When active, code is produced in memory and resides there ready to be activated by a Run command.

Com-file is selected by pressing C. The arrow moves to point to this line. When active, code is written to a file with the same name as the Work file (or Main file, if specified) and the file type .COM. This file contains the program code and Pascal runtime library, and may be activated by typing its name at the console. Programs compiled this way may be larger than programs compiled in memory, as the program code itself does not take up memory during compilation, and as program code starts at a lower address.

cHain-file is selected by pressing H. The arrow moves to point to this line. When active, code is written to a file with the same name as the Work file (or Main file, if specified) and the file type .CHN. This file con tains the program code but no Pascal library and must be activated from ~nother TURBO Pascal program with the Chain procedure (see page 263).

When Com or cHn mode is selected, the menu is expanded with the fol lowing two lines:

260 TURBO Pascal Reference Manual compiler Options

Start address: XXXX (min YYYY) End address: XXXX (max YYYY)

Figure 22-2: Start and End Addresses Start Address

The Start address specifies the address (in hexadecimal) of the first byte of the code. This is normally the end address of the Pascal library plus one, but may be changed to a higher address if you want to set space aside e.g. for absolute variables to be shared by a series of chained pro grams.

When you enter an S, you are prompted to enter a new Start address. If you just hit < RETURN> , the minimum value is assumed. Don't set the Start address to anything less than the minimum value, as the code will then overwrite part of the Pascal library.

End Address

The End address specifies the highest address available to the program (in hexadecimal). The value in parentheses indicate the top of the TPA on your computer, i.e. BOOS minus one. The default setting is 700 to 1000 bytes less to allow space for the loader which resides just below BOOS when executing programs from TURBO.

If compiled programs are to run in a different environment, the End ad dress may be changed to suit the TPA size of that system. If you antici pate your programs to run on a range of different computers, it will be wise to set this value relatively low, e.g. C100 (48K), or even A 100 (40K) if the program is to run under MP/M.

CP/M-8o 261 compiler Options

When you enter an E, you are prompted to enter a End address. If you just hit < RETURN> , the default value is assumed (Le. top of TPA less 700 to 1000 bytes). If you set the End address higher than this, the resulting programs cannot be executed from TURBO, as they will overwrite the TURBO loader; and if you set it higher than the TPA top, the resulting pro grams will overwrite part of BOOS if run on your machine.

Find Runtime Error

When you run a program compiled in memory, and a runtime error occurs, the editor is invoked, and the error is automatically pointed out. This, of course, is not possible if the program is in a .COM file or an .CHN file. Run time errors then print out the error code and the value of the program counter at the time of the error, e.g.:

Run-time error 01, PC=lB56 Program aborted

Figure 22-3: Run-time Error Message

To find the place in the source text where the error occurred, enter the F command on the Options menu. When prompted for the address, enter the address given by the error message:

I Enter pc: 1B56

Figure 22-4: Find Run-time Error

The place in the source text is now found and pointed out exactly as if the error had occurred while running the program in memory.

262 TURBO Pascal Reference Manual Standard Identifiers

Standard Identifiers

The following standard identifiers are unique to the CP /M-80 implemen tation:

Bios Bdos RecurPtr BiosHL BdosHL StackPtr

Chain and Execute

TURBO Pascal provides two standard procedures: Chain and Execute which allow you to activate other programs from a TURBO program. The syntax of these procedure calls is:

Chain(FilVar) Execute(FilVar)

where FilVar is a file variable of any type, previously assigned to a disk file with the standard procedure Assign. If the file exists, it is loaded into memory and executed.

The Chain procedure is used only to activate special TURBO Pascal .CHN files, i.e. files compiled with the cHn-file option selected on the Options menu (see page 260). Such a file contains only program code; no Pascal library. It is loaded into memory and executed at the start ad dress of the current program, i.e. the address specified when the current program was compiled. It then uses the Pascal library already present in memory. Thus, the current program and the chained program must use the same start address.

The Execute procedure is used to execute any .COM file that was created using Turbo Pascal (see page 260). The file is loaded and executed at address $100, as specified by the CP/M standard.

If the disk file does not exist, an I/O error occurs. This error is treated as described on page 116. If the I compiler, directive is passive ({ $I-}), pro gram execution continues with the statement following the failed Chain or Execute statement, and the IOresult function must be called prior to further I/O.

CP/M-BO 263 Chain and Execute

Data can be transferred from the current program to the chained pro gram either by shared global variables or by absolute address variables.

To ensure overlapping, shared global variables should be declared as the very first variables in both programs, and they must be listed in the same order in both declarations. Furthermore, both programs must be compiled to the same memory size (see page 261). When these condi tions are satisfied, the variables will be placed at the same address in memory by both programs, and as TURBO Pascal does not automatical ly initialize its variables, they may be shared.

Example: Program MAIN.COM:

program Main; var Txt: string[ 80] ; CntPrg: file; begin Write( 'Enter any text: '); Readln(Txt); Assign(CntPrg, 'ChrCount.chn'); Chain(CntPrg); end.

Program CHRCOUNT.CHN:

program ChrCount; var Txt: string[ 80] ; NoOfChar, NoOfUpc, I: Integer; begin NoOfUpc := 0; NoOfChar := Length(Txt); for I := 1 to length(Txt) do if Txt[I] in ['A' .. 'Z'] then NoOfUpc := Succ(NoOfUpc); Write( 'No of characters in entry: ',NoOfChar); Writeln('. No of upper case characters: " NoOfUpc,'.'); end.

264 TURBO Pascal Reference Manual Chain and Execute

If you want a TURBO program to determine whether it was invoked by eXecute or directly from the DOS command line, you should use an ab solute variable at address $80. This is the command line length byte, and when a program is called from CP/M, it contains a value between 0 and 127. When eXecuting a program, therefore, the calling program should set this variable to something higher than 127. When you then check the variable in the called program, a value between 0 and 127 in dicates that the program was called from CP/M, a higher value that it was called from another TURBO program.

Note that neither Chain nor Execute can be used in direct mode, i.e. from a program run with the compiler options switch in position Memory (page 260).

Overlays

During execution, the system normally expects to find its overlay files on the logged drive. The OvrDrive procedure may be used to change this default value.

OvrDrive Procedure

Syntax: OvrDrive(Drive}

Example: program OvrTest; overlay procedure ProcA; begin Writeln( 'Overlay A'); end; overlay procedure ProcB; begin Writeln('Overlay B'); end;

CP/M-8D 265 Overlays

procedure Dummy; begin {Dummy procedure to separate the overlays into two groups} end; overlay procedure ProcC; begin Writeln('Overlay C'); end; begin OvrDrive(2) ; ProcA; OvrDrive(O) ; ProcC; OvrDrive(2) ; ProcB; end.

Next, the OvrDrive(O) statement specifies that following overlays are to be found on the logged drive. The call to ProcC opens the second over lay file here.

The following ProcB statement calls an overlay procedure in the first overlay file; and to ensure that it is sought on the B: drive, the OvrDrive(2) statement must be executed before the call.

266 TURBO Pascal Reference Manual Files

Files File Names

A file name in CP/M consists of one through eight letters or digits, op tionally followed by a period and a file type of one through three letters or digits:

Drive: Name. Type

Text Files

The Seek and Flush procedures and the FilePos and FileSize functions are not applicable to CP/M text files.

Absolute Variables

Variables may be declared to reside at specific memory addresses, and are then called absolute. This is done by adding the reserved word ab solute and an address expressed by an integer constant to the variable declaration.

Example: var IObyte: Byte absolute $0003; CmdLine: string[127] absolute $80;

Absolute may also be used to declare a variable "on top" of another variable, i.e. that a variable should start at the same address as another variable. When absolute is followed by the variable (or parameter) identifier, the new variable will start at the address of that variable (or parameter).

Example: var Str: string[32]; StrLen: Byte absolute Str;

The above declaration specifies that the variable StrLen should start at the same address as the variable Str, and since the first byte of a string variable gives the length of the string, StrLen will contain the length of Str. Notice that only one identifier may be specified in an absolute de claration, i.e. the construct:

CP/M-BO 267 Absolute Variables

Identl, Ident2: Integer absolute $8000

is illegal. Further details on space allocation for variables are given on pages 278 and 288.

Addr

Syntax: Addr(name);

Returns the address in memory of the first byte of the type, variable, procedure, or function with the identifier name. If name is an array, it may be subscribed, and if name is a record, specific fields may be selected. The value returned is-of type Integer.

Predefined Arrays

TURBO Pascal offers two predefined arrays of type Byte, called Mem and Port, which are used to directly access CPU memory and data ports.

MemArray

The predeclared array Mem is used to access memory. Each com ponent of the array is a Byte, and indexes correspond to addresses in memory. The index type is Integer. When a value is assigned to a com ponent of Mem, it is stored at the address given by the index expres sion. When the Mem array is used in an expression, the byte at the ad dress specified by the index is used.

Examples: Mern[WsCursor] := 2; Mern[WsCursor+l] := $IB; Mern[WsCursor+2] := Ord(' '); IObyte := Mern[3]; Mern[Addr+Offset] := Mern[Addr];

268 TURBO Pascal Reference Manual Predefined Arrays

Port Array

The Port array is used to access the data ports of the Z80 CPU. Each element of the array represents a data port with indexes corresponding to port numbers. As data ports are selected by 8-bit addresses, the in dex type is Byte. When a value is assigned to a component of Port, it is output to the port specified. When a component of Port is referenced in an expression, its value is input from the port specified.

The use of the port array is restricted to assignment and reference in expressions only, i.e. components of Port cannot function as variable parameters to procedures and functions. Furthermore, operations refer ring to the entire Port array (reference without index) are not allowed.

Array Subscript Optimization

The X compiler directive allows the programmer to select whether array subscription should be optimized with regard to execution speed or to code size. The default mode is active, i.e. ( $X +}, which causes execu tion speed optimization. When passive, i.e. ( $X-}, the code size is minimized.

With Statements

The default 'depth' of nesting of With statements is 2, but the W direc tive may be used to change this value to between 0 and 9. For each block, With statements require two bytes of storage for each nesting level allowed. Keeping the nesting to a minimum may thus greatly affect the size of the data area in programs with many subprograms.

CP/M-80 269 Pointer Related Items

Pointer Related Items

MemAvaii

The standard function MemA vail is available to determine the available space on the heap at any given time. The result is an Integer, and if more than 32767 bytes is available, MemAvail returns a negative number. The correct number of free bytes is then calculated as 65536.0 + MemA vail. Notice the use of a real constant to generate a Real result, as the result is greater than Maxlnt. Memory management is discussed in further detail on page 288.

Pointers and Integers

The standard functions Ord and Ptr provide direct control of the address contained in a pointer. Ord returns the address contained in its pointer argument as an Integer, and Ptr converts its Integer argument into a pOinter which is compatible with all pOinter types.

These functions are extremely valuable in the hands of an experienced programmer as they allow a pointer to point to anywhere in memory. If used carelessly, however, they are very dangerous, as a dynamic vari able may be made to overwrite other variables, or even program code.

270 TURBO Pascal Reference Manual CP/M Function Calls

CP 1M Function Calls

For the purpose of calling CP/M BOOS and BIOS routines, TURBO Pas cal introduces two standard procedures: Bdos and Bios, and four stan dard functions: Bdos, BdosHL, Bios, and BiosHL.

Details on BOOS and BIOS routines are found in the CP/M Operating System Manual published by Digital Research.

8dos procedure and function

Syntax: Bdos(Func {, Param } );

The Bdos procedure is used to invoke CP/M BOOS routines. Func and Param are integer expressions. Func denotes the number of the called routine and is loaded into the C register. Param is optional and denotes a parameter which is loaded into the DE register pair. A call to address 5 then invokes the BOOS.

The Bdos function is called like the procedure and returns an Integer result which is the value returned by the BOOS in the A register.

8dosHL function

Syntax: BdosHL(Func {, Param } );

This function is exactly similar to the Bdos function above, except that the result is the value returned in the HL register pair.

CP/M-BO 271 CP1M Function Calls

Bios procedure and function

Syntax: Bios(Func {, Param } );

The Bios procedure is used to invoke BIOS routines. Func and Param are integer expressions. Func denotes the number of the called routine, with 0 meaning the WBOOT routine, 1 the CONST routine, etc. /.e. the address of the called routine is Func * 3 plus the WBOOT address con tained in addresses 1 and 2. Param is optional and denotes a parameter which is loaded into the BC register pair prior to the call.

The Bios function is called like the procedure and returns an integer result which is the value returned by the BIOS in the A register.

BiosHL function

Syntax: BiosHL(Func {, Param} );

This function is exactly similar to the Bios function above, except that the result is the value returned in the HL register pair.

User Written 1/0 Drivers

For some applications it is practical for a programmer to define his own input and output drivers, i.e. routines which perform input and output of characters to and from external devices. The following drivers are part of the TURBO environment, and used by the standard I/O drivers (although they are not available as standard procedures or functions):

function CanSt boolean; function Conln: Char; procedure ConOut (Ch: Char); procedure LstOut (Ch: Char); procedure AuxOut (Ch: Char); function AuxIn: Char; procedure UsrOut (Ch: Char); function Usrln: Char;

272 TURBO Pascal Reference Manual User Written I/O Drivers

The ConSt routine is called by the function KeyPressed, the Con In and ConOut routines are used by the CON:, TRM:, and KBD: devices, the LstOut routine is used by the LST: device, the AuxOut and AuxIn rou tines are used by the AUX: device, and the UsrOut and Usrln routines are used by the USA: device.

By default, these drivers use the corresponding BIOS entry points of the CP/M operating system, i.e. ConSt uses CONST, Conln uses CONIN, ConOut uses CONOUT, LstOut uses LIST, AuxOut uses PUNCH, AuxIn uses READER, UsrOut uses CONOUT, and Usrln uses CONIN. This, however, may be changed by the programmer by assigning the address of a self-defined driver procedure or a driver function to one of the fol lowing standard variables:

Variable Contains the address of the

A user defined driver procedure or driver function must match the definitions given above, i.e. a ConSt driver must be a Boolean function, a Conln driver must be a Char function, etc.

CP/M-80 273 External Subprograms

External Subprograms

The reserved word external is used to declare external procedures and functions, typically procedures and functions written in machine code.

An external subprogram has no block, i.e. no declaration part and no statement part. Only the subprogram heading is specified, immediately followed by the reserved word external and an integer constant defining the memory address of the subprogram:

procedure OiskReset; external $ECOO; function IOstatus: boolean; external $0123

Parameters may be passed to external subprograms, and the syntax is exactly the same as that of calls to ordinary procedures and functions:

procedure Plot(X,Y: Integer); external $F003; procedure QUickSort(var List: PartNo); external $lCOO;

Parameter passing to external subprograms is discussed further on page 283.

In-line Machine Code

Example: inline (lOI$2345/count+l/sort-*+2);

274 TURBO Pascal Reference Manual In-line Machine Code

The I <' and I >' characters may be used to override the automatic

size selection described above. If a code element starts with a I < I character, only the least significant byte of the value is coded, even if it

is a 16-bit value. If a code element starts with a I > ' character, a word is always coded, even though the most significant byte is zero.

Example: inline «$1234/>$44);

This inline statement generates three bytes of code: $34, $44, $00.

The following example of an inline statement generates machine code that will convert all characters in its string argument to upper case.

CP/M-8o 275 In-line Machine Code

procedure UpperCase(var Strg: Str); {Str is type String[255]} {$A+} begin inline ($2A/Strgl { LO HL, (Strg) } $461 { LO B, (HL) } $041 { INC B } $051 { Ll: DEC B } $CA/*+201 { JP Z,L2 } $231 { INC HL } $7EI { LO A, (HL) } $FE/$611 { CP , a' } $OA/*-91 { JP C,Ll } $FE/$7BI { CP 'z'+l } $02/*-141 { JP NC,Ll } $06/$201 { SUB 20H } $771 { LO (HL),A } $C3/*-20); { JP Ll } { L2: EQU $ } end;

In line statements may be freely mixed with other statements throughout the statement part of a block, and inline statements may use all CPU registers. Note, however, that the contents of the stack pointer register (SP) must be the same on exit as on entry.

276 TURBO Pascal Reference Manual Interrupt Handling

Interrupt Handling

The TURBO Pascal run time package and the code generated by the compiler are both fully interruptable. Interrupt service routines must preserve all registers used.

If required, interrupt service procedures may be written in Pascal. Such procedures should always be compiled with the A compiler directive ac tive ({$A +}), they must not have parameters, and they must them selves insure that all registers used are preserved. This is done by plac ing an inline statement with the necessary PUSH instructions at the very beginning of the procedure, and another inline statement with the corresponding POP instructions at the very end of the procedure. The last instruction of the ending inline statement should be an EI instruction ($FB) to enable further interrupts. If daisy chained interrupts are used, the inline statement may also specify a RETI instruction ($EO, $40), which will override the RET instruction generated by the compiler.

The general rules for register usage are that integer operations use only the AF, BC, OE, and HL registers, other operations may use IX and IY, and real operations use the alternate registers.

An interrupt service procedure should not employ any 1/0 operations us ing the standard procedures and functions of TURBO Pascal, as these routines are not re-entrant. Also note that BOOS calls (and in some in stances BIOS calls, depending on the specific CPIM implementation) should not be performed from interrupt handlers, as these routines are not re-entrant.

The programmer may disable and enable interrupts throughout a pro gram using 01 and EI instructions generated by inline statements.

If mode 0 (1M 0) or mode 1 (1M 1) interrupts are employed, it is the responsibility of the programmer to initialize the restart locations in the base page (note that RST 0 cannot be used, as CP/M uses locations 0 through 7).

If mode 2 (1M 2) interrupts are employed, the programmer should gen erate an initialized jump table (an array of integers) at an absolute address, and initialize the I register through a inline statement at the beginning of the program.

CP/M-BO 277 Internal Data Formats

Internal Data Formats

In the following descriptions, the symbol @ denotes the address of the first byte occupied by a variable of the given type. The standard function Addr may be used to obtain this value for any variable.

Basic Data Types

The basic data types may be grouped into structures (arrays, records, and disk files), but this structuring will not affect their internal formats.

Scalars

The following scalars are all stored in a single byte: Integer subranges with both bounds in the range O.. 255, Booleans, Chars, and declared scalars with less than 256 possible values. This byte contains the ordinal value of the variable.

The following scalars are all stored in two bytes: Integers, Integer subranges with one or both bounds not within the range O.. 255, and de clared scalars with more than 256 possible values. These bytes contain a 2's complement 16-bit value with the least significant byte stored first.

Reals

@ Exponent @ +1 LSB of mantissa

@ +5 MSB of mantissa

The exponent uses binary format with an offset of $80. Hence, an ex ponent of $84 indicates that the value of the mantissa is to be multiplied by 2 A($84-$80) = 2 A4 = 16. If the exponent is zero, the floating pOint value is considered to be zero.

278 TURBO Pascal Reference Manual Internal Data Formats

The value of the mantissa is obtained by dividing the 40-bit unsigned in teger by 2 A40. The mantissa is always normalized, Le. the most significant bit (bit 7 of the fifth byte) should be interpreted as a 1. The sign of the mantissa is stored in this bit, a 1 indicating that the number is negative, and a 0 indicating that the number is positive.

Strings

A string occupies the number of bytes corresponding to one plus the maximum length of the string. The first byte contains the current length of the string. The following bytes contain the actual characters, with the first character stored at the lowest address. In the table shown below, L denotes the current length of the string, and Max denotes the maximum length:

@ Current length (L) @ +1 First character @ +2 Second character

@ +L Last character @ +L+1 Unused

@ + Max Unused

Sets

An element in a set occupies one bit, and as the maximum number of elements in a set is 256, a set variable will never occupy more than 32 bytes (256/8).

If a set contains less than 256 elements, some of the bits are bound to be zero at all times and need therefore not be stored. In terms of memory efficiency, the best way to store a set variable of a given type would then be to "cut off" all insignificant bits, and rotate the remaining bits so that the first element of the set would occupy the first bit of the first byte. Such rotate operations, however, are quite slow, and TURBO therefore employs a compromise: Only bytes which are statically zero (Le. bytes of which no bits are used) are not stored. This method of compression is very fast and in most cases as memory efficient as the rotation method.

CP/M-80 279 Internal Data Formats

MemAddress = @ + (E div 8) - (Min div 8)

and the bit address within the byte at MemAddress is:

BitAddress = E mod 8

where E denotes the ordinal value of the element.

File Interface Blocks

The table below shows the format of a FIB in TURBO Pascal-80:

@+O Flags byte. @+1 Character buffer. @+2 Sector buffer pointer (LSB). @+3 Sector buffer pointer (MSB). @+4 Number of records (LSB). @+5 Number of records (MSB). @+6 Record length (LSB). @+7 Record length (MSB). @+8 Current record (LSB). @+9 Current record (MSB). @+10 Unused. @+11 Unused. @+12 First byte of CP/M FCB.

@+47 Last byte of CP/M FCB. @+48 First byte of sector buffer.

@+175 Last byte of sector buffer.

The format of the flags byte at @ + 0 is:

Bit 0 .. 3 File type. Bit 4 Read semaphore. Bit 5 Write semaphore. Bit 6 Output flag. Bit 7 Input flag.

280 TURBO Pascal Reference Manual Internal Data Formats

File type 0 denotes a disk file, and 1 through 5 denote the TURBO Pas cal logical 1/0 devices (CON:, KBD:, LST:, AUX:, and USR:). For typed files, bit 4 is set if the contents of the sector buffer is undefined, and bit 5 is set if data has been written to the sector buffer. For textfiles, bit 5 is set if the character buffer contains a pre-read character. Bit 6 is set if output is allowed, and bit 7 is set if input is allowed.

The sector buffer pointer stores an offset (0 .. 127) in the sector buffer at @ + 48. For typed and untyped files, the three words from @ + 4 to @ + 9 store the number of records in the file, the record length in bytes, and the current record number. The FIB of an untyped file has no sector buffer, and so the sector buffer pointer is not used.

When a text file is assigned to a logical device, only the flags byte and the character buffer are used.

Pointers

A pointer consists of two bytes containing a 16-bit memory address, and it is stored in memory using byte reversed format, i.e. the least significant byte is stored first. The value nil corresponds to a zero word.

Data Structures

Data structures are built from the basic data types using various struc turing methods. Three different structuring methods exist: arrays, records, and disk files. The structuring of data does not in any way affect the internal formats of the basic data types.

Arrays

The components with the lowest index values are stored at the lowest memory address. A mUlti-dimensional array is stored with the rightmost dimension increasing first, e.g. given the array

Board: array[l .. 8,1 .. 8] of Square

you have the following memory layout of its components:

CP/M-8D 281 Internal Data Formats

lowest address: Board [ 1, 1] Board[1,2]

Board[1,8] Board[2,1] Board[2,2]

Highest address: Board[ 8,8]

Records

The first field of a record is stored at the lowest memory address. If the record contains no variant parts, the length is given by the sum of the lengths of the individual fields. If a record contains a variant, the total number of bytes occupied by the record is given by the length of the fixed part plus the length of largest of its variant parts. Each variant starts at the same memory address.

Disk Files

Disk files are different from other data structures in that data is not stored in internal memory but in a file on an external device. A disk file is controlled through a file interface block (FIB) as described on page 280. In general there are two different types of disk files: random access files and text files.

Random Access Files

sector 0, byte 0: Number of records (LSB) sector 0, byte 1: Number of records (MSB) sector 0, byte 2: Record length (LSB) sector 0, byte 3: Record length (MSB)

282 TURBO Pascal Reference Manual Internal Data Formats

Text Files

The basic components of a text file are characters, but a text file is sub divided into lines. Each line consists of any number of characters ended by a CR/LF sequence (ASCII $OD/ $OA). The file is terminated by a Ctrl-Z (ASCII $1 A).

Parameters

Parameters are transferred to procedures and functions via the Z-80 stack. Normally, this is of no interest to the programmer, as the machine code generated by TURBO Pascal will automatically PUSH parameters onto the stack before a call, and POP them at the beginning of the sub program. However, if the programmer wishes to use external subpro grams, these must POP the parameters from the stack themselves.

On entry to an external subroutine, the top of the stack always contains the return address (a word). The parameters, if any, are located below the return address, i.e. at higher addresses on the stack. Therefore, to access the parameters, the subroutine must first POP off the return ad dress, then all the parameters, and finally it must restore the return ad dress by PUSHing it back onto the stack.

Variable Parameters

With a variable (VAR) parameter, a word is transferred on the stack giv ing the absolute memory address of the first byte occupied by the actual parameter.

Value Parameters

With value parameters, the data transferred on the stack depends upon the type of the parameter as described in the following sections.

Scalars

Integers, Boo/eans, Chars and declared scalars are transferred on the stack as a word. If the variable occupies only one byte when it is stored, the most significant byte of the parameter is zero. Normally, a word is POPped off the stack using an instruction like POP HL.

CP/M-80 283 Internal Data Formats

Reals

A real is transferred on the stack using six bytes. If these bytes are POPped using the instruction sequence:

POP HL POP DE POP BC

then L will contain the exponent, H the fifth (least significant) byte of the mantissa, E the fourth byte, D the third byte, C the second byte, and B the first (most significant) byte.

Strings

When a string is at the top of the stack, the byte pointed to by SP con tains the length of the string. The bytes at addresses SP + 1 through SP + n (where n is the length of the string) contain the string with the first character stored at the lowest address. The following machine code instructions may be used to POP the string at the top of the stack and store it in StrBut.

LD DE,StrBuf LD HL,O LD B,H ADD HL,SP LD C, (HL) INC BC LDIR LD SP,HL

Sets

A set always occupies 32 bytes on the stack (set compression only ap plies to the loading and storing of sets). The following machine code in structions may be used to POP the set at the top of the stack and store it in SetBut.

284 TURBO Pascal Reference Manual Internal Data Formats LD DE,SetBuf LD HL,O ADD HL,SP LD BC,32 LDIR LD SP,HL

This will store the least significant byte of the set at the lowest address in SetBuf.

Pointers

A pointer value is transferred on the stack as a word containing the memory address of a dynamic variable. The value NIL corresponds to a zero word.

Arrays and Records

Even when used as value parameters, Array and Record parameters are not actually PUSHed onto the stack. Instead, a word containing the ad dress of the first byte of the parameter is transferred. It is then the responsibility of the subroutine to POP this word, and use it as the source address in a block copy operation.

Function Results

User written external functions must return their results exactly as specified in the following:

Values of scalar types, must be returned in the HL register pair. If the type of the result is expressed in one byte, then it must be returned in L and H must by zero.

Reals must be returned in the BC, DE, and HL register pairs. B, C, 0, E, and H must contain the mantissa (most significant byte in B), and L must contain the exponent.

Strings and sets must be returned on the top of the stack on the for mats described on page 284.

Pointer values must be returned in the HL register pair.

CP/M-8D 285 Internal Data Formats

The Heap and The Stacks

As indicated by the memory maps in previous sections, three stack-like structures are maintained during execution of a program: The heap, the CPU stack, and the recursion stack.

The heap is used to store dynamic variables, and is controlled with the standard procedures New, Mark, and Release. At the beginning of a program, the heap pOinter HeapPtr is set to the address of the bottom of free memory, i.e the first free byte after the object code.

The CPU stack is used to store intermediate results during evaluation of expressions and to transfer parameters to procedures and functions. An active for statement also uses the CPU stack, and occupies one word. At the beginning of a program, the CPU stack pOinter StackPtr is set to the address of the top of free memory.

The recursion stack is used only by recursive procedures and functions, i.e. procedures and functions compiled with the A compiler directive pas sive ({$A-}). On entry to a recursive subprogram it copies its workspace onto the recursion stack, and on exit the entire workspace is restored to its original state. The default initial value of RecurPtr at the beginning of a program, is 1 K ($400) bytes below the CPU stack pOinter.

Because of this technique, variables local to a subprogram must not be used as var parameters in recursive calls.

The pre-defined variables:

HeapPtr: The heap pointer, RecurPtr: The recursion stack pointer, and StackPtr: The CPU stack pointer

allow the programmer to control the position of the heap and the stacks.

The type of these variables is Integer. Notice that HeapPtr and RecurPtr may be used in the same context as any o~her Integer variable, whereas StackPtr may only be used in assignments and expressions.

When these variables are manipulated, always make sure that they pOint to addresses within free memory, and that:

HeapPtr < RecurPtr < StackPtr

286 TURBO Pascal Reference Manual Internal Data Formats

Failure to adhere to these rules will cause unpredictable, perhaps fatal, results.

Needless to say, assignments to the heap and stack pointers must nev er occur once the stacks or the heap are in use.

On each call to the procedure New and on entering a recursive pro cedure or function, the system checks for collision between the heap and the recursion stack, i.e. checks if HeapPtr is less than RecurPtr. If not, a collision has occurred, which results in an execution error.

Note that no checks are made at any time to insure that the CPU stack does not overflow into the bottom of the recursion stack. For this to happen, a recursive subroutine must call itself some 300-400 times, which must be considered a rare situation. If, however, a program re quires such nesting, the following statement executed at the beginning of the program block will move the recursion stack pointer downwards to create a larger CPU stack:

Recurptr := StackPtr -2 *MaxDepth -512;

where MaxDepth is the maximum required depth of calls to the recur sive subprogram(s). The extra approx. 512 bytes are needed as a margin to make room for parameter transfers and intermediate results during the evaluation of expressions.

CP/M-BO 287 Memory Management

Memory Management

Memory Maps

The following diagrams illustrate the contents of memory at different stages of working with the TURBO system. Solid lines indicate fixed boundaries (Le. determined by amount of memory, size of your CP/M, version of TURBO, etc.), whereas dotted lines indicate boundaries which are determined at run-time (e.g. by the size of the source text, and by possible user manipulation of various pointers, etc.). The sizes of the segments in the diagrams do not necessarily reflect the amounts of memory actually consumed.

Compilation in Memory

During compilation of a program in memory (Memory-mode on compiler Options menu, see page 259), the memory is mapped as follows:

0000 CP/M and run-time workspace Pascal Library

Turbo interface, editor, and compiler

Error messages, optional I------_. r- --- Source text r------1-- Object code growing upward

t Symbol table growing downward t CPU stack growing downward

CP/M HighMem Figure 22-5: Memory map during compilation in memory

288 TURBO Pascal Reference Manual Memory Management

If the error message file is not loaded when starting TURBO, the source text starts that much lower in memory. When the compiler is invoked, it generates object code working upwards from the end of the source text. The CPU stack works downwards from the logical top of memory, and the compiler's symbol table works downwards from an address 1 K ($400 bytes) below the logical top of memory.

Compilation To Disk

During compilation to a .COM or .CHN file (Com-mode or cHn-mode on compiler Options menu, see page 259), the memory looks much as dur ing compilation in memory (see preceding section) except that generated object code does not reside in memory but is written to a disk file. Also, the code starts at a higher address (right after the Pascal library instead of after the source text). Compilation of much larger programs is thus possible in this mode.

0000 CP/M and run-time workspace Pascal Library

Turbo interface, editor, and compiler

------Error messages, optional

Source text

t Symbol table growing downward

1 CPU stack growing downward

CP/M HighMem

Figure 22-6: Memory map during compilation to a file

CP/M-80 289 Memory Management

Execution in Memory

When a program is executed in direct - or memory - mode (Le. the Memory-mode on compiler Options menu is selected, see page 259), the memory is mapped as follows:

0000 CP/M and run-time workspace Pascal Library

Turbo interface, editor, and compiler

Error messages, optional 1------1----

Source text t'------

Object code

1------Default initial value of HeapPtr -!- Heap growing upward

Recursion stack growing downward ______t_ Default initial value of RecurPtr ______1_ CPU stack growing downward Default initial state of StackPtr

Program variables growing downward CP/M HighMem Figure 22-7: Memory map during execution in direct mode

When a program is compiled, the end of the object code is known. The heap pointer HeapPtr is set to this value by default, and the heap grows from here and upwards in memory towards the recursion stack. The maximum memory size is BOOS minus one (indicated on the compiler Options menu). Program variables are stored from this address and downwards. The end of the variables is the 'top of free memory' which is the initial value of the CPU stack pOinter StackPtr. The CPU stack grows downwards from here towards the position of the recursion stack pointer RecurPtr, $400 bytes lower than StackPtr. The recursion stack grows from here downward towards the heap.

290 TURBO Pascal Reference Manual Memory Management

Execution of A Program File

When a program file is executed (either by the Run command with the Memory-mode on the compiler Options menu selected, by an eXecute command, or directly from CP/M), the memory is mapped as follows:

0000 1------1--- CP/M and run-time workspace Pascal Library 1------1--- Default program start address

Object code

------1--1- Default initial value of HeapPtr Heap growing upward

Recursion stack growing downward ______I- J -- Default initial value of RecurPtr CPU stack growing downward ______r- 1- Default initial state of StackPtr

Program variables growing downward I- -- Default end address ...-____L_o_ad_e_r ____-+- __Maximum memory size CP/M

~ ______~~___ H~hMem

Figure 22-8: Memory map during execution of a program file

This map resembles the previous, except for the absence of the TURBO interface, editor, and compiler (and possible error messages) and of the source text. The default program start address (shown on the compiler Options menu) is the first free byte after the Pascal runtime library. This value may be manipulated with the Start address command of the com piler Options menu, e.g. to create space for absolute variables and/or external procedures between the library and the code. The maximum memory size is BOOS minus one,· and the default value is determined by the BOOS location on the computer in use.

CP/M-80 291 Memory Management

If programs are to be translated for other systems, care should be taken to avoid collision with the BDOS. The maximum memory may be mani pulated with the End address command of the compiler Options menu. Notice that the default end address setting is approx. 700 to 1000 bytes lower than maximum memory. This is to allow space for the loader which resides just below BDOS when .COM files are Run or eXecuted from the TURBO system. This loader restores the TURBO editor, com piler, and possible error messages when the program finishes and thus returns control to the TURBO system.

292 TURBO Pascal Reference Manual TURBO-BCD Chapter 23 TURBO-BCD

TURBO-BCD is a special version of TURBO Pascal which is not included in the standard TURBO Pascal package. It employs binary coded de cimal (BCD) Real numbers to obtain higher accuracy, especially needed in programs for business applications.

If you are interested in purchasing TURBO-BCD, please see page 3 for ordering information. TURBO-BCD will compile and run any program written for standard TURBO or TURBO-8? Pascal that does not use these procedures or functions: Sin, Cos, ArcTan, Ln, Exp, Sqrt, and the pre-declared constant Pi, the only difference being in real number processing and real number format. Files On the TURBO-BCD Distribution Diskette

In addition to the files listed on page 8, the TURBO-BCD distribution diskette contains the file

TURBOBCD.COM

(TURBOBCD.CMD for CP/M-86). This file contains the special TURBO BCD system. If you want to install it with TINST, you must first tem porarily rename it to TURBO.COM (or .CMD).

BCD Range

TURBO-BCD's BCD Reals have a range of 1 E-63 through 1 E + 63 with 18 significant digits.

TURBO-BCD 293 Form function Form function

Syntax: Form(St, Var1, Var2, .. , VarN)

The Form function provides advanced numeric and string formatting. St is a string expression giving an image of the format string, as detailed in the following, and Var1, Var2, .. , VarN are Real, Integer, or String expres sions. The result is a String of the same length as Sf.

St is made up of a number of field specifiers, each of which corresponds to one parameter in the parameter list. Blanks and characters other than the ones defined in the following serve to separate fields and will also appear in the formatted result, viz:

Form( 'Total: $#,###.##' ,1234.56) = 'Total: $1,234.56'

The arguments in the argument list use the field specifiers in the order of appearance:

Form('Please @@@@@@ us at (###) ### ####'. 'phone' .408,438.8400) - 'Please phone us at (408) 438 8400 '

If there are more arguments in the argument list than there are field specifiers in the format string, the arguments in excess are ignored. If there are less arguments than field specifiers, the field specifiers in ex cess are returned unchanged:

Form('###.##' ,12.34,43.21) = ' 12.34' Form('###.## -##.##' ,123.4) = '123.40 -##.##'.

There are two types of field specifiers: numeric and string.

Numeric Fields

A numeric field is a sequence of one or more of the following characters:

# @ * $ +

294 TURBO Pascal Reference Manual Form function

Any other character terminates the numeric field. The number is re turned right-justified within the field, decimals are rounded if they exceed the number of decimals specified by the format, and if the number is too large to be returned in the field, all digit positions are filled with aster isks.

# A digit position. If the numeric field contains no @ or * characters, unused digits are returned as blanks. If the numeric field contains no sign positions ('-' or ' + ' characters) and the number is negative, a float ing minus is returned in front of the number.

Examples: Form( '####' ,34.567) 35' Form('###.##' ,12.345') , 12.35' Form( '####.##' ,-12.3) , -12.30' Form( '###.##' ,1234.5) '*** **'

@ A digit position. Unused digits are forced to be returned as zeros instead of blanks. The @ character needs only occur once in the numeric field to activate this effect. The sign of the number will not be returned unless the field contains a sign position ('-' or' + ' character).

Examples: Form( '@##' ,9) '009' Form( '@@@.@@' ,12.345) '012.35'

* A digit position. Unused digits are forced to be returned as asterisks in stead of blanks. The * character needs only occur once in the numeric field to activate this effect. The sign of the number will not be returned unless the field contains a sign position ('-' or' + ' character).

Examples: Form( '*##.#' ,4.567) '**4.57' Form( '****' ,123) = '*123'

TURBO-BCD 295 Form function

$ A digit position. A floating $-sign is returned in front of the number. The '$' character need only occur once in the numeric field to activate this effect.

Examples: Form('$#####.##' ,123.45) $123.45' Form( '######.#$' ,-12.345) -$12.35' Form( '*$####.##' ,12.34) '***$12.34'

A sign position. If the number is negative, a minus will be returned in that position; if it is positive, a blank is returned.

Examples: Form( '-###.##' ,-1.2) 1.20' Form( '-###.##' ,12) 12.00' Form( '*#####.##-' ,-123.45) '***123.45-'

+ A sign position. If the number is positive, a plus will be returned in that position; if it is negative, a minus is returned.

Examples: Form( '+###.##' ,-1.2) 1.20' Form( '+###.##' ,12) '+ 12.00' Form( '*$####.##+' ,12.34) '***$12.34+'

A decimal comma or a separator comma. The last period or comma in the numeric image is considered the decimal delimiter.

A decimal period or a separator period. The last period or comma in the numeric image is considered the decimal delimiter.

Examples: Form('##,###,###.##' ,12345.6) 12,345.60' Form( '$#.###.###,##' ,-12345.6) -$12.345,60' Form('*$,###,###.##+' ,12345.6) '***$12,345.60+' Form('##,###.##' ,123456.0) '** , *** . **'

296 TURBO Pascal Reference Manual Form function

String Fields

A string field is a sequence of # or @ characters. If the string parameter is longer than the string field, only the first characters of the string are returned.

# If the field contains only # characters, the string will be returned left justified.

@ If one or more '@' characters are present in the field, the string will be returned right justified within the length of the field.

Examples:

Form( '##########', 'Pascal') 'Pascal' Form( '@#########', 'Pascal') Pascal' Form( '####', 'TURBO Pascal') 'TURBO' Form( '@@@@', 'TURBO Pascal') 'TURBO'

Writing BCD Reals

BCD Rea/s are written on a format slightly different from the standard format, as described below.

R The decimal representation of the value of R is output in a field 25 char acters wide, using floating point format. For R > = 0.0, the format is:

uu#.#################E*##

For R < 0.0, the format is:

u-#.#################E*##

where u represents a blank, # represents a digit, and * represents ei ther plus or minus.

TURBO-BCD 297 Writing BCD Reals

R:n The decimal representation of the value of R is output, right adjusted in a field n characters wide, using floating point format. For R > = 0.0: blanks#.digitsE*##

For R < 0.0: blanks-#.digitsE*##

where blanks represents zero or more blanks, digits represents from 1 to 17 digits, # represents a digit, and * represents either plus or minus.

Formatted Writing

The Form standard function can be used as a write parameter to pro duce formatted output: Write(Form( 'The price is $###,###,###.##' ,Price));

Internal Data Format

The BCD Real variable occupies 10 bytes, and consists of a floating point value with an 18 digit binary coded decimal mantissa, a 7 -bit 1D's exponent, and a 1-bit sign. The exponent and the sign are stored in the first byte and the mantissa in the next nine bytes with the least significant byte first:

@+o Exponent and sign. @+l LSB of mantissa.

@+9 MSB of mantissa.

298 TURBO Pascal Reference Manual Internal Data Format

The most significant bit of the first byte contains the sign. 0 means posi tive and 1 means negative. The remaining seven bits contain the ex ponent in binary format with an offset of $3F. Thus, an exponent of $41 indicates that the value of the mantissa is to be multiplied by 10~($41- $3F) = 1 0~2 = 100. If the first byte is zero, the floating point value is considered to be zero. Starting with the tenth byte, each byte of the mantissa contains two digits in BCD format, with the most significant di git in the upper four bits. The first digit contains the 1/1 D's, the second contains the 1/1 ~O's, etc. The mantissa is always normalized, i.e. the first digit is never 0 unless the entire number is O.

This 10-byte Real is not compatible with TURBO standard or 8087 Reals. This, however, should only be a problem if you develop programs in different versions of TURBO which must interchange data. The trick then is simply to provide an interchange-format between the programs in which you transfer Reals on ASCII format, for instance.

TURBO-BCD 299 Internal Data Format

Notes:

300 TURBO Pascal Reference Manual TURBO-87 Chapter 24 TURBO-87

TURBO-87 TURBO-87 is a special version of TURBO Pascal which is not included in the standard TURBO Pascal package. It uses the Intel 8087 math processor for real number arithmetic, providing a significant gain in speed. TURBO-87 does not include the 8087 chip.

If you are interested in purchasing TURBO-87, please see page 3 for ordering information.

TURBO-87 will compile and run any program written for standard TURBO Pascal; the only difference being in real number processing and real number format.

TURBO-87 programs will not run on a computer without the 8087-chip installed, whereas the opposite will work.

Files On the TURBO-87 Distribution Diskette

In addition to the files listed on page 8, the TURBO-87 distribution diskette contains the file

TURBO-87.COM

(TURBO-87.CMD for CP/M-86). This file contains the special TURBO-8? system. If you want to install it with TINST, you must first temporarily rename it to TURBO.COM (or .CMD).

TURBO-87 301 Writing 8087 Reals

Writing 8087 Reals

8087 Reals are written on a format slightly different from the standard format, as described below.

R The decimal representation of the value of R is output in a field 23 char acters wide, using floating point format. For R > = 0.0, the format is: uu#.###############E*###

For R < 0.0, the format is: u-#. #.##############E*###

where LJ represents a blank, # represents a digit, and * represents ei ther plus or minus.

R:n The decimal representation of the value of R is output, right adjusted in a field n characters wide, using floating point format. For R > = 0.0: blanks#.digitsE*###

For R < 0.0: blanks-#.digitsE*###

where blanks represents zero or more blanks, digits represents from 1 to 14 digits, # represents a digit, and * represents either plus or minus.

Internal Data Format

The 8087 chip supports a range of data types. The one used by TURBO-87 is the long reat, its 64-bits yielding 16 digits accuracy and a range of 4.19E-307 to 1.67E + 308.

This 8-byte Real is not compatible with TURBO standard or BCD Reals. This, however, should only be a problem if you develop programs in different versions of TURBO which must interchange data. The trick then is simply to provide an interchange-format between the programs in which you transfer Reals on ASCII format, for instance.

302 TURBO Pascal Reference Manual AppendixA A SUMMARY OF STANDARD PROCEDURES AND FUNCTIONS

This appendix lists all standard procedures and functions available in Turbo Pascal and describes their use, syntax, parameters, and type. The follow ing symbols are used to denote elements of various types:

string Any string type type Any type file Any file type scalar Any scalar type pointer Any pointer type

When a parameter-type specification is not present, it means that the procedure or function accepts variable parameters of any type.

INPUT/OUTPUT PROCEDURES AND FUNCTIONS The following procedures use a non-standard syntax in their parameter lists: Read; Read(var V: type); Read(var F: file of type; var V: type); Read(var F: text; var I: integer); Read(var F: text; var R: real); Read(var F: text; var C: char); Read(var F: text; var S: string); Readln; Readln(var V: type); Readln(var F: text); Readln(var F: text; var I: integer); Readln(var F: text; var R: real); Readln(var F: text; var C: char); Readln(var F: text; var S: string); Write(var V: type); Write(var F: file of type; var V: type); Write(var F: Text; I: integer); Write(var F: Text; R: real); Write(var F: Text; B: boolean); Write(var F: Text; C: char); Write(var F: Text; S: string); Writeln; Writeln(var V type); Writeln(var F Text); Writeln(var F Text; I: integer);

TURBO-87 303 Arithmetic Functions

Writeln(var F: Text; R: real); Writeln(var F: Text; B: boolean); Writeln(var F: Text; C: char); Writeln(var F: Text; S: string);

ARITHMETIC FUNCTIONS Abs(I: integer): integer; Abs(R: real): real; ArcTan(R: real): real; Cos(R: real): real; Exp(R: real): real; Frac(R: real): real; Int(R: real): real; Ln(R: real): real; Sin(R: real): real; Sqr(I: integer): integer; Sqr(R: real): real; Sqrt(R: real): real;

FILE-HANDLING ROUTINES Procedures Append(var F: text; Name: string); {PC/MS-DOS, CP/M-86} Assign(var F: file; Name: string); BlockRead(var F: file; var Dest: Type; Num: integer); {untyped files} BlockRead(var F: file; var Dest: Type; Num: integer; var RecsRead: integer); {untyped files PC/MS-DOS} BlockWrite(var F: file; var Dest: Type; Num: integer); {untyped files} BlockWrite(var F: file; var Dest: Type; Num: integer; var RecsWritten: integer); {untyped files PC/MS-DOS} Chain(var F: file); Close(var F: file); Erase(var F: file); Execute(var F: file); Rename(var F: file; Name: string); Reset(var F: file); Reset(var F: file; BlockSize : integer); {untyped files PC/MS-DOS} Rewrite(var F: file); Rewrite(F: file; BlockSize : integer); {untyped files PC/MS-DOS} Seek(var F: file Pos: integer); {except text files} LongSeek(var F: file; Pos: real); {except text files, PC/MS-DOS only}

304 TURBO Pascal Reference Manual Heap Control Procedures and Functions

Functions Eof(var F: file): boolean; Eoln(var F: Text): boolean; FilePos(var F: file of type): integer; FilePos(var F: file): integer; LongFilePos(var F: file): real; {except text files, PC/MS-DOS only} FileSize(var F: file): integer; {except text files} LongFileSize(var F: file): real; {except text files, PC/MS-DOS only} SeekEof(var F: file): boolean; SeekEoln(var F: Text): boolean; HEAP CONTROL PROCEDURES AND FUNCTIONS Procedures Dispose(var P: pOinter); FreeMem(var P: pointer, I: integer); GetMem(var P: pointer; I: integer); Mark(var P: pOinter); New(var P: pOinter); Release(var P: pointer); Functions MaxAvail: integer; MemAvail: integer; Ord(P: pOinter): integer; {CP/M-50} Ptr(segment, offset: integer): Pointer; {PC/MS-DOS, CP/M-56}

MISCELLANEOUS PROCEDURES AND FUNCTIONS Procedures Bdos(Func {,Param }: integer); {CP/M-50} Bdos(Func: integer; Param: record); {CP/M-56} Bios(Func {,Param }: integer); {CP/M} Delay(MS: integer); Exit; FillChar(var Dest, Length: integer; Data: char); FillChar(var Dest, Length: integer; Data: byte); Halt; Intr(Func : integer; Param : record); {PC/MS-DOS} MsDos(Func: integer; Param: record); {PC/MS-DOS} Move(var Source,Dest; Length: integer); Randomize; Functions Addr(var Variable): Pointer; {PC/MS-DOS, CP/M-56} Addr(var Variable): integer; {CP/M-50} Addr«function identifier»: integer; {CP/M-50} Addr«procedure identifier»: integer; (CP/M-50}

SUMMARY OF STANDARD PROCEDURES AND FUNCTIONS 305 Miscellaneous Procedures and Functions

Bdos(Func, Param: integer): byte; {CP/M-8D} BdosHL(Func, Param: integer): integer; {CP/M-8D} Bios(Func, Param: integer): byte; {CP/M} BiosHL(Func, Param: integer): integer; {CP/M} Hi(I: integer): byte; IOresult: integer; KeyPressed : boolean; Lo(I: integer): byte; Ofs(var Variable): integer; {PC/MS-DOS, CP/M-8b} Ofs«fnnction identifier»: integer; {PC/MS-DOS, CP/M-8b} Ofs«procednre identifier»: integer; {PC/MS-DOS, CP/M-8b} ParamCount: integer; ParamStr(N: integer): string; Random(Range: integer): integer; Random: real; Seg(var Variable): integer; {PC/MS-DOS, CP/M-8b} SizeOf(var Variable): integer; SizeOf«type identifier»: integer; Swap(I: integer): integer; UpCase(Ch: char): char; SCALAR FUNCTIONS Functions Odd(I: integer): boolean; Pred(X: scalar): scalar; Succ(X: scalar): scalar;

DIRECTORY-RELATED PROCEDURES (PC/MS-DOS) Procedures ChDir(Path: string); GetDir(Drv: integer; var Path: string); MkDir(Path: string); RmDir(Path: string); SCREEN-RELATED PROCEDURES AND FUNCTIONS Procedures CrtExit; CrtInit; CirEoi; ClrScr; DelLine; GotoXY(X, Y: integer); InsLine; LowVideo; HighVideo; NormVideo;

306 TURBO Pascal Reference Manual String Procedures and Functions

STRING PROCEDURES AND FUNCTIONS The Str procedure uses a non-standard syntax for its numeric parameter. Procedures Delete(var S: string; Pos, Len: integer); Insert(S: string; var D: string; Pos: integer); Str(I: integer; var S: string); Str(R: real; var S: string); Val(S: string; var R: real; var p: integer); Val(S: string; var I, p: inte~~r); Functions Concat(S1,S2, ... ,Sn: string): string; Copy(S: string; Pos, Len: integer): string; Length(S: string): integer; Pos(Pattern, Source: string): integer;

TRANSFER FUNCTIONS Chr(I: integer): char; Drd(X: scalar): integer; Round(R: real): integer; Trunc(R: real): integer;

IBM PC PROCEDURES AND FUNCTIONS The following procedures and functions apply to IBM implementations only. Basic Graphics, Windows, and Sound Procedures Draw(X1,Y1,X2,Y2,Color: integer); GraphBackground(Color: integer); GraphColorMode; GraphMode; GraphWindow(X1,Y1,X2,Y2: integer); HiRes; HiResColor(Color: integer); NoSound; Palette(Color: integer); Plot(X,y,Color: integer); Sound(I: integer); TextBackground(Color: integer); TextColor(Color: integer); TextMode(Color: integer); Window(X1,Y1,X2,Y2: integer);

SUMMARY OF STANDARD PROCEDURES AND FUNCTIONS 307 IBM PC Procedures and Functions

Functions WhereX: integer; WhereY: integer; Constants BW~O: integer; = 0 C~O: integer; = 1 BWBO: integer; = 2 CBO: integer; = 3 Black: integer; = 0 Blue: integer; = 1 Green: integer; = 2 Cyan: integer; = 3 Red: integer; = ~ Magenta: integer; = 5 Brown: integer; = 6 LightGray: integer; 7 DarkGray: integer; = B LightBlue: integer; = 9 LightGreen: integer; = 10 LightCyan: integer; = 11 LightRed: integer; = 12 LightMagenta: integer; = 13 Yellow: integer; = 1~ White: integer; = 15 Blink: integer; = 16 Extended Graphics Procedures Arc(X,Y,Angle,Radius,Color: integer); Circle(X,Y,Radius,Color: integer); ColorTable(C1,C2,C3,C~: integer); FillScreen(Color: integer); FillShape(X,Y,FillColor,BorderColor: integer); FillPattern(X1,Y1,X2,Y2,Color: integer); GetPic(var Buffer: AnyType; X1,Y1,X2,Y2: integer); Pattern(P: Array[0 .. 7] of Byte); PutPic(var Buffer: type; X,Y: integer); function GetDotColor(X,Y: integer): integer;

Turtlegraphics Procedures Back(Dist: integer); ClearScreen; Forward(Dist: integer); HideTurtle; Home; NoWrap; PenDown;

308 TURBO Pascal Reference Manual IBM PC Procedures and Functions

PenUp; SetHeading(Angle: integer); SetPenColor(Color: integer); SetPosition(X,Y: integer); ShowTurtle; TurnLeft(Angle: integer); TurnRight(Angle: integer); TurtleDelay(Ms: integer); TurtleWindow(X,Y,W,H: integer); Wrap; Functions Heading: integer; Xeor: integer; Yeor: integer; TurtleThere: boolean; Constants North = 0; East = gO; South = LBO; West = 270;

SUMMARY OF STANDARD PROCEDURES AND FUNCTIONS 309 Standard Procedures and Functions

Notes:

310 TURBO Pascal Reference Manual SUMMARY OF OPERA TORS Appendix B SUMMARY OF OPERATORS

The following table summarizes all operators of TURBO Pascal. The operators are grouped in order of descending precedence. Where Type of operand is indicated as Integer, Real, the result is as follows:

Operand Result Integer, Integer Integer Real, Real Real Real, Integer Real

Operator Operation Type of operand(s) Type of result

+ unary sign identity Integer, Real as operand - unary sign inversion Integer, Real as operand

not negation Integer, Boolean as operand

multiplication Integer, Real Integer, Real set intersection any set type as operand I division Integer, Real Real div Integer division Integer Integer mod modulus Integer Integer and arithmetical and Integer Integer logical and Boolean Boolean shl shift left Integer Integer shr shift right Integer Integer

+ addition Integer, Real Integer, Real concatenation string string set union any set type as operand subtraction Integer, Real Integer, Real set difference any set type as operand or arithmetical or Integer Integer logical or Boolean Boolean xor arithmetical xor Integer Integer logical xor Boolean Boolean

SUMMARY OF OPERA TORS 311 Operator Operation Type of operand(s) Type of result

equality any scalar type Boolean equality string Boolean equality any set type Boolean equality any pointer type Boolean <> inequality any scalar type Boolean inequality string Boolean inequality any set type Boolean inequality any pointer type Boolean >= greater or equal any scalar type Boolean greater or equal string Boolean set inclusion any set type Boolean <= less or equal any scalar type Boolean less or equal string Boolean set inclusion any set type Boolean > greater than any scalar type Boolean greater than string Boolean < less than any scalar type Boolean less than string Boolean in set membership see below Boolean

The first operand of the in operator may be of any scalar type, and the second operand must be a set of that type.

312 TURBO Pascal Reference Manual SUMMARY OF COMPILER DIRECTIVES Appendix C SUMMARY OF COMPILER DIRECTIVES

A compiler directive consists of an opening bracket immediately followed by a dollar-sign immediately followed by one compiler directive letter or a list of compiler directive letters separated by commas, ultimately ter minated by a closing bracket.

Examples: {$I-} {$I INCLUDE. FIL} {$B-, R+, V-} (*$U+*)

Notice that no spaces are allowed before or after the dollar-sign. A + sign after a directive indicates that the associated compiler feature is en abled (active), and a minus sign indicates that is disabled (passive).

IMPORTANT NOTICE

All compiler directives have default values. These have been chosen to optimize execution speed and minimize code size. This means that e.g. code generation for recursive procedures (CP/M-BO only) and index checking has been disabled. Check below to make sure that your programs include the required compiler directive settingsl

SUMMARY OF COMPILER DIRECTIVES 313 Common Compiler Directives

Common Compiler Directives

B - I/O Mode Selection

Default: B+

The B directive controls input/output mode selection. When active, {$B + }, the CON: device is assigned to the standard files Input and Out put, i.e. the default input/output channel. When passive, {$B-}, the TRM: device is used. This directive is global to an entire program block and cannot be re-defined throughout the program. See pages 105 and 108 for further details.

C - Control C and S

Default: C +

The C directive controls control character interpretation during console I/O. When active, {$C +}, a Ctrl-C entered in response to a Read or Readln statement will interrupt program execution, and a Ctrl-S will tog gle screen output off and on. When passive, {$C-}, control characters are not interpreted. The active state slows screen output somewhat, so if screen output speed is imperative, you should switch off this directive. This directive is global to an entire program block and cannot be re defined throughout the program. Note that when using the function on KeyPressed, the C directive must be set to {$C-}. I - I/O Error Handling

Default: 1+

The I directive controls I/O error handling. When active, {$I +}, all I/O operations are checked for errors. When passive, {$I-}, it is the respon sibility of the programmer to check I/O errors through the standard func tion IOresult. See page 116 for further details.

I - Include Files

The I directive succeeded by a file name instructs the compiler to in clude the file with the specified name in the compilation. Include files are discussed in detail in chapter 17.

314 TURBO Pascal Reference Manual Common Compiler Directives

R - Index Range Check

Default: R-

The R directive controls run-time index checks. When active, {$R + }, all array indexing operations are checked to be within the defined bounds, and all assignments to scalar and subrange variables are checked to be within range. When passive, {$R-}, no checks are performed, and index errors may well cause a program to go haywire. It is a good idea to ac tivate this directive while developing a program. Once debugged, execu tion will be speeded up by setting it passive (the default state). v - Var-parameter Type Checking Default: V +

The V compiler directive controls type checking on strings passed as var-parameters. When active, {$V + }, strict type checking is performed, i.e. the lengths of actual and formal parameters must match. When pas sive, {$V-}, the compiler allows passing of actual parameters which do not match the length of the formal parameter. See pages 203, 236, and 267 for further details.

U - User Interrupt

Default: U-

The U directive controls user interrupts. When active, {$U + }, the user may interrupt the program anytime during execution by entering a Ctrl C. When passive, {$U-}, this has no effect. Activating this directive will significantly slow down execution speed.

SUMMARY OF COMPILER DIRECTIVES 315 PC-DOS and MS-DOS Compiler Directives

PC-DOS and MS-DOS Compiler Directives

The following directives are unique to the PC/MS-DOS implementations:

G - Input File Buffer

Default: GO

The G (get) directive enables I/O re-direction by defining the standard Input file buffer. When the buffer size is zero (default), the Input file refers to the CON: or TRM: device. When non-zero (e.g. {$G256}), it refers to the MS-DOS standard input handle.

The D compiler directive applies to such non-zero-buffer input and out put files. The G compiler directive must be placed before the declaration part.

Note that when using Chain or Execute you set all compiler directives to be the same across Chained or Executed modules. This includes the buffer sizes used for the G and P compiier directives.

P - Output File Buffer

Default: PO

The P (put) directive enables 1/0 re-direction by defining the standard Output file buffer. When the buffer size is zero (default), the Output file refers to the CON: or TRM: device. When non-zero (e.g. {$G512}), it refers to the MS-DOS standard output handle.

The D compiler directive applies to such non-zero-buffer input and out put files. The P compiler directive must be placed before the declaration part.

Note that when using Chain or Execute you set all directives to be the same across Chained or Executed modules. This includes the buffer sizes used for the G and P compiler directives. o - Device Checking Default: D +

When a text file is opened by Reset, Rewrite or Append, TURBO Pascal asks MS-DOS for the status of the file. If MS-DOS reports that the file is a

316 TURBO Pascal Reference Manual PC-DOS and MS-DOS Compiler Directives

device, TURBO Pascal disables the buffering that normally occurs on text files, and all 1/0 operations on the file are done on a character by character basis.

The D directive may be used to disable this check. In the default state {$D+}, device checks are made. In the {$D-} state, no checks are made and all device 1/0 operations are buffered. In this case, a call to the standard procedure Flush will ensure that the characters you have written to a file have actually been sent to it.

F-Number of Open Files

Default: F15

The F directive controls the number of files that may be open simultane ously. The default setting is {$F15}, which means that up to 16 files may be open at anyone time. This directive is global to a program and must be placed before the declaration part. The F compiler directive does not limit the number of files that may be declared in a program; it only sets a limit to the number of files that may be open at the same time.

The F compiler directives's maximum effective value is 15. Also, the maximum value for the statement

files = XX

in your CONFIG.SYS file is 20. Therefore, the maximum number of files available in a Turbo Pascal program running under MS-DOS/PC-DOS is 15. Note that even if the F compiler directive has been used to allocate sufficient file space, you may still experience a 'too many open files' er ror condition if the operating system runs out of file buffers. If that hap pens, you should supply a higher value for the files = xx parameter in the CONFIG.SYS file. The default value is usually 8. For further detail, please refer to your MS-DOS documentation.

PC-DOS, MS-DOS, and CP IM-a6 Compiler Directive

The following directive is unique to the 16-bit implementations:

SUMMARY OF COMPILER DIRECTIVES 317 CPIM-80 Compiler Directives

K - Stack Checking

Default: K +

The K directive controls the generation of stack check code. When ac tive, {$K + }, a check is made to insure that space is available for local variables on the stack before each call to a subprogram. When passive, {$K-}, no checks are made.

CP 1M-SO Compiler Directives

The following directives are unique to the 8-bit implementation:

A - Absolute Code

Default: A+

The A directive controls generation of absolute, i.e. non-recursive, code. When active, {$A +}, absolute code is generated. When passive, {$A-} , the compiler generates code which allows recursive calls. This code re quires more memory and executes slower.

W - Nesting of With Statements

Default: W2

The W directive controls the level of nesting of With statements, i.e. the number of records which may be 'opened' within one block. The W must be immediately followed by a digit between 1 and 9. For further details, please refer to page 81. ,.

x -Array Optimization

Default: X +

The X directive controls array optimization. When active, {$X +}, code generation for arrays is optimized for maximum speed. When passive, {$X-}, the compiler minimizes the code size instead. This is discussed further on page 75.

318 TURBO Pascal Reference Manual TURBO VS. STANDARD PASCAL Appendix D TURBO VS. STANDARD PASCAL

The TURBO Pascal language follows the Standard Pascal defined by Jensen & Wirth in their User Manual and Report, with only minor differences introduced for the sheer purpose of efficiency. These differences are described in the following. Notice that the extensions offered by TURBO Pascal are not discussed.

Recursion

CP /M-80 version only: Because of the way local variables are handled during recursion, a variable local to a subprogram must not be passed as a var-parameter in recursive calls.

Get and Put

The standard procedures Get and Put are not implemented. Instead, the Read and Write procedures have been extended to handle all I/O needs. The reason for this is threefold: Firstly, Read and Write give much faster I/O; secondly, variable space overhead is reduced, as file buffer variables are not required, and thirdly, the Read and Write pro cedures are far more versatile and easier to understand that Get and Put.

Goto Statements

A goto statement must not leave the current block.

Page Procedure

The standard procedure Page is not implemented, as the CP/M operat ing system does not define a form-feed character.

TURBO VS. STANDARD PASCAL 319 Page Procedure

Packed Variables

The reserved word packed has no effect in TURBO Pascal, but it is still allowed. This is because packing occurs automatically whenever possi ble. For the same reason, standard procedures Pack and Unpack are not implemented.

Procedural Parameters

Procedures and functions cannot be passed as parameters.

320 TURBO Pascal Reference Manual COMPILER ERROR MESSAGES Appendix E COMPILER ERROR MESSAGES

The following is a listing of error messages you may get from the com piler. When encountering an error, the compiler will always print the er ror number on the screen. Explanatory texts will only be issued if you have included error messages (answer Y to the first question when you start TURBO).

Many error messages are totally self-explanatory, but some need a little elaboration as provided in the following.

01 ';' expected 02 ':' expected 03 ' " expected 04 '(' expected 05 ')' expected 06 ' = ' expected 07 ': = ' expected 08 '[' expected 09 ']' expected 10 ' .' expected 11 ' .. ' expected 12 BEGIN expected 13 DO expected 14 END expected 15 OF expected 16 PROCEDURE or FUNCTION expected 17 THEN expected 18 TO or DOWNTO expected 20 Boolean expression expected 21 File variable expected 22 Integer constant expected 23 Integer expression expected 24 Integer variable expected 25 Integer or real constant expected 26 Integer or real expression expected 27 Integer or real variable expected 28 Pointer variable expected 29 Record variable expected

COMPILER ERROR MESSAGES 321 COMPILER ERROR MESSAGES

30 Simple type expected Simple types are all scalar types, except real. 31 Simple expression expected 32 String constant expected 33 String expression expected 34 String variable expected 35 Textfile expected 36 Type identifier expected 37 Untyped file expected 40 Undefined~b~ A statement references an undefined label. 41 Unknown identifier or syntax error Unknown label, constant, type, variable, or field identifier, or syntax error in statement. 42 Undefined pointer type in preceding type definitions A preceding pointer type definition contains a reference to an un known type identifier. 43 Duplicate identifier or label This identifier or label has already been used within the current block. 44 Type mismatch 1) Incompatible types of the variable and the expression in an assign ment statement 2) Incompatible types of the actual and the formal parameter in a call to a subprogram. 3) Expression type incompatible with index type in array assignment. 4) Types of operands in an ex pression are not compatible. 45 Constant out of range 46 Constant and CASE selector type does not match 47 Operand type(s) does not match operator Example: 'A' div '2' 48 Invalid result type Valid types are all scalar types, string types, and pointer types. 49 Invalid string length The length of a string must be in the range 1.. 255. 50 String constant length does not match type 51 Invalid subrange base type Valid base types are all scalar types, except real. 52 Lower bound > upper bound ihe ordinal value of the upper bound must be greater than or equal to the ordinal value of the lower bound. 53 Reserved word These may not be used as identifiers. 54 Illegal assignment

322 TURBO Pascal Reference Manual COMPILER ERROR MESSAGES

55 String constant exceeds line String constants must not span lines. 56 Error in integer constant An Integer constant does not conform to the syntax described in page 43, or it is not within the Integer range -32768 .. 32767. Whole Real numbers should be followed by a decimal point and a zero, e.g. 123456789.0. 57 Error in real constant The syntax of Real constants is defined on page 43. 58 Illegal character in identifier 60 Constants are not allowed here 61 Files and pointers are not allowed here 62 Structured variables are not allowed here 63 Textfiles are not allowed here 64 Textfiles and untyped files are not allowed here 65 Untyped files are not allowed here 66 I/O not allowed here Variables of this type cannot be input or output. 67 Files must be VAR parameters 68 File components may not be files file of file constructs are not allowed. 69 Invalid ordering of fields 70 Set base type out of range The base type of a set must be a scalar with no more than 256 pos sible values or a subrange with bounds in the range O.. 255. 71 Invalid GOTO A GOTO cannot reference a label within a FOR loop from outside that FOR loop. 72 Label not within current block A GOTO statement cannot reference a label outside the current block. 73 Undefined FORWARD procedure(s) A subprogram has been forward declared, but the body never oc curred. 74 INLINE error 75 Illegal use of ABSOLUTE 1) Only one identifier may appear before the colon in an absolute variable declaration. 2) The absolute clause may not be used in a record. 76 Overlays can not be forwarded The FORWARD specification cannot not be used in connection with overlays. 77 Overlays not allowed in direct mode Overlays can only be used from programs compiled to a file. (Starting with version 3.0, this applies only to CP/M-80 Turbo.)

COMPILER ERROR MESSAGES 323 COMPILER ERROR MESSAGES

90 File not found The specified include file does not exist. 91 Unexpected end of source Your program cannot end the way it does. The program probably has more begins than ends. 92 Unable to create overlay file 93 Invalid compiler directive 96 Cannot nest include files 97 Too many nested WITHs Use the W compiler directive to increase the maximum number of nested WITH statements. Default is 2. (CP/M-SO only). 98 Memory overflow You are trying to allocate more storage for variables than is available. 99 Compiler overflow There is not enough memory to compile the program. This error may occur even if free memory seems to exist; it is, however, used by the stack and the symbol table during compilation. Break your source text into smaller segments and use include files.

324 TURBO Pascal Reference Manual Appendix F. RUN-TIME ERROR MESSAGES

Fatal errors at run-time result in a program halt and the display of the message:

Run-time error NN, PC~addr Program aborted

where NN is the run-time error number, and addr is the address in the program code where the error occurred. The following contains explana tions of all run-time error numbers. Notice that the numbers are hexade cimal!

01 Floating point overflow. 02 Division by zero attempted. 03 Sqrt argument error. The argument passed to the Sqrt function was negative. 04 . Ln argument error. The argument passed to the Ln function was zero or negative. 10 String length error. 1) A string concatenation resulted in a string of more than 255 characters. 2) Only strings of length 1 can be converted to a charac ter. 11 Invalid string index. Index expression is not within 1 .. 255 with Copy, Delete or Insert pro cedure calls. 90 Index out of range. The index expression of an array subscript was out of range. 91 Scalar or subrange out of range. The value assigned to a scalar or a subrange variable was out of range. 92 Out of integer range. The real value passed to Trunc or Round was not within the Integer range - 32768 .. 32767. FO Overlay file not found. FF Heap/stack collision. A call was made to the standard procedure New or to a recursive subprogram, and there is insufficient free memory between the heap pointer (HeapPtr) and the recursion stack pointer (RecurPtr).

RUN-TIME ERROR MESSAGES 325 RUN-TIME ERROR MESSAGES

Notes:

326 TURBO Pascal Reference Manual I/O ERROR MESSAGES Appendix G 1/0 ERROR MESSAGES

An error in an input or output operation at run-time results in I/O error. If I/O checking is active (I compiler directive active), an I/O error causes the program to halt and the following error message is displayed: displayed:

I/O error NN, PC=addr Program aborted

Where NN is the I/O error number, and addr is the address in the pro gram code where the error occurred.

If I/O error checking is passive ({$I-}), an I/O error will not cause the pro gram to halt. Instead, all further I/O is suspended until the result of the I/O operation has been examined with the standard function IOresult. If I/O is attempted before IOresult is called after en error, a new error oc curs, possibly hanging the program.

The following contains explanations of all run-time error numbers. Notice that the numbers are hexadecimal!

01 File does not exist. The file name used with Reset, Erase, Rename, Execute, or Chain does not specify an existing file. 02 File not open for input. 1) You are trying to read (with Read or Readln) from a file without a previous Reset or Rewrite. 2) You are trying to read from a text file which was prepared with Rewrite (and thus is empty). 3) You are try ing to read from the logical device LST:, which is an output-only dev ice. 03 File not open for output. 1) You are trying to write (with Write or Writeln) to a file without a previous ROeset or Rewrite. 2) You are trying to write to a text file which was prepared with Reset. 3) You are trying to write to the logical device KBD:, which is an input-only device.

I/O ERROR MESSAGES 327 I/O ERROR MESSAGES

04 File not open. You are trying to access (with BlockRead or Block Write) a file without a previous Reset or Rewrite. 10 Error in numeric format. The string read from a text file into a numeric variable does not con form to the proper numeric format (see page 43 ). 20 Operation not allowed on a logical device. You are trying to Erase, Rename, Execute, or Chain a file assigned to a logical device. 21 Not allowed in direct mode. Programs cannot be Executed or Chained from a program running in direct mode (i.e. a program activated with a Run command while the Memory compiler option is set). 22 Assign to std files not allowed. 90 Record length mismatch. The record length of a file variable does not match the file you are trying to associate it with. 91 Seek beyond end-of-file. 99 Unexpected end-of-file. 1) Physical end-of-file encountered before EOF-character (Ctrl-Z) when reading from a text file. 2) An attempt was made to read beyond end-of-file on a defined file. 3) A Read or BlockRead is un able to read the next sector of a defined file. Something may be wrong with the file, or (in the case of BlockRead) you may be trying to read past physical EOF. FO Disk write error. Disk full while attempting to expand a file. This may occur with the output operations Write, WriteLn, Block Write, and Flush, but also Read, ReadLn, and Close may cause this error, as they cause the write buffer to be flushed. F1 Directory is full. You are trying to Rewrite a file, and there is no more room in the disk directory. F2 File size overflow. You are trying to Write a record beyond 65535 to a defined file. F3 Too many open files. FF File disappeared. An attempt was made to Close a file which was no longer present in the disk directory, e.g. because of an unexpected disk change.

328 TURBO Pascal Reference Manual TRANSLA TlNG Appendix H TRANSLATING ERROR MESSAGES

The compiler error messages are collected in the file TURBO. MSG. These messages are in English but may easily be translated into any other language as described in the following.

The first 24 lines of this file define a number of text constants for subse quent inclusion in the error message lines; a technique which drastically reduces the disk and memory requirements of the error messages. Each

constant is identified by a control character, denoted by a A character in the following listing. The value of each constant is anything that fol lows on the same line. All characters are significant, also leading and trailing blanks.

The remaining lines each contain one error message, starting with the error number and immediately followed by the message text. The mes sage text may consist of any characters and may include previously defined constant identifiers (control characters). Appendix E lists the resulting messages in full.

When you translate the error messages, the relation between constants and error messages will probably be quite different from the English ver sion listed here. Start therefore with writing each error message in full, disregarding the use of constants. You may use these error messages, but they will require excessive space. When all messages are translated, you should find as many common denominators as possible. Then define these as constants at the top of the file and include only the con stant identifiers in subsequent message texts. You may define as few or as many constants as you need, the restriction being only the number of control characters.

As a good example of the use of constants, consider errors 25, 26, and 27. These are defined exclusively by constant identifiers, 15 in total, but would require 101 characters if written in clear text.

The TURBO editor may be used to edit the TURBOMSG.OVR file. Con trol characters are entered with the Ctrl-P prefix, i.e. to enter a Ctrl-A (A A) into the file, hold down the < CONTROL> key and press first P, then A. Control characters appear dim on the screen (if it has any video attributes).

TRANSLA TlNG ERROR MESSAGES 329 TRANSLATING ERROR MESSAGES

Notice that the TURBO editor deletes all trailing blanks. The original message therefore does not use trailing blanks in any messages.

Error Message File Listing "A are not allowed "B can not be "C constant "D does not "E expression "F identifier "G file "H here "KInteger "LFile "NIllegal "0 or "?Undefined "Q match "R real "SString "TTextfile "u out of range "V variable "W overflow "X expected "Y type "[Invalid "] pointer 01';' "X 02':' "X 03',' "X 04' (' "X 05')' "X 06' =' "X 07' :=' "X 08' [ '''X 09']' "X 10' . '''X 11' .. '''X 12BEGIN"X 13DO"X 14END"X

330 TURBO Pascal Reference Manual Error Message File Listing

150F"'X 17THEN"'X 18TO"'0 DOWNTO"'X 20Boolean"'E"'X 21"'L"'V"'X 22"'K"'C"'X 23"'K"'E"'X 24"'K"'V"'X 25"'K"'0"'R"'C"'X 26"'K"'0"'R"'E"'X 27"'K"'0"'R"'V"'X 28Pointer"'V"'X 29Record"'V"'X 30Simple"'Y"'X 31Simple"'E"'X 32"'S"'C"'X 33"'S"'E"'X 34"'S"'V"'X 35"'T"'X 36Type"'F"'X 37Untyped"'G"'X 40"'P label 41Unknown"'F"'0 syntax error 42"'P"']"'Y in preceding"'Y definitions 43Duplicate"'F"'0 label 44Type mismatch 45"'C"'U 46"'C and CASE selector"'Y"'D"'Q 470perand"'Y(s)"'D"'Q operator 48"'[ result"'Y 49'" [ "'S length 50"'S"'C length"'D"'Q"'Y 51"'[ subrange base"'Y 52Lower bound > upper bound 53Reserved word 54"'N assignment 55"'S"'C exceeds line 56Error in integer"'C 57Error in"'R"'C 58"'N character in"'F 60"'Cs"'A"'H 61"'Ls and"']s"'A"'H 62Structured"'Vs"'A"'H 63"'Ts"'A"'H

TRANSLA TlNG ERROR MESSAGES 331 Error Message File Listing

64ATs and untypedAGsAAAH 65UntypedAGsAAAH 66I/O A A 67ALs must beAV parameters 68AL componentsABAGs 69A[AOrdering of fields 70Set baseAyAU 7lA[ GOTO 72Label not within current block 73 AP FORWARD procedure(s) 74INLINE error 75 AN use of ABSOLUTE 90 AL not found 9lUnexpected end of source 93 Illegal compiler directive 97Too many nested WITH's 98Memory AW 99CompilerAW

332 TURBO Pascal Reference Manual TURBO SYNTAX Appendix I TURBO SYNTAX

The syntax of the TURBO Pascal language is presented here using the formalism known as the Backus-Naur Form. The following symbols are meta-symbols belonging to the BNF formalism, and not symbols of the TURBO Pascal language:

Means "is defined as". I Means "or". ( ) Enclose items which may be repeated zero or more times.

All other symbols are part of the language. Each syntactic construct is printed in italics, e.g.: block and case-element. reserved words are printed in boldface, e.g.: array and for. actual-parameter:: = expression I variable adding-operator:: = + I-lor I xor array-constant :: = {structured-constant { , structured-constant) ) array-type :: = array [ index-type { , index-type) ] of component-type array-variable :: = variable assignment-statement :: = variable: = expression I function-identifier :: = expression base-type :: = simple-type block:: = declaration-part statement-part case-element:: = case-list: statement case-label:: = constant case-label-list :: = case-label { , case-label} case-list :: = case-list-element ( , case-list-element) case-list-element :: = constant I constant .. constant case-statement:: = case expression of case-element { ; case-element) end I case expression of case-element { ;case-element} else statement { ; statement} end complemented-factor:: = signed-factor I not signed-factor component-type :: = type component-variable :: = indexed-variable I field-designator compound-statement:: = begin statement { ; statement) end conditional-statement:: = if-statement I case-statement

TURBO SYNTAX 333 TURBO SYNTAX

constant:: = unsigned-number 1 sign unsigned-number 1 constant-identifier 1 sign constant-identifier 1 string constant-definition-part :: = const constant-definition { ; constant-definition} ; constant-definition :: =. untyped-constant-definition 1 typed-cons tan t-definition constant-identifier :: = identifier control-character:: = # unsigned-integer 1 A character control-variable :: = variable-identifier declaration-part :: = { declaration-section} declaration-section :: = label-declaration-part 1 constant-definition-part 1 type-definition-part 1 variable-declaration-part 1 procedure-and-function-declaration-part digit:: = 0 11 12 13 14 15 16 17 18 19 digit-sequence :: = digit { digit} empty:: = empty-statement:: = empty entire-variable:: = variable-identifier 1 typed-constant-identifier expression :: = simple-expression { relational-operator simple-expression} factor:: = variable 1unsigned-constant 1(expression) 1 function-designator 1 set field-designator:: = record-variable. field-identifier field-identifier:: = identifier field-list :: = fixed-part 1 fixed-part; variant-part 1 variant-part file-identifier:: = identifier file-identifier-/ist ::= empty I (file-identifier { I file-identifier}) file-type:: = file of type final-value :: = expression fixed-part :: = record-section { ; record-section} for-list :: = initial-value to final-value 1 initial-value downto final-value for-statement :: = for control-variable: = for-list do statement formal-parameter-section :: = parameter-group 1 var parameter-group function-declaration :: = function-heading block; function-designator:: = function-identifier 1 function-identifier

(actual-parameter { I actual-parameter} ) function-heading :: = function identifier: result-type; 1 function identifier (formal-parameter-section

{ I formal-parameter-section } ) : result-type; function-identifier :: = identifier goto-statement:: = goto label hexdigit :: = digit 1AlB 1C 1DIE 1F hexdigit-sequence :: = hexdigit { hexdigit} identifier :: = letter { letter-or-digit} identifier-list :: = identifier { I identifier}

334 TURBO Pascal Reference Manual TURBO SYNTAX if-statement ::= if expression then statement else statement I if expression then statement] index-type:: = simple-type indexed-variable :: = array-variable [ expression { , expression} ] initial-value :: = expression inline-list-element :: = unsigned-integer I constant-identifier I variable-identifier I/ocation-counter-reference inline-statement :: = inline inline-/ist-element { , inline-list-element} label :: = letter-or-digit { letter-or-digit } label-declaration-part :: = label label { , label} ; letter :: = A I B I C I 0 I ElF I G I Hili J I K I LIM I NIOIPIQIRISITIUIVIWIXIYIZI alblcidielflglhliljlklllmi nlolplqlrlsltlulvlwlxlylzl_ letter-or-digit :: = letter I digit location-counter-reference :: = . * I * sign constant multiplying-operator:: = * 1/ I div I mod I and Ishii shr parameter-group :: = identifier-list: type-identifier pointer-type :: = " type-identifier pointer-variable :: = variable procedure-and-function-declaration-part :: = { procedure-or-function-declaration } procedure-declaration :: = procedure-heading block; procedure-heading :: = procedure identifier; I procedure identifier ( formal-parameter-section { , formal-parameter-section } ) ; procedure-or-function-declaration :: = procedure-declaration I function-declaration procedure-statement :: = procedure-identifier I procedure-identifier (actual-parameter { , actual-parameter} ) program-heading ::= ::= program program-identifier file-identifier-list; program:: = program-heading block program-identifier :: = identifier record-constant:: = (record-constant-element { ; record-constant-element } ) record-constant-element :: = field-identifier: structured-constant record-section :: = empty I field-identifier { , field-identifier} : type record-type :: = record field-list end record-variable :: = variable record-variable-list :: = record-variable { , record-variable} referenced-variable :: = pointer-variable" relational-operator:: = = I < > I < = I > = I < I > I in repeat-statement:: = repeat statement { ; statement} until expression repetitive-statement :: = while-statement I repeat-statement I for-statement

TURBO SYNTAX 335 TURBO SYNTAX result-type :: = type-identifier scalar-type :: = (identifier { , identifier} ) scale-factor:: = digit-sequence 1 sign digit-sequence set ::= [set-element} , set-element} ] I [] set-constant ::= [set-constant-element { , set-constant-element } ] I [] set-constant-element :: = constant 1 constant .. constant set-element:: = expression 1 expression .. expression set-type :: = set of base-type sign:: = + 1- signed-factor:: = factor 1 sign factor simple-expression :: = term { adding-operator term} simple-statement:: = assignment-statement 1 procedure-statement 1 goto-statement 1 inline-statement 1 empty-statement simple-type:: = scalar-type 1 subrange-type 1 type-identifier statement:: = simple-statement 1 structured-statement statement-part:: = compound-statement string :: = {string-element} string-element :: = text-string 1 control-character string-type:: = string [ constant] structured-constant:: = constant 1 array-constant 1 record-constant 1 set-constant structured-constant-definition :: = identifier: type = structured-constant structured-statement:: = compound-statement 1 conditional-statement 1 repetitive-statement 1 with-statement structured-type :: = unpacked-structured-type 1 packed unpacked-structured-type subrange-type :: = constant .. constant tag-field :: = empty 1 field-identifier: term :: = complemented-factor { multiplying-operator complemented-factor} text-string :: = '{ character} , type-definition :: = identifier = type type-definition-part :: = type type-definition { ; type-definition} ; type-identifier:: = identifier type :: = simple-type 1 structured-type 1 pointer-type typed-constant-identifier:: = identifier unpacked-structured-type :: = string-type 1 array-type 1 record-type 1 . set-type 1 file-type unsigned-constant :: = unsigned-number 1 string 1 constant-identifier 1 nil unsigned-integer:: = digit-sequence 1 $ hexdigit-sequence unsigned-number:: = unsigned-integer 1 unsigned-real unsigned-real:: = digit-sequence. digit-sequence 1 digit-sequence. digit-sequence E scale-factor 1 digit-sequence E scale-factor

336 TURBO Pascal Reference Manual TURBO SYNTAX un typed-cons tan t-definition :: = identifier = constant variable:: = entire-variable I component-variable I referenced-variable variable-declaration :: = identifier-list: type I identifier-list: type absolute constant variable-declaration-part :: = var variable-declaration { ; variable-declaration } ; variable-identifier :: = identifier variant :: = empty I case-label list : (field-list) variant-part :: = case tag-field type-identifier of variant { ; variant} while-statement:: = while expression do statement with-statement:: = with record-variable-list do statement

TURBO SYNTAX 337 TURBO SYNTAX

Notes:

338 TURBO Pascal Reference Manual ASCII TABLE Appendix J ASCII TABLE

DEC HEX CHAR DEC HEX CHAR DEC HEX CHAR DEC HEX CHAR

0 00 "@ NUL 32 20 SPC 64 40 @ 96 60 I 1 01 "A SOH 33 21 ! 65 41 A 97 61 a 2 02 "B STX 34 22 II 66 42 B 98 62 b 3 03 "C ETX 35 23 # 67 43 C 99 63 c 4 04 "D EOT 36 24 $ 68 44 D 100 64 d 5 05 "E ENQ 37 25 % 69 45 E 101 65 0 6 06 "F ACK 38 26 & 70 46 F 102 66 f 7 07 "G BEL 39 27 I 71 47 G 103 67 g 8 08 "H BS 40 28 ( 72 48 H 104 68 h 9 09 "I HT 41 29 ) 73 49 I 105 69 i 10 OA "J LF 42 2A * 74 4A J 106 6A j 11 OB "K VT 43 2B + 75 4B K 107 6B k 12 OC "L FF 44 2C 76 4C L 108 6C 1 13 OD "M CR 45 2D - 77 4D M 109 6D m 14 OE "N SO 46 2E 78 4E N 110 6E n 15 OF "0 SI 47 2F / 79 4F 0 111 6F 0 16 10 "P DLE 48 30 0 80 50 P 112 70 p 17 11 "Q DCl 49 31 1 81 51 Q 113 71 q 18 12 "R DC2 50 32 2 82 52 R 114 72 r 19 13 "S DC3 51 33 3 83 53 S 115 73 s 20 14 "T DC4 52 34 4 84 54 T 116 74 t 21 15 "U NAK 53 35 5 85 55 U 117 75 u 22 16 "V SYN 54 36 6 86 56 V 118 76 v 23 17 "W ETB 55 37 7 87 57 W 119 77 w 24 18 "X CAN 56 38 8 88 58 X 120 78 x 25 19 "Y EM 57 39 9 89 59 Y 121 79 y 26 lA "Z SUB 58 3A : 90 5A Z 122 7A z 27 IB "[ ESC 59 3B : 91 5B [ 123 7B { 28 lC "\ FS 60 3C < 92 5C \ 124 7C I 29 ID " ] GS 61 3D = 93 5D ] 125 7D } 30 IE "" RS 62 3E > 94 5E " 126 7E - 31 IF " - US 63 3F ? 95 5F - 127 7F DEL

ASCII TABLE 339 ASCII TABLE

Notes:

340 TURBO Pascal Reference Manual KEYBOARD RETURN CODES Appendix K KEYBOARD RETURN CODES

This appendix lists the codes returned from all combinations of keys on the entire IBM PC keyboard, as they are seen by TURBO Pascal. Actu ally, function keys and 'Alt-ed' keys generate 'extended scan codes', but these are turned into 'escape sequences' by TURBO.

To read the escape sequences, you let your read routine check for ESC, and if detected see if there is another character in the keyboard buffer. If there is, an escape code was received, so you read the next character and set a flag to signal that what you got is not a normal character, but the second part of an 'escape sequence'

i r KeyPressed then begin Read(Kbd,Ch) { ch is char if (ch = #27) and KeyPressed then { one more char? } begin Read(Kbd,Ch) FuncKey True; { FuncKey is boolean end end;

The following table lists the return codes as decimal ASCII values. Nor- mal keys only return a single code; extended codes return an ESC (27) followed by one more character.

Key Unshifted Shift Ctrl Alt Fl 27 59 27 84 27 94 27 104 F2 27 60 27 85 27 95 27 105 F3 27 61 27 86 27 96 27 106 F4 27 62 27 87 27 97 27 107 F5 27 63 27 88 27 98 27 108 F6 27 64 27 89 27 99 27 109 F7 27 65 27 90 27 100 27 110 F8 27 66 27 91 27 101 27 111 F9 27 67 27 92 27 102 27 112 FlO 27 68 27 93 27 103 27 113

KEYBOARD RETURN CODES 341 KEYBOARD RETURN CODES

Key Unshifted Shift Ctrl Alt LArr 27 75 52 RArr 27 77 54 UArr 27 72 56 DArr 27 80 50 Home 27 71 55 End 27 79 49 PgUp 27 73 57 PgDn 27 81 51 Ins 27 82 48 Del 27 83 46 Esc 27 27 BackSp 8 8 Tab 9 27 15 RETURN 13 13 10 A 97 65 1 27 30 B 98 66 2 27 48 C 99 67 3 27 46 D 100 68 4 27 32 E 101 69 5 27 18 F 102 70 6 27 33 G 103 71 7 27 34 H 104 72 8 27 35 I 105 73 7 27 23 J 106 74 10 27 36 K 107 75 11 27 37 L 108 76 12 27 38 M 109 77 13 27 50 N 110 78 14 27 49 0 III 79 15 27 24 P 112 80 16 27 25 Q 113 81 17 27 16 R 114 82 18 27 19 S 115 83 19 27 31 T 116 84 20 27 20 U 117 85 21 27 22 V 118 86 22 27 47 W 119 87 23 27 17 X 120 88 24 27 45 Y 121 89 25 27 21 Z 122 90 26 27 44

(Shaded area indicates return codes that require SuperKey.)

342 TURBO Pascal Reference Manual KEYBOARD RETURN CODES

Ke~ Unshifted Shift Ctr1 A1t [ 91 123 27 \ 92 124 28 ] 93 125 29 I 96 126 0 48 41 27 129 1 49 33 27 120 2 50 64 27 3 27 121 3 51 35 27 122 4 52 36 27 123 5 53 37 27 124 6 54 94 30 27 125 7 55 38 27 126 8 56 42 27 127 9 57 40 27 128 * 42 27 114 + 43 43 45 95 31 27 130 61 43 27 131 , 44 60 / 47 63 59 58 96 126

Table K-1: Keyboard Return Codes

KEYBOARD RETURN CODES 343 KEYBOARD RETURN CODES

Notes:

344 TURBO Pascal Reference Manual INSTALLA TION Appendix L INSTALLATION

Terminal Installation

Before you use TURBO Pascal, it must be installed to your particular terminal, i.e. provided with information regarding control characters re quired for certain functions. This installation is easily performed using the program TlNSTwhich is described in this chapter.

After having made a work-copy, please store your distribution diskette safely away and work only on the copy.

Now start the installation by typing TlNST at your terminal. Select Screen installation from the main menu. Depending on your version of TURBO Pascal, the installation proceeds as described in the following two sections.

IBM PC Display Selection

If you use TURBO Pascal without installation, the default screen set-up will be used. You may override this default by selecting another screen mode from this menu:

Choose one of the following displays:

0) Default display mode 1) Monochrome display 2) Color display 80x25 3) Color display 40x25 4) h/w display 80x25 5) h/w display 40x25

Which display (enter no. or AX to exit) -

Figure L-1: IBM PC Screen Installation Menu

INSTALLA TlON 345 Terminal Installation

Each time TURBO Pascal runs, the selected mode will be used, and you will return to the default mode on exit.

Non-IBM PC Installation

A menu listing a number of popular terminals will appear, inviting you to choose one by entering its number:

Choose one of the following terminals:

1 ) ADDS 20/25/30 15) Lear-Siegler ADM-3l 2) ADDS 40/60 16) Liberty 3) ADDS Viewpoint-IA 17) Morrow MDT-20 4) ADM 3A 18) Otrona Attache 5) Ampex 080 19) Qume 6) ANSI 20) Soroc IQ-120 7) Apple/graphics 21) Soroc new models 8) Hazeltine 1500 22) Teletext 3000 9) Hazeltine Esprit 23) Televideo 912/920/925 10) IBM PC CCP/M b/w 24) Visual 200 11) IBM PC CCP/M color 25) Wyse WY-IOO/200/300 12) Kaypro 10 26) Zenith 13) Kaypro II and 4 27) None of the above 14) Lear-Siegler ADM-20 28) Delete a definition

Which terminal? (Enter no. or AX to exit):

Figure L-2: Terminal Installation Menu

If your terminal is mentioned, just enter the corresponding number, and the installation is complete. Before installation is actually performed, you are asked the question:

Do you want to modify the definition before installation?

This allows you to modify one or more of the values being installed as described in the following. If you do not want to modify the terminal definition, just type N, and the installation completes by asking you the operating frequency of your CPU (see last item in this appendix).

346 TURBO Pascal Reference Manual Terminal Installation

If your terminal is not on the menu, however, you must define the re quired values yourself. The values can most probably be found in the manual supplied with your terminal.

Enter the number corresponding to None of the above and answer the questions one by one as they appear on the screen.

In the following, each command you may install is described in detail. Your terminal may not support all the commands that can be installed. If so, just pass the command not needed by typing RETURN in response to the prompt. If Delete line, Insert line, or Erase to end of line is not in stalled, these functions will be emulated in software, slowing screen per formance somewhat.

Commands may be entered either simply by pressing the appropriate keys or by entering the decimal or hexadecimal ASCII value of the com mand. If a command requires the two characters 'ESCAPE' and ' = " may:

either: press first the Esc key, then the =. The entry will be echoed with appropriate labels, i.e. =.

or: enter the decimal or hexadecimal values separated by spaces. Hexa decimal values must be preceded by a dollar-sign. Enter e.g. 27 61 or $1B 61 or $1B $3D which are all equivalent.

The two methods cannot be mixed, i.e. once you have entered a non numeric character, the rest of that command must be defined in that mode, and vOice versa.

A hyphen entered as the very first character is used to delete a com mand, and echoes the text Nothing.

Terminal type: Enter the name of the terminal you are about to install. When you com plete TlNST, the values will be stored, and the terminal name will ap pear on the initial list of terminals. If you later need to reinstall TURBO Pascal to this terminal, you can do that by choosing it from the list.

INSTALLA TlON 347 Terminal Installation

Send an initialization string to the terminal? If you want to initialize your terminal when TURBO Pascal starts (e.g. to download commands to programmable function keys), you answer Y for yes to this question. If not, just hit RETURN.

Send a reset string to the terminal? Define a string to be sent to the terminal when TURBO Pascal ter minates. The description of the initialization command above applies here.

CURSOR LEAD-IN command: Cursor Lead-in is a special sequence of characters which tells your ter minal that the following characters are an. address on the screen on which the cursor should be placed.

When you define this command, you are asked the following supplemen tary questions:

CURSOR POSITIONING COMMAND to send between line and column: Some terminals need a command between the two numbers defining the row- and column cursor address.

CURSOR POSITIONING COMMAND to send after line and column: Some terminals need a command after the two numbers defining the row- and column cursor address.

Column first? Most terminals require the address on the format: first ROW, then COLUMN. If this is the case on your terminal, answer N. If your ter minal wants COLUMN first, then ROW, then answer Y.

OFFSET to add to LINE Enter the number to add to the LINE (ROW) address.

OFFSET to add to COLUMN Enter the number to add to the COLUMN address.

Binary address? Most terminals need the cursor address sent on binary form. If that is true for your terminal, enter Y. If your terminal expects the cursor ad dress as ASCII digits, enter N. If so, you are asked the supplementa ry question:

348 TURBO Pascal Reference Manual Terminal Installation

2 or 3 ASCII digits? Enter the number of digits in the cursor address for your terminal.

CLEAR SCREEN command: Enter the command that will clear the entire contents of your screen, both foreground and background, if applicable.

Does CLEAR SCREEN also HOME cursor? This is normally the case; if it is not so on your terminal, enter N, and define the cursor HOME command.

DELETE LINE command: Enter the command that deletes the entire line at the cursor position.

INSERT LINE command: Enter the command that inserts a line at the cursor position.

ERASE TO END OF LINE command: Enter the command that erases the line at the cursor position from the cursor position through the right end of the line.

START OF 'LOW VIDEO' command: If your terminal supports different video intensities, then define the com mand that initiates the dim video here. If this command is defined, the following question is asked:

START OF 'NORMAL VIDEO' command: Define the command that sets the screen to show characters in 'normal' video.

Number of rows (lines) on your screen: Enter the number of horizontal lines on your screen.

Number of columns on your screen: Enter the number of vertical column positions on your screen.

Delay after CURSOR ADDRESS (0-255 ms): Delay after CLEAR, DELETE, and INSERT (0-255 ms): Delay after ERASE TO END OF LINE and HIGHLIGHT On/Off (0-255 ms): Enter the delay in milliseconds required after the functions specified. RETURN means 0 (no delay).

INSTALLA TION 349 Terminal Installation

Is this definition correct? If you have made any errors in the definitions, enter N. You will then re turn to the terminal selection menu. The installation data you have just entered will be included in the installation data file and appear on the ter minal selection menu, but installation will not be performed. When you enter Y in response to this question, you are asked:

Operating frequency of your microprocessor in MHz (for delays): As the delays specified earlier are depending on the operating frequency of your CPU, you must define this value.

The installation is finished, installation data is written to TURBO Pascal, and you return to the outer menu (see section 12 ). Installation data is also saved in the installation data file and the new terminal will appear on the terminal selection list when you run TINST in future.

Editing Command Installation

The built-in editor responds to a number of commands which are used to move the cursor around on the screen, delete and insert text, move text etc. Each of these functions may be activated by either of two com mands: a primary command and a secondary command. The secondary commands are installed by Borland and comply with the 'standard' set by WordStar. The primary commands are un-defined for most systems, and using the installation program, they may easily be defined to fit your taste or your keyboard. IBM PC systems are supplied with the arrows and dedicated function keys installed as primary commands as described in chapter 19.

When you hit C for Command installation, the first command appears:

CURSOR MOVEMENTS:

1: Character left Nothing -> •

350 TURBO Pascal Reference Manual Editing Command Installation

This means that no primary command has been installed to move the cursor one character left. If you want to install a primary command (in addition to the secondary WordStar-like Ctrl-S, which is not shown here), you may enter the desired command following the -> prompt in either of two ways:

1) Simply press the key you want to use. It could be a function key (for ex ample a left-arrow-key, if you have it) or any other key or sequence of keys that you choose (max. 4). The installation program responds with a mnemonic of each character it receives. If you have a left-arrow-key that transmits an < ESCAPE> character followed by a lower case a, and you press this key in the situation above, your screen will look like this:

CURSOR MOVEMENTS:

1: Character left Nothing -> a C

2) Instead of pressing the actual key you want to use, you may enter the ASCII value(s) of the character(s) in the command. The values of multi ple characters are entered separated by spaces. Decimal values are just entered: 27; hexadecimal values are prefixed by a dollar-sign: $lB. This may be useful to install commands which are not presently available on your keyboard, for example if you want to install the values of a new terminal while still using the old one. This facitity has just been provided for very few and rare instances, because there is really no idea in defining a command that cannot be generated by pressing a key. But it's there for those who wish to use it.

In both cases terminate your input by pressing < RETURN> .Notice that the two methods cannot be mixed within one command. If you have started defining a command sequence by pressing keys, you must define all characters in that command by pressing keys and vise versa.

You may enter a - (minus) to remove a command from the list, or a B to back through the list one item at a time.

INSTALLA TION 351 Editing Command Installation

The editor accepts a total of 45 commands, and they may all be installed to your specification. If you make an error in the installation, like defining the same command for two different purposes, an self-explanatory error message is issued, and you must correct the error before terminating the installation. A primary command, however, may conflict with one of the WordStar-like secondary commands; that will just render the secon dary command inaccessible.

The following table lists the secondary commands, and allows you to mark any primary commands installed by yourself:

CURSOR MOVEMENTS: 1 : Character left Ctrl-S 2: Al terna ti ve Ctrl-H 3: Character right Ctrl-D 4: Word left Ctrl-A 5: Word right Ctrl-F 6: Line up Ctrl-E 7: Line down Ctrl-X 8: Scroll up Ctrl-W 9: Scroll down Ctrl-Z 10: Page up Ctrl-R 11: Page down Ctrl-C 12: To left on line Ctrl-Q Ctrl-S 13: To right on line Ctrl-Q Ctrl-D 14: To top of page Ctrl-Q Ctrl-E 15: To bottom of page Ctrl-Q Ctrl-X 16: To top of file Ctrl-Q Ctrl-R 17: To end of file Ctrl-Q Ctrl-C 18: To beginning of block Ctrl-Q Ctrl-B 19: To end of block Ctrl-Q Gtrl-K 20: To last cursor position Ctrl-Q Ctrl-P

352 TURBO Pascal Reference Manual Editing Command Installation

INSERT & DELETE:

21: Insert mode on/off Ctrl-V 22: Insert line Ctrl-N 23: Delete line Ctrl-Y 24: Delete to end of line Ctrl-Q Ctrl-Y 25: Delete right word Ctrl-T 26: Delete character under cursor Ctrl-G 27: Delete left character ~~28: Alternative: Nothing~~

BLOCK COMMANDS:

29: Mark block begin Ctrl-K Ctrl-B 30: Mark block end Ctrl-K Ctrl-K 31: Mark single word Ctrl-K Ctrl-T 32: Hide/display block Ctrk-K Ctrl-H 33: Copy block Ctrl-K Ctrl-C 34: Move block Ctrl-K Ctrl-V 35: Delete block Ctrl-K Ctrl-Y 36: Read block from disk Ctrl-K Ctrl-R 37: Write block to disk Ctrl-K Ctrl-W

MISC. EDITING COMMANDS:

38: End edit Ctrl-K Ctrl-D 39: Tab Ctrl-I 40: Auto tab on/off Ctrl-Q Ctrl-I 41 : Restore line Ctrl-Q Ctrl-L 42: Find Ctrl-Q Ctrl-F 43: Find & replace Ctrl-Q Ctrl-A 44: Repeat last find Ctrl-L 45: Control character prefix Ctrl-P

Table L-1: Secondary Editing Commands

Items 2 and 28 let you define alternative commands to Character Left and Delete left Character commands. Normally < BS > is the alterna tive to Ctrl-S, and there is no defined alternative to < DEL> . You may install primary commands to suit your keyboard, for example to use the < BS > as an alternative to < DEL> if the < BS > key is more con veniently located. Of course, the two alternative commands must be unambiguous like all other commands.

INSTALLA TlON 353 Editing Command Installation

Notes:

354 TURBO Pascal Reference Manual CP/M PRIMER Appendix M CP/MPRIMER

How to use TURBO on a CP/M system

When you turn on your computer, it reads the first couple of tracks on your CP/M diskette and loads a copy of the CP/M operating system into memory. Each time you re-boot your computer, CP/M also creates a list of the disk space available for each disk drive. Whenever you try to save a file to the disk, CP/M checks to make sure that the diskettes have not been changed. If you have changed the diskette in Drive A without re booting, for example, CP/M will generate the following error message when a disk-write is attempted: BOOS ERROR ON A: RIO

Control will return to the operating system and your work was NOT saved! This can make copying diskette a little confusing for the be ginner. If you are new to CP/M, follow these instructions:

Copying Your TURBO Disk

To make a working copy of your TURBO MASTER DISK, do the follow ing:

1. Make a blank diskette and put a copy of CP/M on it (see your CP/M manual for details). This will be is your TURBO work disk.

2. Place this disk in Drive A:. Place a CP/M diskette with a copy of PIP.COM in Drive B (PIP.COM is CP/M's file copy program that should be on your CP/M diskette. See your CP/M manual for details).

3. Re-boot the computer. Type B: PIP and then press < RETURN>

4. Remove the diskette from Drive B: and insert your TURBO MASTER DISK.

5. Now type: A: =B : * . * [V] and then press < RETURN>

You have instructed PIP it to copy all the files from the diskette in Drive B: onto the diskette in Drive A:. Consult your CP/M manual if any errors occur.

CP/M PRIMER 355 Copying Your TURBO Disk

The last few lines on your screen should look like this:

A> B:PIP *A:=B:*.*[V] COPYING - FIRSTFILE

LASTFILE *

6. Press < RETURN> , and the PIP program will end.

Using Your TURBO Disk

Store your TURBO MASTER DISK in a safe place. To use TURBO PASCAL, place your new TURBO work disk in drive A: and re-boot the system. Unless your TURBO came pre-installed for your computer and terminal, you should install TURBO (see 12 ). When done, type TURBO

and TURBO Pascal will start.

If you have trouble copying your diskette, please consult your CPIM user manual or contact your hardware vendor for CP 1M support.

356 TURBO Pascal Reference Manual APPENDIX N-HELP!!! Common Questions and Answers About Turbo Pascal

This appendix lists a number of the most commonly asked questions and their answers. If you don't find the answer to your question here, you can either call Borland's Technical Support staff, or you can access Com puServe's Consumer Information 24 hours a day and 'talk' to the Borland Special Interest Group. See insert in the front of this manual for details.

GENERAL Q: How do I use the system? A: Please read the manual, specifically Chapter 1. If you must get started immediately do the following: 1. Boot up your operating system. 2. If you have a computer other than an IBM PC, run Tinst to install Turbo for your equipment. 3. Run Turbo. 4. Start programming!

Q: I am having disk problems. How do I copy my disks? A: Most disk problems do not mean you have a defective disk. Specifically, if you are on a CP/M-80 system, you may want to look up the brief CP/M primer on page 355. If you can get a directory of your distribution disk, then chances are that it is a good disk. To make a backup copy of Turbo, you should use a file-by-file copy program like COpy for PC/MS-DOS or PIP for CP/M-80/86. The rea son is that for those of you who have quad density disk drives, you may have trouble using a DISKCOPY type program. These programs are expecting the exact same format for the Source diskette as well as the Destination diskette.

Q: Do I need Turbo to run programs I developed in Turbo? A: No, Turbo can make .COM or .CMD files.

HELP!!! 357 Q: How do I make .COM or .CMD files? A: Type 0 from the main menu for Compiler Options and then select "C" for .COM or .CMD file.

Q: What are the limits on the compiler as far as code and data? A: The compiler can handle up to 64K of code, 64K of data, 64K of stack, and unlimited heap. The object code, however, cannot exceed 64K.

Q: Can DOS interrupt calls $25 (Absolute disk read) and $26 (Absolute disk write) be made from Turbo Pascal? A: Yes. DOS did not implement these DOS services the same as all other calls provided. Therefore, you cannot use the procedures MS-DOS or INTR provided by Turbo Pascal. You can contact Turbo Pascal Techni cal Support for a handout demonstrating how to perform these opera tions, or you can download the information from our Special Interest Group on CompuServe.

Q: I don't get the results I think I should when using Reals and Integers in the same expression. A: When assigning an Integer expression to a Real variable, the expres sion is converted to Real. However, the expression itself is calculated as an integer, and you should therefore be aware of possible integer overflow in the expression. This can lead to surprising results. Take for instance: RealVar := ~o * 1000; First, the compiler multiplies integers 40 and 1000, resulting in 40,000 which gives integer overflow. It will actually come out to -25536 as Integers wrap around. Now it will be assigned to the RealVar as -25536. To prevent this, use either:

RealVar ~o.o *1000; or RealVar := 1.0 * IntVar1 * IntVar2; to ensure that the expression is calculated as a Real.

Q: How do I get a disk directory from my Turbo program? A: Sample procedures for accessing the directory are included in the Turbo Tutor package (see how to order the Turbo Tutor on page 3).

358 TURBO Pascal Reference Manual Q: How much RAM do I need to run Turbo Pascal? A: You'll need at least 48K on a CP/M-80 machine and 128K on a 16-bit or PC-compatible machine.

Q: Are variables initialized automatically in Turbo Pascal? A: Turbo doesn't initialize user-defined variables at runtime. The program mer must initialize a variable before it can be used.

Q: My program runs correctly in memory, but crashes or performs differ ently when I run the .COM file. What's wrong? A: There are several possibilities:

• You are using a variable or data structure that has not been initial ized. • You are going out of bounds on an array or a string and conse quently overwriting something in memory. Set the R compiler direc tive to {$ R + }. • You are using a pointer that has not been properly allocated, which can cause a program to overwrite something in memory. • You are using assembly language externals and Turbo Pascal ver sion 2.0 on MS-DOS, PC-DOS, or CP/M-86. Under these condi tions, external assembly code is not always transferred properly during a compile to disk. It is necessary to compile first in memory, then, without running the program, select the .COM option using the compiler Options menu and recompile. • You may be overwriting memory somehow. Suspect any code that uses 1. MEM or MEMW arrays or pointers 2. absolute variables 3. INLlNE, externals, or interrupt calls 4. FiIIChar or Move statements

Q: How do I assign an integer variable a value of -32768? A: By assigning the integer a value of $8000.

HELP!!! 359 Q: When I change my program into a .CHN/Execute file, the program either hangs, gives a memory allocation error, or gives erroneous results. What am I doing wrong? A: For Chain and Execute to work, you must set the minimum code and data segment to the size of the code and data of the largest program in the Chained or Executed series (on CP/M-80 systems, you must adjust the end address). These settings can be changed using the compiler Options menu.

Q: How do I get a real number printed in non-exponential notation? A: You must use real formatting: Writeln(R:M:3) This means write the value of R, use a field width of 14 characters, 3 of which should be to the right of the decimal point.

Q: When I use FilChar on a string, the string gets messed up. Why? A: Remember that the zero'th byte of a string is used to hold the current length of the string. Immediately after using the FiIIChar routine, you must be sure to set the length byte of your string to the appropriate value.

Q: I have a for loop that writes to the string position using index (str1 [ill. However, when I write out the string, it has its old length. Why? A: When updating the value of a particular index of a string, you must update the length byte. We recommend using the Insert procedure to change the value of a particular character in a string, since all the string manipulation routines in Turbo Pascal automatically change the length of the string.

Q: What is the maximum length of a string in Turbo Pascal? A: 255 characters.

360 TURBO Pascal Reference Manual Q: How do you declare an enumerated type and use it in a for loop? A: Try using this code:

type Num (one,two,three); var Count: Num; begin for count := one to three do Write ('. ') ; end.

Q: How can I access command-line parameters? A: Use the ParamStr and ParamCount functions described in Chapter 16. These functions allow complete access to the command line from your Turbo Pascal program.

Q: When I write my linked list data structure to a disk file, why doesn't it store properly? A: Linked lists are dynamic data structures that can only be properly allocated/represented in memory. In order to store the information in a dynamic data structure to a disk file, you must write a routine that traverses the entire linked list and writes each piece of data to your file. When you read the information back from the file, you must reconstruct your linked list.

Q: I made a file with a text editor, and now I'm trying to read it as a record file and it doesn't work. What's wrong? A: Record files use a different data format from text files. You'll need to write a program to convert your data from text to record files.

Q: How do I get typeahead in a Turbo Pascal program? A: First set the C and U compiler directives to { $ C-} and { $ U- }. This will prevent Turbo Pascal from clearing the keyboard buffer during screen I/O. From now on, whenever you do any reads, you can read one character at a time from the logical device KBD: Read(KBD,ch).

HELP!!! 361 Q: Why can't I read more than one integer/character/real on a line using a repea t loop and a read(ch)? A: The following routine reads an input line of characters, requiring the user to press !El only once. var ch : char; begin repeat read(TRM,ch); { read from the logical device TRM } write(ch) ; until Ch = #13; end You can read from the TAM device, read{TRM,var1), for version 3.0 for standard input, or use the compiler directive { $B-} for version 2.0.

Q: Why can't I read/write from the logical device AUX? A: Turbo Pascal treats the logical device AUX exactly like a text file. Because of the BIOS design, most users find that they have great difficulty trying to write serial communication routines using reads and writes from AUX. We recommend writing your own interrupt service routines to check the status of the serial port before you try doing a read or write.

Q: Why does my program behave differently when I run it several times in a row? A: If you are running programs in Memory mode and use typed constants as initialized variables, these constants will only be initialized right after a compilation, not each time you Run the program because they reside in the code segment. With .COM files, this problem does not exist, but if you still experience different results when using arrays and sets, turn on range checking {$ R + } .

Q: How can I use more than 64K of variables? A: You can expand the amount of data space available to your program by using pointer variables.

Q: How do I compile my program to a .CHN file? A: This cookbook-style recipe shows how to compile MAIN.COM and CHRCOUNT.CHN: 1. Load Turbo Pascal and specify CHRCOUNTas the work file. Enter the program using the editor and return to the main menu. Set the

362 TURBO Pascal Reference Manual mode to CHN file and compile to disk (type OHCO). Write down the code and data sizes (on CP/M-80 systems, write down the end address). 2. Specify MAIN as the work file, enter the program using the editor and return to the main menu. Set the mode to COM file and compile to disk (type OCOC). Write down the code and data sizes (on CP/M-80 systems, write down the end address). 3. Type "0" to display the options menu and specify the largest code and the largest data values (on CP/M-80 systems, specify the highest end address). Recompile MAIN (type C), exit Turbo and run MAIN.COM from the operating system command line. Note that you must always set the code and data values when compiling the main module (unless it uses the most code and data).

For more information about CP/M compiler options, refer to chapters 21 (for CP/M-B6) and 22 (for CP/M-BO).

INSTALLATION 0: I am having trouble installing my terminal! A: If your terminal is not one that is on the installation menu, you must create your own. All terminals come with a manual containing informa tion on codes that control video I/O. You must answer the questions in the installation program according to the information in your hardware manual. The terminology we use is the closest we could find to a standard. Note: most terminals do not require an initialization string or reset string. These are usually used to access enhanced features of a particular terminal; for example, on some terminals you can send an initialization string to make the keypad act as a cursor pad. You can put up to 13 characters into the initialization or reset string. 8087 IMPLEMENTATION 0: Do I need an 8087 chip to use Turbo-87? A: Yes, if you want to compile programs for the 8087 chip, that chip must be in your machine. The standard Turbo compiler, however, is included on the Turbo-87 disk, so you can have it both ways!

0: Is the 8087 version of Turbo Pascal compatible with the 80287 co processor? A: Yes.

HELP!!! 363 Q: I have the 8087 version of the compiler. The program compiles but it doesn't run. Why not? A: For version 2.0 users: Turbo Pascal does not check for the 8087 at compile time; instead, it tries to use it at runtime. If it is not there, Turbo Pascal will wait until you respond. For version 3.0 owners: Turbo Pascal will not allow compilation on a machine without an 8087. If the program is compiled and taken to a machine without an 8087, it will crash.

Q: How fast is the 8087? A: The 8087 version of Turbo performs real-number calculations approxi mately 10 times faster than a non-8087 compiler.

BCD IMPLEMENTATION

Q: Do I need any special equipment to use Turbo-BCD? A: No, but the BCD reals package works on 16-bit implementations of Turbo only.

Q: Is Turbo Pascal with BCD support as fast as the regular Turbo com piler? A: If you are using real numbers, Turbo-BCD will run more slowly than regular Turbo Pascal. Also note that Sin, Cos, Exp, and Ln are not implemented in Turbo-BCD.

Q: Is there a switch in the BCD or 8087 compilers that lets you use regular real number arithmetic? A: No, they are separate compilers.

EDITOR

Q: What are the space limitations of the editor? A: The editor can edit as much as 64K at a time. If this is not enough, you can split your source into more than one file using the $1 compiler directive.

364 TURBO Pascal Reference Manual Q: When I am in the Turbo Pascal Editor and I press carriage return, the cursor returns to column 1 instead of going to the next line. A: In order to create new lines at the end of a file, you must be in Insert mode. So type []ill)]l and try it again.

COMPILE/RUN-TIME/I/O ERRORS

Q: What do I do when I get error 99 (Compiler overflow)? A: You can do two things: break your code into smaller segments and use the $1 compiler directive or compile to a .COM or .CMD file.

Q: What do I do if my object code is going to be larger than 64K? A: Either use the chain facility or use overlays.

Q: My program works well with Turbo 2.0, but now it keeps getting 1/0 Error F3 (or Turbo Access error 243). A: Turbo 3.0 uses DOS file handles. When booting your computer, you should have a CONFIG.SYS file in the root directory of your boot drive. Place the statement: FILES=16 in this file and re-boot your system. For more information about file handles, please refer to your DOS reference manual. NOTE: If you distribute your programs, you should include similar instructions in the documentation that you provide.

Q: What causes the runtime error FO? A: There are four possible causes: 1. a recursive routine that is overlaid 2. a procedure that calls another procedure in the same overlay group 3. calling for an overlay inside a read or write statement, which is not allowed 4. insufficient file handles when calling for an overlay, a .CHN, or an Execute (MS/PC-DOS only).

HELPIII 365 Q: Why do I get an I/O error FO when I try to Append to a text file? A: You cannot use the Append procedure on an empty file. The existing file must have text in it in order to successfully append.

Q: Why am I getting a compile-time error in my type declaration for a large data structure? A: It may be over 64K in size (Turbo's upper limit for the size of a data structure).

Q: Why do I keep getting a type mismatch with the labels I'm using in my case statement? A: You may be trying to use strings as labels in your case statement. Pascal only allows simple types to be used as case statement labels. In addition, the labels must be constants, not variables or typed con stants.

Q: What does compiler error #99 mean, and how can I fix it? A: This compile time error indicates that you do not have enough memory to compile your program. You should take the following steps to correct the problem: 1. Separate your code into several include files that are included in a very small main program file. 2. Compile the program to a .COM file.

Q: Why would I get the I/O error F3? A: Because you are trying to use too many file handles. MS-DOS and PC-DOS limit a program to a maximum number of file handles You can raise the number to 20 using this line in your CONFIG.SYS file: FILES = 20 This will allow you to use up to 16 files in your program (DOS uses 5). When all handles have been used, you must close some files before opening any new ones.

Q: I get a Type Mismatch error when passing a string to a function or procedure as a parameter. A: Turn off type checking of variable parameters: {$V-L

366 TURBO Pascal Reference Manual GRAPHICS

Q: After including GRAPH.P in my program, the commands Plot and Draw no longer work as expected. A: When using GRAPH.P, you must set the Palette before using these routines.

Q: Any idea why I can't get the sample graphics programs on the Turbo Pascal disk to run on my system? A: You must have an IBM Color Graphics Adapter (CGA) card or compati ble in order to use the built-in graphics abilities of Turbo Pascal.

Q: What resolution setting does the Hires graphics mode on the IBM PC version of Turbo Pascal require? A: Hires is set at (640x200).

Q: Will Turbo Pascal's graphics run on the Hercules Graphics card? A: Turbo Pascal's built-in graphics will only run on the IBM Color Graphics Adapter card, or something compatible with this card. To write graphics programs using Turbo with the Hercules card, you can use the Turbo Graphix Toolbox.

Q: Why doesn't my graphics program run on my Paradise Modular Graphics card? A: The graphics routines built into Turbo Pascal and included in the extended graphics (GRAPH.P) will only run on an IBM Color Graphics Adapter card (or compatible).

PRINTING Q: How can I get a listing of my program's input and output to go to the printer? A: To do this, declare the following compiler directive at the top of your program: UP:L2IH before running your .COM file, type "P at the DOS command line.

From now until you type 1\ P again, everything that goes to the screen will be echoed to the printer.

HELPI/I 367 Q: How do I send something to the printer from my program? A: By specifying the logical device LST in your writeln statements, you can send something to the printer: writeln(LST,'This text is going to the printer.'); Q: How can I write to a printer other than PRN? A: In order to support multiple printers from a Turbo Pascal program, you need to treat them as text files. In other words, declare a file variable of type text and assign it to the logical device you wish it to represent.

Q: How do I print my program to the printer? A: We have given you a listing program called LlSTER.PAS on the Turbo Pascal diskette. In order to use it do the following: 1. Compile the program to a .COM file using Turbo Pascal. 2. Exit from Turbo Pascal and run the program LISTER. 3. When it prompts you for the file name you wish to print, enter the correct file.

Q: How can I check if my printer is on-line? A: The following routine will return the printer status. See an IBM Technical Reference Manual or equivalent for detailed information on the Error codes returned. type Registers = record case Byte of 1 : (AX,BX,CX,DX,BP,SI,DI,DS,ES,Flags Integer); 2 : (AL,AH,BL,BH,CL,CH,DL,DH : Byte); end var Reg : Registers; begin Reg. AH : = 2; Intr($17, Reg); PrinterError (Reg.AH and $29) (> 0; end;

368 TURBO Pascal Reference Manual Q: How can I use one Write statement to access any of several printers? A: On the IBM PC and compatibles (only), do the following: First, include the following code in your program: const CurrentPrinter : Byte = 1 { The printer number to print on } procedure WritePrinter(Ch : Char); { Replaces Turbo's LstOut procedure } type Registers = record case Byte of 1 : (AX,BX,CX,DX,BP,SI,DI,DS,ES,Flags Integer); 2 : (AL,AH,BL,BH,CL,CH,DL,DH : Byte); end; var Reg: Registers; begin with Reg do begin AH := 0; AL : = Ord (Ch) ; DX := Pred(CurrentPrinter); Intr($17, Reg); end; { with} end; { WritePrinter }

At the start of your program, insert the statement: LstOutPtr := Ofs(WritcPrinter);

Now, whenever you write to the Lst device in your program, it will print on the printer specified by CurrentPrinter. To change the printer that the text will print on, simply change the value of CurrentPrinter.

Q: How can I tell if my printer is ready to print? A: You can check for the printer's status by polling DOS interrupt 17.

Q: How do I get output to go to the printer? A: Try: Writeln(Lst, ... ).

HELP!!! 369 Q: How can I get a listing of my source code to my printer? A: You can use the following program. If you wish to have a listing that underlines or highlights reserved words, puts in page breaks, and lists all Include files, there is one included free (including source) on the Turbo Tutor diskette. program TextFileDemo; var TextFile : Text; Scratch: String[12BJ; begin Write('File to print: '); { Get file name} Readln(Scratch); Assign(TextFile, Scratch); { Open the file} {$I-} Reset(TextFile) ; {$I+} if IOresult () 0 then Writeln('Cannot find " Scratch) { File not found} else { Print the file .. } begin while not Eof(TextFile) do begin Readln(TextFile, Scratch); { Read a line Writeln(Lst, Scratch) { Print a line end; { while } Writeln(Lst) { Flush printer buffer} end { else } end.

IBM IMPLEMENTATION

Q: How can I get my output to display in inverse video? A: By executing the following statements: begin TextColor(Black); Textbackground(White); end;

Q: When I change the currently active display page, why doesn't Turbo write to the current page? A: Turbo writes directly to video RAM and always assumes that page 0 is the active display page, If you want to display text in different display pages, you will have to either write directly to video RAM (the Turbo Pascal Editor Toolbox and Lightning Word Wizard both have routines to do this), or use DOS's display services.

370 TURBO Pascal Reference Manual Q: Is it possible to execute DOS commands; i.e., do a shell, from Turbo? A: Yes. You can contact Turbo Pascal Technical Support for a handout demonstrating how to perform these operations, or you can download the information from our Special Interest Group on CompuServe.

Q: Is it possible to perform Serial Communications from Turbo? A: Yes. You can contact Turbo Pascal Technical Support for a handout demonstrating how to perform these operations, or you can download the information from our Special Interest Group on CompuServe.

Q: GotoXY isn't working in my program. What am I doing wrong? A: The most common mistake is reversing the row and column coordi nates. They should read as: GotoXY(Column,Row); where 1 (= column (= 80 (on most machines) and 1 (= row (= 25 (or 24 lines on most generic machines)

Q: How do I get the time/date in Turbo Pascal? A: The files DOSFCALL.DOC and INTRPTCL.DOC on your Turbo Pascal disk demonstrate how to get the date and time.

Q: I wrote an interrupt handler, but it doesn't work. Do you mask interrupts during I/O? A: No. You are probably using global variables, but OS has the wrong value after you enter the interrupt procedure. Save the value of OS in the code segment (that is, in a typed constant) and restore it within the interrupt handler.

Q: What interrupt is used by the MS-DOS and PC-DOS implementations of Turbo Pascal to handle the keyboard? A: Turbo Pascal uses interrupt 16 to check the keyboard status.

Q: Does Turbo Pascal 3.0 for the IBM PC use direct screen writes in its editor? A: Yes.

HELP!!! 371 Q: How can I change the border color on a CGA? A: The following program will let you change the border color to blue (substitute any color you wish): begin Port[$3D91 Blue; end;

Q: How can I hide the cursor in Turbo Pascal? A: The following routine turns the cursor on and off in Turbo Pascal: procedure SetCursor(On:Boolean); var reg : record ax,bx,cx,dx,bp,si,di,ds,es,flags:integer; end; begin with reg do begin if On then { turn cursor on } cx := $COB { $706 if on color monitor} else { turn cursor off } cx := $20; bx : = 0; ax := $0100; end; { with } intr($10,reg); end; { procedure SetCursor

Q: How can I find out if the I][) / (][) keys are on? A: The status of these keys is kept in RAM at address $40:$17.

Q: How do I get the I PrISe I key on an IBM PC to work with a Turbo Pascal program? A: To re-enable DOS's standard 1/0 redirection capabilities, the G and P compiler directives must be set in your program: {$P128,G128}

COMPATIBILITY Q: I can't get Turbo Pascal to load on my DEC Rainbow. Why? A: Make sure you are using the DEC format, not the MS-DOS format.

372 TURBO Pascal Reference Manual Q: I'm having trouble running Turbo Pascal on Concurrent PC-DOS. Why? A: We recommend using the MS-DOS generic implementation of Turbo Pascal under Concurrent PC-DOS.

Q: Why can't I get Turbo Pascal to run under Topview? A: You must have Turbo Pascal version 3.01 to use under Topview, and you must install Topview with the following parameters: Does it read directly from the keyboard? Yes. Does it access video RAM directly? Yes.

MS-DOS/PC-DOS Q: How can I use Turbo Pascal to write to DOS's null device? A: Use the following code: va! T : text; begin Assign(T, 'Nul'); Rewrite(T) ; Writeln(T, 'help'); Close(T) ; end.

CP/M-SO Q: Can I use the program I developed under CP/M-SO on my IBM PC? A: Yes, you can, provided there are no machine-specific calls in your code, and that you recompile the source code on an IBM PC implemen tation of Turbo Pascal.

Q: What software do I need to get Turbo Pascal up and running on my Osborne executive computer? A: You need the Osborne version of Turbo Pascal and BIOS revision 1.21 or greater.

Q: How can I get Turbo Pascal 3.0 to run on my Bondwell CP/M-SO computer? A: To run 3.0 on your Bondwell, you will have to contact Bondwell to get a patch to their BIOS.

HELPIII 373 Q: Why do my recursive procedures not work? A: Set the A compiler directive off: { $ A -} (CP/M-80 only).

KEYBOARD Q: Why doesn't the function KeyPressed work properly? A: Any strange behavior you are experiencing concerning the function KeyPressedwil1 be remedied by setting the C compiler directive to C-.

Q: How do I read from the keyboard without having to hit return (duplicate BASIC's INKEY$ function)? A: Like this: read (Kbd, Ch) where Ch:Char.

Q: How do I read a function key? A: Function keys generate 'extended scan codes' which are turned into 'escape sequences' by Turbo; that is, two characters are sent from the keyboard: first an Esc (decimal ASCII value 27), then some other character. To read these extended codes, you check for Esc and, if detected, see if there is another character in the keyboard buffer. If there is, a function key was pressed, so you read the next character and set a flag to signal that what you got is not a normal character, but the second part of an 'escape sequence.' if KeyPressed then begin Read(Kbd,Ch) {ch is char} if (ch = #27) and KeyPressed then {one more char?} begin Read(Kbd,Ch) FuncKey := True; {FuncKey is Boolean} end end;

Q: How do I disable CTRL-C? A: Set compiler directive: {$C-}.

374 TURBO Pascal Reference Manual FILE 1/0 Q: How do I find out if a file exists on the disk?

A: Use UI-} and {I +}, The following function returns True if the file name passed as a parameter exists, otherwise it returns False: type Name=string[bbl;

function Exist(FileName: Name): Boolean; var Fil: file; begin Assign(Fil, FileName); UI-} Reset (Fil) ; UI+ } Exist (IOresult 0) end;

Q: Is there any way to get around the File Handle limitations imposed by DOS? A: Yes. You can contact Turbo Pascal Technical Support for a handout demonstrating how to perform these operations, or you can download the information from our Special Interest Group on CompuServe.

Q: How can I expand my data files to use more than 64K of records? A: See the extended file size section on page 199.

Q: I am having trouble with file handling. What is the correct order of instructions to open a file? A: The correct manner to handle files is as follows: To create a new file: Assign(FileVar,'NameOf.Fil'); Rewrite(FileVar);

Close(FileVar) ; To.open an existing file: Assign(FileVar,'NameOf.Fil'); Reset(FileVar) ;

Close(FileVar) ;

HELP!!! 375 Q: When using the functions EOF and EOLN on a file, my program seems to hang. What's the cause? A: Turbo Pascal adds an extension to the functions EOF and EOLN. This extension lets you pass to the two functions a parameter specifying which file you are checking (for example, EOF(FileVariable)). If you do not specify this optional parameter, then set the 8 compiler directive.

Q: How do you access a file on another disk drive? A: When assigning the drive, make your file name 'B:filename' or use ChdirCB:') (MS/PC-DOS only).

Q: How can I use EOF and EOLN without a file variable as a parameter? A: Turn off buffered input:UB-L

376 TURBO Pascal Reference Manual INDEX

A B A command, 188 B compiler directive, 106, 148, A compiler directive, 131, 137, 314 277,286,318 Back routine, 178 Abs function, 139 Backslash, 188 Absolute address functions, BAKfile, 17 204-205, 237 Base type, 85 Absolute variables, 203-204, BCD, 293-299 236, 261, 267, 291 BOOS, 240, 271 Adding operators, 51, 53 BIOS, 272 Addr function, 204, 237,268 Block commands, 28-30 Allocating variables, 120 BlockRead procedure, 114 And operator, 52 Blocks, 127 Append procedure, 117, 200 BlockWrite procedure, 114 Arc, 173 Boolean scalar type, 42 ArcTan, 139 Brackets, 37 Arithmetic functions, 139-141, Buffer, 220, 235, 250-251, 304 280-281 Array(s), 75-77, 254, 281, 285 Byte scalar type, 41 character, 77 component, 75 constants, 90-91 c internal data formats, 219, C command, 17,190,227,260 224 C compiler directive, 148, 314 multidimensional, 76 Case statement, 58-59 of characters, 112 Chain, 193-194, 231-233 predefined, 77 Char scalar type, 42 subscript optimization, 269 Character arrays, 77 ASCII table, 339 Characters Assign procedure, 94, 98, 101, blinking, 161 106,117 color of, 161 Assignment operator, 37, 55 of string variable, 73 Auto indentation, 31, 35 ChOir procedure, 189 AUX:, 104,220,241,251,273, Chr function, 142 280 Circle routine, 173 AuxlnPtr, 210, 241 Clear screen, in graphics mode, AuxOut, 209 163 AuxOutPtr, 210, 241 Clearscreen routine, 179

INDEX 377 Clipped graphics, 163, 183 D Close procedure, 96, 98 o command, 18, 191, 229 ClrScr procedure, 133 o compiler directive, 201, Code segment size, 191, 228 316-317 Color modes, 161-162 Data conversion, 108 ColorTable routine, 172 Data segment size, 191, 229 Column indicator, editor, 20 Data structures, 219-221 , Command keys, editor, 186 249-252, 281-283 Command line length byte, 265 Data transfer between programs, Command line parameters, 192, 194,231,264 229,262 Data types, basic, 216-218, Comments, 37, 46 246-249,278-281 Compilation, 288-289 Declaration part, 47-48 Compile command, 17 Declared scalar type, 41 Compiler directives, 7, 46, DEL,109 313-318 Delay, 134 Compiler error messages, Delete commands, 27-28 321-324 Delete procedure, 69 Compiler options, 18, 190, 227, Delimiters, 39 259-260 DelUne, 134 Compound statement, 57 Digits, 37 COM1: logical device, 104 Direct memory access, 205-206, Concat,71 238,268 Concatenation, 68 Directories, 187-188 Concurrent CP/M, 229 Directory command, 18 Conditional statement, 57 Directory-related procedures, Control characters, 22, 24-29, 189 34, 45, 341-343 Discriminated unions, 83 Conversion type, 65 Disjunction, set, 87 CON: logical device, 104 Disk file, 220, 250, 282-283 Coordinates, turtle, 177 Disk reset, 15 Copy function, 71 Disk write error, 15 Cos, 139 Dispose procedure, 124-125 CP/M Distribution disk, 8 command line, 232 Div, 52 FCB, 250, 280 DOS command line, 265 function calls, 271 DOS function calls, 208-209 primer, 355-356 Downto,60 CP/M-80, 259-292, 318 Draw procedure, 171 CrtExit, 134 Dseg, 205 Crtlnit, 133 Dynamic variables, 119, 319 Cseg, 205,237 Cursor movement, 22-25, 34 E Cursor position, 162 E (Edit) command, 17

378 TURBO Pascal Reference Manual Editor, Turbo, 19-35 F block commands, 28-30 F command, 192, 230, 262 command keys, 186 F compiler directive, 198-199, compared to WordStar, 34-35 317 cursor movement commands, False, standard identifier, 42 22-26 Field constants, 91-92 exiting, 22, 30 Field list, 79 insert/delete commands, Fields, 79 26-28 File{s) installation, 350 extended file size, 199 miscellaneous commands, identifier, 93 30-34 handle, 220 status line, 19-20 handling routines, 304-305 Element, of set, 85 names, 15, 20, 198, 235, 267 Else statement, 57-58 number open, 198-199 Empty set, 86 of byte, 199 Empty statement, 56 parameters, 128 End address, 261, 292 path,188 EOF function, 97, 107, 115 pointer, 93 Eoln, 102, 109 standard functions, 97-98 Erase procedure, 96, 104, 114, text, 101, 235, 267 ERR:, 200 types, 93-117 ERRORLEVEL test, 135 untyped, 114 Error messages FilePos function, 97, 102, 235 compiler, 321-324 FileSize function, 98, 102, 235 1/0,327-328 Files on distribution disk, 8-9, run-time, 325 293,301 translating, 329-332 FiIIChar procedure, 136 Esc, 109 FiliPattern procedure, 175 EXecute command, 259 FiIIScreen procedure, 175 Execute procedure, 193-194, FiIIShape procedure, 175 231-233,263-265 Find and replace command, Execution 32-33 error messages, 325 Find command, 31 in memory, 290 Flags byte, 251, 281 of a program file, 291-292 Flush procedure, 96, 102, 235, Exist function, 361 267 Exit, 135 For statement, 60 Exiting the editor, 22, 30 Form function, 294 Exp, 140 Formatted writing, 298 Exponents, 278 Forward, reserved word, 145 Expressions, 51-54 Forward declarations, 156 Extended file size, 199 Forward references, 145 Extended graphics, 172-176, 308 Forwd procedure, 179 External, 210-211, 242, 255, 274, Frac function, 140 83,285 Free dynamic memory, 192, 229 External subroutines, 221-222, Free union, 83 252-253,283 Freemem procedure, 125

INDEX 379 Function Ord,142,207,240,270 calls, 208-209, 240 Pos, 72 declarations, 137 Pred,141 designators, 54 Ptr, 207, 240, 270 results, 224, 255, 285 Random, 143 Functions Round,142 CP/M-80 implementation- Sin, 140 specific Sizeof,144 Bdos, 271 Sqr, 141 Bios, 272 Sqrt, 141 Bioshl, 272 Succ, 141 Graphics Swap, 144 GetOotColor, 174 Trunc, 142 Heading, 179 Upcase, 145 Turtle There, 183 16-bit specific Xcor,184 Cseg,205,237 Ycor,184 Oseg, 205, 238 IBM PC implementation Ofs, 205, 237 specific Seg,205,237 WhereX, 162 SSeg, 205, 238 WhereY, 162 MS-DOS specific FilePos, 97, 115,235,267 G FileSize, 98, 115, 235, 267 G compiler directive, 202, 316 SeekEof, 102 Get procedure, 319 SeekEoln, 102 GetOir procedure, 189 standard GetMem procedure, 125 Abs, 139 GetPic procedure, 173 Addr, 204, 237, 268 Global variables, 216, 246 Arctan, 139 Goto statement, 56, 319 Concat,71 GotoXY, 134 Copy, 71 GraphBackground procedure, Cos, 139 166 Eof, 97,115 GraphColorMode procedure, 163 Eoln, 102 Graphics, 163-184 Exp,140 basic, 171 Frac, 140 extended, 172-176 Hi,143 functions, see Functions Int, 140 modes, 163-167 loresult, 116 procedures, see Procedures Keypressed, 143 Turtlegraphics, 177-184 Length,72 windows, 168-170 Ln,140 GraphMode, 164 LO,143 GraphWindow procedure, 169 Maxavail, 126 Memavail, 121, 207, 239, 270 H Odd,141 H command, 190, 227-228, 260

380 TURBO Pascal Reference Manual Halt procedure, 135 Intr procedure, 215, 245 Heading function, 179 10Result, 116 Heap, 121,225,229,255,286, 1/0,108 305 checking, 116-117 Heap control procedures and drivers, 209-21 0 functions, 305 error handling, 116-117, 263, HeapPtr, 225, 226, 255, 257, 314 286,290 error messages, 327-328 Hexadecimal numbers, 43 mode selection, 106-108 Hi function, 143 redirection, 202-203 HideTurtle procedure, 179 Highlighting screen, 14 K HiRes procedure, 164 K compiler directive, 225, 256, Home position, 134 318 Home procedure, 179 Kbd,106 KBD: logical device, 104 Keyboard return codes, I 341-343 I compiler directive KeyPressed function, 143 include file, 16,147-148,314 IBM PC functions, 308 see also L Functions L command, 15 installation, 12, 345 Label declaration part, 47-48 procedures, 308, see also Labels, 56 Procedures Language elements, Identifiers, standard, 38, 43 user-defined,43-46 If statement, 57-58 Large programs, 147-148 Include compiler directives, 16 Ln function, 140 Include files, 147-148 Lo function, 143 Indent, 20, 31 Local variables Initialized variable, 89 as var parameters, 319 In-line machine code, 211-213, in internal formats, 216 243-244, 274-276 Logged drive selection, 15 Inline procedure, 134 Logical devices, 104, 200 Insert commands, 26-27 Log-on message, 10 Insert indicator in editor, 20 LongFilePos function, 193, 199 Insert procedure, 69 LongFileSize function, 193, 199 Installation, 12-13 LongSeek procedure, 193, 199 of editing commands, 13, LowVideo procedure, 135 350-353 Lst,106 of terminal, 345-350 LST: logical device, 104 Int function, 140 LstOut, 209 Integer overflow, 41 LstOutPtr, 210,241 Integer scalar type, 41 Internal data formats, 216-225, 246-256, 278-287 M Intersection, of sets, 85 M command, 16,190,227,260

INDEX 381 Main file selection, 16 Or Operator, 53 Main menu, 11 Ord func, 142 Mantissa, 278 Ordinal values, 142 Mark, 120-124 OUT: logical device, 200 MaxAvail function, 126 Output, 106 Mem, 77 Overflow, 41-42 Mem Array, 204, 238, 268 Overlays, 149-157 Members, of sets, 85 Overwrite mode, 27 Memory access, 206 OvrDrive procedure, 233, 265 Memory management, 226, OvrPath procedure, 196-197 256-257, 288-292 Memory / com file / cHn file, 227 Memory / cmd file / cHn file, 227 p MemW array, 206 P command, 192, 229, 262 Menu, 11, 14-18 P compiler directive, 202, 316 MkDir procedure, 189 Packed variables, 320 Mod,52 Page procedure, 319 Move procedure, 136 Palette procedure, 165 MsDos procedure, 208 Paragraphs, 191 Multidimensional arrays, 76, 91 ParamCount function, 144 Multiplying operator, 51 Parameter passing by reference, 128 by value, 127 N Parameters, 127-131,221-224, Nested overlays, 154 252-254, 283-285 Nesting, of with statements, 81 ParamStr function, 144 New procedure, 120 Path, director, 188 Nil pointer value, 120 Pattern procedure, 176 NormVideo procedure, 135 Pendown procedure, 180 NoSound, 185 Penup procedure, 180 Not operator, 51-52 Plot, 171 NoWrap procedure, 180 Pointer types, 92, 119-126 Numbers, 43-44 Pointer values, 207, 239 Numeric fields, 294-296 Port, 77 Numeric input, 109 Port access, 206, 239, 269 Port array, 193, 206, 238 Pos function, 72 o Pred function, 141 o command, 18, 190-191, Predefined arrays, 77, 206, 238, 227 -228, 259 268 Odd function, 141 Predefined identifiers, 193 Ofs function, 205 Printing, 367-370 Operators, 51,311-312 Procedure and function Options, compiler, 18, 190-193, declaration part, 47, 50 227-230, 259-262 Procedure statement, 56, 127

382 TURBO Pascal Reference Manual Procedure(s), 127-136 MS-DOS CP 1M-specific Append,201 OvrDrive, 233, 265 Erase,96 CP IM-80 implementation Flush, 96, 200-201 specific OvrPath, 196 Bdos, 271 Rename, 96 Bios, 272 Seek,115,235,267 Graphics Truncate, 200 Arc, 173 standard Back,178 Assign, 94 Circle, 173 Chain, 193, 231, 263 ClearScreen, 179 Close, 96 ColorTable, 172 ClrEol,133 Draw, 171 ClrScr, 133 FiIIPattern, 175 CrtExit, 134 FiIIScreen, 175 Crtlnit, 133 FiIIShape, 175 Delay, 134 Forwd,179 Delete, 69 GetPic, 173 Del Line, 134 GraphBackground, 166 Dispose, 124 GraphColorMode, 163 Execute, 193, 231, 263 GraphMode, 164 Exit, 135 GraphWindow, 169 FiIIChar, 136 HideTurtle, 179 FreeMem, 125 HiRes, 164 GetMem, 125 HiResColor, 164 GotoXY, 134 Home, 179 Halt, 135 NoWrap, 180 Insert, 69 Palette, 165 InsLine, 134 Pendown, 180 LowVideo, 135 Plot, 171 Move, 136 PutPic, 174 New, 120 SetHeading, 180 NormVideo, 135 SetPenColor, 181 Randomize, 135 SetPosition, 181 Read,95,108 ShowTurtle, 181 Readln, 101 Turnleft, 181 Reset, 94 Turnright, 181 Rewrite, 94 Turtlewindow, 182 Seek,95 Wrap, 184 Str, 70 IBM PC implementation- Val, 70 specific Write, 95 NoSound, 185 Write In, 101 Pattern, 176 16-bit Sound,185 Intr, 215, 245 TextBackground, 162 Procedural parameters, 320 TextColor, 161 Program, Turbo, contents of, TextMode, 160 47-50 Window, 168 Program lines, 39

INDEX 383 Ptr, 207, 240, 270 Run-time Put procedure, 319 error messages, 325 PutPic, 174 errors, 156-157 range checking, 65 Q Q (Quit) command, 18 s S (Save) command, 17, 261 Scalar functions, 141, 306 R Scalar types, 41-42, 63-64 R (Run) command, 17 Scalars, 216, 223, 247,254,278, R compiler directive, 65, 73, 76, 283 315 Scope Random access files, 221, of identifiers, 49, 131 251-252, 282 of labels, 56 Random function, 143 Screen Randomize procedure, 135 intensity, 161 Range checking, 65 modes, 160-167 ReadLn, 101, 110-111 procedures and functions, 306 Read procedure, 95, 108-109 Sector buffer, 250-251, 280-281 Real scalar type, 42, 217, 223, SeekEof, 102 247,254 SeekEoln, 102 Record Seek procedure, 95, 115, 235, constant, 90-92 267 definition, 79-80 Seg, 204,237 length, 220, 250, 280 Set(s), 218, 224, 241, 248, 251, type, 79-83 254,273,279,280,284 Records, 219, 224, 250, 254, assignments, 88 282,285 constants, 90, 92 RecurPtr, 286 constructors, 86 Recursion, 156, 286 expressions, 86 Relational operators, 51, 53 types, 85-88,218,224 Relative complement, of sets, 85 SetHeading procedure, 180 Release procedure, 120-121, SetPenColor procedure, 181 124,225,255 SetPos:tirm, 181 Rename procedure, 96 , 124, Shared data, 194, 231, 264 225,255 Shl operator, 52 Repeat statement, 61 ShowTurtle procedure, 181 Repetitive statements, 59 Shr operator, 52 Reset procedure, 95 Simple statements, 55 Restore line command, 31 Sin function, 140 Retype facility, 65 Sine, of Num, 140 Rewrite, 94 SizeOf function, 144 RmDir procedure, 189 Sound, 307-308 Root directory, 188 Special symbols, 37 Root program, 191, 228 Square root, 141 Round function, 142 Sqr, 141 Run (R) command, 17 Sqrt, 141

384 TURBO Pascal Reference Manual Stack,225, 255-256,286-287 Translation of error messages, StackPtr, 263, 286, 290 329 Standard files, 105-1 07 Tree-structured directories, 187 Standard identifiers, 38, 193, TRM: logical device, 104 230,263 True, 42 Standard Pascal, compared to Trunc function, 142 Turbo Pascal, 319-320 Truncate procedure, 200 Standard scalar type, 41 Turn Left procedure, 181 Start address, 261 Turn Right procedure, 181 Statement part, 50, 55 TurtleDelay procedure, 183 Statement separator, 55 Turtlegraphics, 177-184, Statements, 55-61 308-309 Static variable, 119 TurtleThere function, 183 Status line, 19-20 Turtle window, 177-178 Str, 70 Turtlewindow procedure, String 182-183 fields, 297 Type checking, 129 input, 109 Type conversion, 65 length,67 Type definition part, 49 Structured statements, 57 Typed constants, 89-92, 216 Structured typed constants, 90 Subprograms, 127 consecutive, 152 u data area, 156 U compiler directive, 315 Subrange type, 64 Unary minus, 51 Succ func, 141 Union, 85 Successor, of Num, 141 discriminated, 83 Swap func, 144 free, 83 Syntax, Turbo, 333-337 Unstructured typed constants, 89-90 Untyped files, 114 Untyped variable parameters, T 130 Tabulator, 35 Upcase, 145 Tag field, 82 User-written I/O drivers, 241, Terminal installation, 12, 345 272-273 Text Usr, 106 files, 101, 160, 200, 221, 235, USR: logical device, 104 252,267,283 UsrlnPtr, 210, 241 input and output, 108 UsrOutPtr, 210,241 mode, 160 Usrln, 209 window, 168 UsrOut, 209 TextBackground, 162 TextColor procedure, 161 TextMode procedure, 160 v TINST,12 V compiler directive, 129, 315 TPA,261 Val procedure, 70 Transfer function, 142, 307 Value, of pointers, 240

INDEX 385 Value parameters, 127, 223-224, 253-254, 283-285 Variable declarations, 49-50 Variable parameter, 129-130, 223,253 Variant part, 83 Variant records, 82 Variables, 49, 119 absolute, 203, 236, 267 w W compiler directive, 269, 318 W command, 15 WhereX, 162 WhereY, 162 While statement, 61 Windows, 168, 307-308 With statement, 81, 206, 239, 269 WordStar compatibility, 13, 350-353 Work file selection, 15-16 Wrap procedure, 184 Write parameters, 112 Write procedure, 95, 111, 139 WriteLn procedure, 113 Writing 8087 reals, 302 Writing BCD reals, 297-298 x X command, 259 X compiler directive, 269, 318 X-coordinate, 163 Xcor, 184 y Y-coordinate, 163 Ycor, 184

16-bit compiler directives, 317 8087, 301-302

386 TURBO Pascal Reference Manual Borland Software

INTERNATIONAL 4585 Scotts Valley Drive, Scotts Valley, CA 95066

Ava.1la.b1e at better deolers nationwide. To order by credit card, call (800) 255-8008; CA (800) 742-1133; CANADA (800) 237-1136. Whether you're running WordStar,® Lotus,® dBASE,® or any other program, SideKick puts all these desktop accessories at your fingertips-Instantly! A full-screen WordStar-like Editor to jot A Monthly Calendar from 1901 through down notes and edit files up to 25 pages 2099. long. Appointment Calendar to remind you A Phone Directory for names, addresses, of important meetings and appointments. and telephone numbers. Finding a name or a A full-featured Calculator ideal for number is a snap. business use. It also performs decimal An Autodialer for all your phone calls. It will to hexadecimal to binary conversions. look up and dial telephone numbers for you. An ASCII Table for easy reference. (A modem is required to use this function.)

All the SideKick windows stacked up over Lotus 1-2-3. Here's SideKick running over Lotus 1-2-3. In the From bottom to top: SideKick's "Menu Window," ASCII SideKick Notepad you'll notice data that's been imported Table, Notepad, Calculator, Appointment Calendar, Monthly directly from the Lotus screen. In the upper right you can Calendar, and Phone Dialer. see the Calculator. The Critics' Choice "In a simple, beautiful implementation of WordStar's "SideKick is by far the best we've seen. It is also block copy commands, SideKick can transport all the least expensive." or any part of the display screen (even an area -Ron Mansfield, ENTREPRENEUR overlaid by the notepad display) to the notepad." "If you use a PC, get SideKick. You'll soon become -Charles Petzold, PC MAGAZINE dependent on it." -Jerry Pournelle, BYTE "SideKick deserves a place in every PC." -Gary Ray, PC WEEK Suggested Retail Price: $84.95 (not copy protected)

Minimum system configuration: IBM PC, Xl, AT, PClr and true compatibles. The IBM PClr will only accept the SideKick not copy protected versions. PC-DOS (MS-DOS) 2.0 or greater. 128K RAM. One disk drive. A Hayes-compatible modem, IBM PClr Internal modem, or AT&T Modem 4000 Is required for the autodialer function.

SideKick is a registered trademark of BorlMacintosh • The most complete and comprehensive collection 01 desk accessories available lor your Macintosh!

Thousands of users already know that SideKick is the best collection of desk accessories available for the Macintosh. With our new Release 2.0, the best just got better.

We've just added two powerful high-performance tools to SideKick-Outlook"': The Outliner and MacPlan"': The Spreadsheet. They work in perfect harmony with each other and while you run other programs! Outlook: The Outliner • It's the desk accessory with more power than a stand-alone outliner • A great desktop publishing tool, Outlook lets you incorporate both text and graphics into your outlines a Works hand-in-hand with MacPlan a Allows you to work on several outlines at the same time MacPlan: The Spreadsheet • Integrates spreadsheets and graphs • Does both formulas and straight numbers • Graph types include bar charts, stacked bar charts, pie charts and line graphs a Includes 12 example templates free! • Pastes graphics and data right into Outlook creating professional memos and reports, complete with headers and footers.

SideKick: The Desktop Organizer, Release 2.0 now includes ~ Outlook: The Outliner ~~~~~~~~~~l::'I.':,.) ';;',',,, ',.!J' ., , , .~,4 41 .', .... " ... ,..... ,.. " ~ MacPlan: The Spreadsheet • 1367~ 5.11'1-' D 1~94'£ $.iluB ,'111 "41.4 ~ Di 2'361~ Tol~llWvfr\l'" Mini word processor I'" I'" " •., .. ~ ,." .. ," '.'").'.1 [J "" ,.,,"(," ~ Calendar • 01 Expf!"Isti ,,,'', .. (] Q31'1iLlbor ~ Phone Log []I "'f.,6~ N~""\I" ~ 621'1i Ovtrh.d ~ Analog clock o ttlB'! Tol.IE"t""" D "" ~ Alarm system a 18.4311 fI,tProhi ~ Calculator ~ Report generator MacPlan does both spreadsheets and business ~ Telecommunications (new version now graphs. Paste them into your Out/oak files and supports XModem file transfer protocol) generate professional reports,

Suggested Retail Price: $99.95 (not copy protected) Minimum system requirements: Macintosh 512K or Macintosh Plus with one disk drive.

SideKick 15 a reQlstered trademark and Outlook and MacPlan are trademarks 01 Borland ==~!~-=-~ BORLAND International. Inc. MaCintosh is a trademark 01 Mcintosh Laboratory. Inc. licensed to Apple V~ INTERNATIONAL Compuler. Inc. Copyright 1987 Borland International [lOA 0264 The Organizer For The Computer Age! Traveling SideKick is BinderWare;" both a binder you take with you when you travel and a software program-which includes a Report Generator-that generates and prints out all the information you'll need to take with you.

Information like your phone list, your client list, you simply punch three holes, fold and clip your address book, your calendar, and your the form into your Traveling SideKick binder, and appointments. The appointment or calendar files you're on your way. Because Traveling SideKick is you're already using in your SideKick~ can auto CAD (Computer-Age Designed), you don't fool matically be used by your Traveling SideKick. You around with low-tech tools like scissors, tape, or don't waste time and effort reentering information staples. And because Traveling SideKick is that's already there. electronic, it works this year, next year, and all the One keystroke prints out a form like your address "next years" after that. Old-fashioned daytime book. No need to change printer paper; organizers are history in 365 days.

What's inside Traveling SideKick What the software program and its Report Generator do for you before you go-and when you get back Before you go: • Prints out your calendar, appointments, addresses, phone directory, and whatever other information you need from your data files AREA CODES AND TRAVEL I CHARTS When you return: • Lets you quickly and easily enter all the new names you obtained while you were away into your THOSE SideKick data files It can also: CALCULATOR IN ONE OF TWO [)U~INESS-CARD·SIZE STORAGE • Sort your address book by contact, POCKETS TRAVELING SIOfKICK SOFTWARE zip code or company name GENERATES. UPDATES. AND PRINTS YOUR ADDRESS AND CAl[NDAR FILES • Print mailing labels • Print information selectively • Search files for existing addresses or calendar engagements *Suggested Retail Price: $69.95

Minimum system configuration: IBM PC, XT, AT, Portable, PC/r, 3270 and true compatibles. PC-DOS (MS-~OS) 2.0 or later. 256K RAM mlmlmum.

·Speclallntroductory offer

SideKick and Traveling SideKick are registered trademarks and BinderWare is a trademark 01 ~~:; BORLAND Bortand tnternational, Inc. tBM, AT, XT, and PCjr are registered trademarks 01 International ~. INTERNATIONAL Business Machines Corp. MS-DOS is a registered trademark 01 Microsoft Corp. BOR 0083 Increased Productivity lor Anyone Using IBM®PCs or Compatibles

SuperKey turns 1,000 keystrokes into 1! Yes, Super Key can record lengthy keystroke sequences and play them back at the touch of a single key. Instantly. Like magic. Say, for example, you want to add a column of figures in 1-2-3.8 Without SuperKey, you'd have to type 5 keystrokes just to get started: @ sum ( . With SuperKey, you can turn those 5 keystrokes into 1. SuperKey keeps your confidential files-CONFIDENTIAL! Time after time you've experienced it: anyone can walk up to your PC and read your confidential files (tax returns, business plans, customer lists, personal letters, etc.). With SuperKey you can encrypt any file, even while running another program. As long as you keep the password secret, only YOU can decode your file correctly. Super Key also implements the U.S. government Data Encryption Standard (DES). SuperKey helps protect your capital investment SuperKey, at your convenience, will make your screen go blank after a predetermined time of screen/keyboard inactivity. You've paid hard-earned money for your PC. SuperKey will protect your monitor's precious phosphor and your investment. SuperKey protects your work from intruders while you take a break Now you can lock your keyboard at any time. Prevent anyone from changing hours of work. Type in your secret password and everything comes back to life-just as you left it.

Suggested Retail Price: $69.95 (not copy protected)

Minimum system configuration: IBM PC, Xl, AT, PClr, and true compatibles. PC·DOS (MS·DOS) 2.0 or greater. 128K RAM. One disk drive.

~~BORLAND =~ -==- I N T ERN A T ION A L

Super Key and SideKick are registered trademarks of Borland International, Inc. IBM, Xl, AI, and PCjr are registered trademarks of Intemational Business Machines Corp. 1·2·3 is a registered trademark of lotus Development Corp. MS-DOS is a registered tradcm.lIk of Microsof1 Corp. BOA 0062B If you use an IBM® PC, you need T U R B 0 Lightning® Turbo Lightning teams up /f you ever write a Turbo Lightning's with the Random House~ word, think a word, or intelligence /els you teact Concise Dictionary to say a word, you need it new words. The more check your spelling as Turbo Lightning you use Turbo Lightning, you typel the smarter it gets Turbo Lightning, using the You can also teach your new 83,OOO-word Random House Turbo Lightning your name, Dictionary, checks your spelling business associates' names, as you type. If you misspell a street names, addresses, word, it alerts you with a beep. correct capitalizations, and any At the touch of a key, Turbo specialized words you use Lightning opens a window on frequently. Teach Turbo top of your application pro Lightning once, and it gram and suggests the correct knows forever. spelling. Just press one key and the misspelled word is Turbo Lightning instantly replaced with the is the engine that correct word. It's that easy! The Turbo Lightning Dictionary powers Bor/and's Turbo Lightning Library'" Turbo Lightning works Turbo Lightning brings hand-in-hand with the electronic power to the Random Random House Thesaurus House Dictionary and Random to give you instant access House Thesaurus. They're at to synonyms your fingertips-even while Turbo Lightning lets you choose you're running other programs. just the right word from a list of Turbo Lightning will also alternates, so you don't say the "drive" soon-to-be-released same thing the same way every encyclopedias, extended time. Once Turbo Lightning thesauruses, specialized opens the Thesaurus window, dictionaries, and many other you see a list of alternate popular reference works. words, organized by parts of You get a head start with this first volume in the Turbo speech. You just select the The Turbo Lightning Thesaurus word you want, press ENTER Lightning Library. and your new word will in And because Turbo Lightning is stantly replace the original a Borland product, you know word. Pure magic! you can rely on our quality, our 60-day money-back guarantee, Suggested Retail Price: $99.95 (not copy protected) and our eminently fair prices.

Minimum system configuration: IBM PC, XT, AT, PCjr, and true compatibles with 2 floppy disk drives. PC·DOS (MS·DOS) 2.0 or greater. 256K RAM. Hard disk recommended.

IBM. Xl. AT. and PClr are registered trademarks of International BUSiness Machines Corp. Turbo Lightning is a reOlstered trademark and Turbo Lightning Library is a trademark of Borland International, Inc Random House is a registered trademark of Random House Inc. BOR 0070A Your Development Toolbox and Technical Reference Manual for Thrbo Lightninge

l I G H T N I N G

Lightning Word Wizard includes complete, commented Turbo Pascal® source code and all the technical information you'll need to understand and work with Turbo Lightning's "engine." More than 20 fully documented Turbo Pascal procedures reveal powerful Turbo Lightning engine calls. Harness the full power of the complete and authoritative Random House® Concise Word List and Random House Thesaurus.

Turbo Lightning's "Reference The ultimate collection of word Manual" games and crossword solvers! Developers can use the versatile on-line The excitement, challenge, competition, examples to harness Turbo Lightning's and education of four games and three power to do rapid word searches. Lightning solver utilities-puzzles, scrambles, spell Word Wizard is the forerunner of the data searches, synonym-seekings, hidden words, base access systems that will incorporate crossword solutions, and more. You and and engineer the Turbo Lightning Librarf your friends (up to four people total) can of electronic reference works. set the difficulty level and contest the high speed smarts of Lightning Word Wizard!

Turbo Lightning-Critics' Choice "Lightning's good enough to make programmers and users cheer, executives of other software companies weep." Jim Seymour, PC Week

"The real future of Lightning clearly lies not with the spelling checker and thesaurus currently included, but with other uses of its powerful look-up engine." Ted Silveira, Profiles "This newest product from Borland has it all." Don Roy, Computing Now!

Minimum IYltem configuration: IBM PC, Xl, AT, PClr, Portable, and true compatlblel. 256K RAM minimum. PC·DOS (MS·DOS) 2.0 or greater. Turbo Lightning software required. Optional-Turbo Pascal 3.0 or greater to edit and compile Turbo PalcallDurce code.

Suggested Retail Price: $69.95 (not copy protected)

Turbo Pascal and TlIbo lIt1rtning are regis~red trademarks and Lightning Word Wizird and TLXbo Lightning library are trademarks 01 Borland International. Inc. Random House is a registered trademark 01 Random House, Inc. IBM, XT, AT. and PC, ire registered trademarks 01 International Business Machines Corp. MS· DOS is a registered trademark 01 Microsoft Corp. BOROO87 A '~~I ~I ® liE IA1ABA'E I'r"~ :.AIASE' The high-performance database manager that's so advanced it's easy to use! Lets you organize, analyze and report information faster than ever before! If you manage mailing lists, customer files, or even your company's budgets-Reflex is the database manager for you! Reflex is the acclaimed, high-performance database manager you've been waiting for. Reflex extends database management with business graphics. Because a picture is often worth a 1000 words, Reflex lets you extract critical information buried in mountains of data. With Reflex, when you look, you see. The REPORT VIEW allows you to generate everything from mailing labels to sophisticated reports. You can use database files created with Reflex or transferred from Lotus 1-2-3," dBASE,· PFS: File," and other applications.

Reflex: the ctltlcs' choice "... if you use a PC, you should know about Reflex ... may be the best bargain in software today." Jerry Pournelle, BYTE "Everyone agrees that Reflex is the best-looking database they've ever seen." Adam B. Green, InloWorld "The next generation of software has officially arrived." Peter Norton, PC Week

Reflex: don't use your PC without it! Join hundreds of thousands of enthusiastic Reflex users and experience the power and ease of use of Borland's award-winning Reflex.

Suggested Retail Price $149.95 (not copy protected)

Minimum system configuration: IBM PC, Xl, AT, and true compatibles. 384K RAM minimum. IBM Color Graphics Adapter, Hercules Monochrome Graphics CArd, or equivalent. PC-DOS (MS-DOS) 2.0 or greater. Hard disk and mouse optional. Lotus 1-2-3, dBASE, or PFS: File optional. Rellex is a trademark of Borland/Analytica klc. Lotus 1·2·3 is a registered trademark of Lotus Development Corporation. dBASE is a registered trademark of Ashton·Tate. PFS: File is a regislered trademark of Software Publishing Corporal ion. IBM, XT, AT, and IBM Color Graphics Adapter are registered trademarks of Interretional Business Machines Corporation. Hercules ~;rJ BORLAND Graphics Card is a trademark of Hercules Computer Technology. MS·DOS is a registered ~ I N T ERN ,A T ION A L trademark of Microsoft Corp. BOR 00668 Copyright 1986 Borland International REFLEX FOR THE MACTM The easy-to-use relational database that thinks like a spreadsheet. Reflex for the Mac lets you crunch numbers by entering formulas and link databases by drawing on-screen lines. 5 free ready-to-use templates are Included on the examples disk:

• A checkbook application. • A client billing application set up for a law office, but easily customized by any professional who bills time. • A parts explosion application that breaks down an object into its component parts for cost analysis.

Reflex for the Mac accomplishes al/ of these tasks without programming-using spreadsheet-like formulas. Some other Reflex for the Mac features are: • Visual database design. • Data types which include variable length text, • "What you see is what you get" report number, integer, automatically incremented and form layout with pictures. sequence number, date, time, and logical. • Automatic restructuring of database files when • Up to 255. fields per record. data types are changed, or fields • Up to 16 files simultaneously open. are added and deleted. • Up to 16 Mac fonts and styles are selectable • Display formats which include General, Decimal, for individual fields and labels. Scientific, Dollars, Percent.

r''''~:::::::~~f ~'='I'~

compo ...nullOOI Compon.ntOfl.leg

AMer opening the "Overview" window, you The link lines you draw e~I.lblish both visual You can have rrultiple windows open draw link lines between databases direclly and electronic relation~hips between your sirooltaneously to view all members 01 a onto your Macintosh screen. databases. linked set-which are interactive and truly relational. .Critic's Choice "... a powerful relational database ... uses a visual approach to information management." Info World "... gives you a lot of freedom in report design; you can even import graphics." A+ MalJazlne "... bridges the gap between the pretty programs and the power programs." Stewart Alsop, PC Leller BORLAND Suggested Retail Price: =wG INTERNATIONAL $99.95* ·Introductory Offer Through 1/15/87 Minimum 'yatem requirement.: 512K Rellex lor the Mac is a trademark 01 BorlandlAnalylica, Inc. Macintosh is a trademar~ 01 Mcintosh laboratory, Inc. and is used with express permission 01 its owner. BOA 0149 REFLEX

Includes 22 "instant templates" covering a broad range 01 business applications (listed below). Also shows you how to customize databases, graphs, crosstabs, and reports. It's an invaluable analytical tool and an important addition to another one 01 our best sellers, Rellex: The Analyst 1.1. Fast-start tutorial examples: Learn Reflexe as you work with practical business applications. The Reflex Workshop Disk supplies databases and reports large enough to illustrate the power and variety of Reflex features. Instructions in eac Reflex Workshop chapter take you through a step-by-step analysis of sample data. You then follow simple steps to adapt the files to your own needs. 22 practical business applications: Workshop's 22 "instant templates" give you a wide range of analytical tools: Administration • Tracking Manufacturing Quality Assurance • Scheduling Appointments • Analyzing Product Costs • Planning Conference Facilities Accounting and Financial Planning • Managing a Project • Tracking Petty Cash • Creating a Mailing System • Entering Purchase Orders • Managing Employment Applications • Organizing Outgoing Purchase Orders Sales and Marketing • Analyzing Accounts Receivable • Researching Store Check Inventory • Maintaining Letters of Credit • Tracking Sales Leads • Reporting Business Expenses • Summarizing Sales Trends • Managing Debits and Credits • Analyzing Trends • Examining Leased Inventory Trends • Tracking Fixed Assets Production and Operations • Planning Commercial Real Estate Investment • Summarizing Repair Turnaround Whether you're a newcomer learning Reflex basics or an experienced "power user" looking for tips, Reflex Workshop will help you quickly become an expert database analyst.

Minimum syslem conl/aurallon: IBM PC, AT, Ind Xl, Ind true compillbill. PC·DOS (MS· DOS) 2.0 or grelter. 3841 RAM minimum. Requlras Renel: TIle Anllyst, Ind IBM Color Graphics Adlpter, Hercules Monochrome Graphics Clrd or lqulYlleni.

Suggested Retail Price: $69.95 (not copy protected)

Reflex is a registered trademark and Reflex Workshop is a trademark 01 Borland/Analytica. Inc. IBM. AT, and XT are registered trademarks 01 International Business Machines Corp. Hercules is a traderM'k 01 Hercules Computer Technology. MS·DOS Is a registered traderM'k 01 Microsoh Corp.

BOROO88A VERSION 3.0 with 8087 support and BCD reals Free MicroCa/c Spreadsheet With Commented Source Code! FEATURES: THE CRITICS' CHOICE: One-Step Compile: No hunting & fishing "Language deal of the century ... Turbo Pascal: expeditions! Turbo finds the errors, takes you it introduces a new programming environment to them, lets you correct them, and instantly and runs like magic." recompiles. You're off and running in -Jeff Duntemann, PC Magazine record time. "Most Pascal compilers barely fit on a disk, but Built-in Interactive Editor: WordStar4!.like Turbo Pascal packs an editor, compiler, linker, easy editing lets you debug quickly. and run-time library into just 39K bytes of Automatic Overlays: Fits big programs into random access memory." small amounts of memory. -Dave Garland, Popular Computing MicroCalc: A sample spreadsheet on your disk "What I think the computer industry is headed with ready-to-compile source code. for: well-documented, standard, plenty of good features, and a reasonable price." IBM8 PC Version: Supports Turtle Graphics, -Jerry Pournelle, BYTE color, sound, full tree directories, window routines, input/output redirection, and much more. LOOK AT TURBO NOW!

5f More than 500,000 users worldwide. 5f Turbo Pascal named "Most Significant Product of the Year" by 5f Turbo Pascal is the de facto industry PC WEEK. standard. 5f Turbo PascaI3.0-the fastest Pascal 5f Turbo Pascal wins PC MAGAZINE'S development environment on the award for technical excellence. planet, period.

Suggested Retail Price: $99.95; CPIM8_80 version without 8087 and BCD: $69.95

Features for 16-bit Systems: 8087 math co-processor support for intensive calculations. Binary Coded Decimals (BCD): eliminates round-off error! A must for any serious business application.

Minimum system configuration: 128K RAM minimum. Includes 8087 & BCD features for 16-bit MS-DOS 2.0 or later and CP/M-86 1.1 or later. CP/M-80 version 2.2 or later 48K RAM minimum (8087 and BCD features not available). 8087 version requires 8087 or 80287 co-processor.

TlIbo Pm is a registered tradernirk of BortInd Intemational. Inc. CPIM is a registered .-ademilrl 01 Digital Rcsea-ch Inc. IBM is a registered trCKlernirt of International Business Machines C

Borland's new Turbo Pascal.for the Mac" is so incredibly fast that it can compile 1,420 lines of source code in the 7.1 seconds it took you to read this! And reading the rest of this takes about 5 minutes, which is plenty of time for Turbo Pascal for the Mac to compile at least 60,000 more lines of source code! Turbo Pascal for the Mac does both Windows and "Units" The separate compilation of routines offered by Turbo Pascal for the Mac creates modules called "Units," which can be linked to any Turbo Pascale program. This "modular pathway" gives you "pieces" which can then be integrated into larger programs. You get a more efficient use of memory and a reduction in the time it takes to develop large programs. Turbo Pascal for the Mac is so compatible with Lisa- that they should be living together Routines from Macintosh Programmer's Workshop Pascal and Inside Macintosh can be compiled and run with only the subtlest changes. Turbo Pascal for the Mac is also compatible with the Hierarchical File System of the Macintosh."

The 21-second Guide to Turbo Pascal for the Mac • Compilation speed of more than 12,000 lines Workshop Pascal (with minimal changes) per minute • Compatibility with Hierarchical File System of • "Unit" structure lets you create programs in your Mac modular form • Ability to define default volume and folder names • Multiple editing windows-up to 8 at once used in compiler directives • Compilation options include compiling to disk or • Search and change features in the editor speed up memory, or compile and run and simplify alteration of routines • No need to switch between programs to compile • Ability to use all available Macintosh memory or run a program without limit • Streamlined development and debugging • "Units" included to call all the routines provided by • Compatibility with Macintosh Programmer's Macintosh Toolbox

Suggested Retail Price: $99.95 (not copy protected)

Minimum system configuration: 256K. One 400K drive.

Turbo Pascal,s a reglslered Ira demark and Turbo Pascal lor the Mac. SideKick lor the Mac. and Aellex lor the Mac are trademarks 01 Borland Inlernational. loc. MaClnlosh is a trademark ot Mclnto~h laboralories. Inc. and licensed to ~$OBORLAND Apple Compuler Wllh liS express permission. lisa is a reglslered trademark 01 Apple Computer. Inc. Inside ~ - INTERNATIONAL Macintosh IS a copyrrghl 01 Apple Computer. Inc BOA 0167 VERSION 2.0 Learn Pascal From The Folks Who Created The Turbo Pascal® Family Borland International proudly presents Turbo Tutor, the perfect complement to your Turbo Pascal compiler. Turbo Tutor is really for everyone- even if you've never programmed before.

And if you're already proficient, Turbo Tutor can sharpen up the fine points. The manual and program disk focus on the whole spectrum of Turbo Pascal programming techniques.

• For the Novice: It gives you a concise history of Pascal, tells you how to write a simple program, and defines the basic programming terms you need to know. o Programmer's Guide: The heart of Turbo Pascal. The manual covers the fine points of every aspect of Turbo Pascal programming: program structure, data types, control structures, procedures and functions, scalar types, arrays, strings, pointers, sets, files, and records. • Advanced Concepts: If you're an expert, you'll love the sections detailing such topics as linked lists, trees, and graphs. You'll also find sample program examples for PC-DOS and Ms-oos.e 10,000 lines of commented source code, demonstrations of 20 Turbo Pascal features, multiple choice quizzes, an interactive on-line tutor, and more!

Turbo Tutor may be the only reference work about Pascal and programming you'll ever need!

Suggested Retail Price: $39.95 (not copy protected)

Minimum system configuration: Turbo Pascal 3.0. PC-DOS (MS-DOS) 2.0 or later. 192K RAM minimum (CP/M-80 version 2.2 or later: 64K RAM minimum). 2VRBO PASCAl. DATABASEltxltsox@ Is The Perfect Complement To Turbo Pascalt) It contains a complete library of Pascal procedures that allows you to sort and search your data and build powerful database applications. It's another set of tools from Borland that will give even the beginning programmer the expert's edge.

THE TOOLS YOU NEED! TURBO ACCESS Using B+ trees: The best way to organize and search your data. Makes it possible to access records in a file using key words instead of numbers. Now available with complete source code on disk, ready to be included in your programs. TURBO SORT: The fastest way to sort data using the QUICKSORT algorithm-the method preferred by knowledgeable professionals. Includes source code. GINST (General Installation Program): Gets your programs up and running on other terminals. This feature alone will save hours of work and research. Adds tremendous value to all your programs. GET STARTED RIGHT AWAY.-FREE DATABASE! Included on every Toolbox diskette is the source code to a working database which demonstrates the power and simplicity of our Turbo Access search system. Modify it to suit your individual needs or just compile it and run. THE CRITICS' CHOICE! liThe tools include a B+ tree search and a sorting system. I've seen stuff like this, but not as well thought out, sell for hundreds of dollars." -Jerry Pournell, BYTE MAGAZINE liThe Turbo Database Toolbox is solid enough and useful enough to come recommended." -Jeff Duntemann, PC TECH JOURNAL

Suggested Retail Price: $69.95 (not copy protected)

Minimum system configuration: 128K RAM and one disk drive (CP/M-80: 48K). 16-blt systems: Turbo Pascal 2.0 or greater for MS-DOS or PC-DOS 2.0 or greater. Turbo Pascal 2.1 or greater for CP/M-86 1.0 or greater. 8-blt systems: Turbo Pascal 2.0 or greater for CP/M-SO 2.2 or greater.

TlIbo Pascal and TlIbo Database Toolbox are registered trademarks 01 Borland International Inc. CP/M Is a registered tradem 01 Diglal Research. Inc. MS-DOS Is a registered trademart 01 Microsoft Corp. BOA 00638 TURBO PASCAL GRAPHIXTootSOX® A Library of Graphics Routines for Use with Turbo Pasca/®

High-resolution graphics for your IBM ~ PC, AT, ®XT, ®PCjr®, true PC compatibles, and the Heath Zenith Z-100:" Comes complete with graphics window management. Even if you're new to Turbo Pascal programming, the Turbo Pascal Graphix Toolbox will get you started right away. It's a collection of tools that will get you right into the fascinating world of high-resolution business graphics, including graphics window management. You get immediate, satisfying results. And we keep Royalty out of American business because you don't pay any-even if you distribute your own compiled programs that include all or part of the Turbo Pascal Graphix Toolbox procedures.

What you get includes: • Complete commented source code on disk. • Full graphics window management. • Tools for drawing simple graphics. • Two different font styles for graphic labeling. • Tools for drawing complex graphics, including • Choice of line-drawing styles. curves with optional smoothing. • Routines that will let you quickly plot functions • Routines that let you store and restore graphic and model experimental data. images to and from disk. • And much, much more ... • Tools allowing you to send screen images to Epson®-compatible printers.

"While most people only talk about low-cost personal computer software, Borland has been doing something about it. And Borland provides good technical support as part of the price." John Markov & Paul Freiberger, syndicated columnists. If you ever plan to create Turbo Pascal programs that make use of business graphics or scientific graphics, you need the Turbo Pascal Graphix Toolbox. Suggested Retail Price: $69.95 (not copy protected)

Minimum system configuration: IBM PC, Xl, AT, PCjr, true compatibles and the Heath Zenith Z-100. Turbo Pascal 3.0 or later. 192K RAM minimum. Two disk drives and an IBM Color Graphics Adapter (eGA), IBM Enhanced Graphics Adapter (EGA), Hercules Graphics Card or compatible.

Turbo Pascal and Turbo Graphix Toolbox are registered trademarks 01 Borland International, Ilic. 10M. XT, AT, and PCjr are registered trademarks ollnternationat BUSiness Machines Corporal Ion. Hercules Graphics Card is a trademark 01 Hercules Computer Technology. Heath Zenith Z·100 is a trademark 01 Zenith Data Systems. Epson is a registered trademark 01 [pson Corp. BOA 0068B 2VRBO PASCAl. EDllOR2tntBOX'M It's All You Need To Build Your Own Text Editor Or Word Processor Build your own lightning-fast editor and incor Create your own word processor. We provide all porate it into your Turbo Pasca/~ programs. the editing routines. You plug in the features you want. Turbo Editor Toolbox gives you easy-to-install You could build aWordStar~ -like editor with pull-down modules. Now you can integrate a fast and powerful menus like Microsoft's~ Word, and make it work as fast editor into your own programs. You get the source as WordPerfect.~ code, the manual, and the know-how. To demonstrate the tremendous power of Turbo Editor Toolbox, we give you the source code for two sample editors: Simple Editor A complete editor ready to include in your programs. With windows, block commands, and memory-mapped screen routines. MicroStar A full-blown text editor with a complete pull-down menu user interface, plus a lot more. Modify MicroStar's pull-down menu system and include it in your Turbo Pascal programs.

The Turbo Editor Toolbox gives you all the standard features you would expect to find in any word processor: • Wordwrap • UN-delete last line • Auto-indent • Find and Find/Replace with options • Set left and right margin • Block mark, move, and copy • Tab, insert and overstrike modes, centering, etc. MicroStar's pull-down menus.

And Turbo Editor Toolbox has features that word processors selling for several hundred dollars can't begin to match. Just to name a few: @' RAM-based editor. You can edit very large @' Multiple windows. See and edit up to eight files and yet editing is lightning fast. documents-or up to eight parts of the same @' Memory-mapped screen routines. In document-all at the same time. stant paging, scrolling, and text display. @' Multitasking. Automatically save your @' Keyboard installation. Change control text. Plug in a digital clock, an appointment keys from WordStar -like commands to any that alarm-see how it's done with MicroStar's you prefer. "background" printing. Best of all, source code is included for everything in the Editor Toolbox. Suggested Retail Price: $69.95 (not copy protected)

Minimum system configuration: IBM PC, XT, AT, 3270, PCjr, and true compatibles. PC-DOS (MS-DOS) 2.0 or greater. 192K RAM. You must be using Turbo Pascal 3.0 for IBM and compatibles.

Turbo Pascal IS a registered trademark and Turbo Editor TOOlbox IS a trademark of Borland International. Inc WordStar is a registered trademark 01 MlcroPro International Corp Word and = ,~O BORLAND MS-DOS are registered trademarks 01 Microsoft Corp WordPerfect is a trademark of Satellite INTERNATIONAL Software International IBM. XT. AT. and per are registered trademarks of International Business Machines Corp BOR 0067A ®

Secrets And Strategies 01 The Masters Are Revealed For The First Time Explore the world of state-of-the-art computer games with Turbo GameWorks. Using easy-to-understand examples, Turbo GameWorks teaches you techniques to quickly create your own computer games using Turbo Pascal.1t Or, for instant excitement, play the three great computer games we've Included on disk-compiled and ready to run. TURBO CHESS Test your chess-playing skills against your computer challenger. With Turbo GameWorks, you're on your way to becoming a master chess player. Explore the complete Turbo Pascal source code and discover the secrets of Turbo Chess. "What impressed me the most was the fact that with this program you can become a computer chess analyst. You can add new variations to the program at any time and make the program play stronger and stronger chess. There's no limit to the fun and enjoyment of playing Turbo GameWorks Chess, and most important of all, with this chess program there's no limit to how it can help you improve your game." -George Koltanowskl, Dean of American Chess, former President of the United Chess Federation, and syndicated chess columnist. TURBO BRIDGE

Now play the world's most popular card game-bridge. Play one-on-one with your computer or against up to three other opponents. With Turbo Pascal source code, you can even program your own bidding or scoring conventions. "There has never been a bridge program written which plays at the expert level, and the ambitious user will enjoy tackling that challenge, with the format already structured in the program. And for the inexperienced player, the bridge program provides an easy-to-follow format that allows the user to start right out playing. The user can 'play bridge' against real competition without having to gather three other people." -Kit Woolsey, writer of several articles and books on bridge, and twice champion of the Blue Ribbon Pairs. TURBO GO-MOKU Prepare for battle when you challenge your computer to a game of Go-Moku-the exciting strategy game also known as Pente.- In this battle of wits, you and the computer take turns placing X's and D's on a grid of 19X19 squares until five pieces are lined up in a row. Vary the game if you like, using the source code available on your disk. Suggested Retail Price: $69.95 (not copy protected)

Minimum system configuration: IBM PC, Xl, AT, Portable, 3270, PClr, and true compatibles. PC·DOS (MS·DOS) 2.0 or lator. 192K RAM minimum. To edit and compUe the Turbo Pascal source codo, you must be using Turbo Pascal 3.0 for IBM PC. and compatibles.

~ 0 BORIiiI a IiUiIR Turbo PmJI Jnd Turbo GameWorks are re~stered trademarks of Borland Internahonai. Inc...... Penle is a reglslered trademark of Parker Brothers. IBM. XT. AT. and PCjr are registered $ I N T ERN A T ION A L trademarks 01 International Business Machires Corporation. MS-DOS is a registered trademark of MlcrosoM Corporation. BOR 00656 TURBO PASCAL IIUIEBICAlIE1HIIIIS 11111lllllTM New from Borland's Scientific & Engineering Division! A complete collection 01 Turbo Pascaf routines and programs New from Borland's Scientific & Engineering Division, Turbo Pascal Numerical Methods Toolbox implements the latest high-level mathematical methods to solve common scientific and engineering problems. Fast. So every time you need to calculate an integral, work with Fourier Transforms or incorporate any of the classical numerical analysis tools into your programs, you don't have to reinvent the wheel. Because the Numerical Methods Toolbox is a complete collection of Turbo Pascal routines and programs that gives you applied state-of-the-art math tools. It also includes two graphics demo programs, Least Squares Fit and Fast Fourier Transforms, to give you the picture along with the numbers. The Numerical Methods Toolbox is a must for you if you're involved with any type of scientific or engineering computing. Because it comes with complete source code, you have total control of your application. What Numerical Methods Toolbox will do lor you now: • Find solutions to equations • Matrix operations: inversions, determinants • Interpolations and eigenvalues • Calculus: numerical derivatives and • Differential equations integrals • Least squares approximations • Fourier transforms 5 free ways to look at "Least Squares Fit"! As well as a free demo "Fast Fourier Transforms," you also get "Least Squares Fit" in 5 different forms-which gives you 5 different methods of fitting curves to a collection of data points. You instantly get the picture! The 5 different forms are: 1. Power 4. 5-term Fourier 2. Exponential 5. 5-term 3. Logarithm Polynomial They're all ready to compile and run "as is." To modify or add graphics to your own programs, you simply add Turbo Graphix Toolbox fll to your software library. Our Numerical Methods Toolbox is designed to work hand-in-hand with our Turbo Graphix Toolbox to make professional graphics in your own programs an instant part of the picture!

Suggested retail price: $99.95

Minimum system configuration: IBM PC, XT, AT and true compatibles. PC-DOS (MS-DOS) 2.0 or later. 256K. Turbo Pascal 2.0 or later. The graphics modules require a graphics monitor with an IBM CGA, IBM EGA, or Hercules compatible adapter card, and require the Turbo Graphix Toolbox. MS-DOS generic version will not support Turbo Graphix Toolbox routines. An 8087 or 80287 numeric co-processor is not required, but recommended for optimal performance.

Turbo Pascal Numerical Melhods Toolbox is a Irademark and Turbo Pascal and Turbo Graphix Toolbox are registered trademarks 01 Borla'ld Inlernational, Inc. IBM, XT. and AT are ~:'BORLAND registered trademarks 01 Internationat Busiress Machines Corp. MS-DOS is a registered ~ INTERNATIONAL trademark 01 Microsoft Corp. Hercules is a trademark 01 Hercules Computer Technology. Apple is a registered Irademark 01 Apple Compuler, Inc. Macintosh is a trademark at Mcintosh Laboratory, Inc. licensed to Apple Computer. Copyright 1986 Borland International BOA 0219 TURBO

the natural language of ArtiflCiallntel6gence Turbo Prolog brings filth-generation supercomputer power to your IBM8PC! Turbo Prolog takes Turbo Prolog provides programming into a new, a fully integrated pro natural, and logical gramming environment environment like Borland's Turbo Pascal,® the de facto With Turbo Prolog, worldwide standard. because of its natural, logical approach, both You get the complete people new to programming Turbo Prolog program and professional programmers ming system can build powerful applica You get the 200-page tions such as expert systems, manual you're holding, customized knowledge software that includes bases, natural language the lightning-fast Turbo interfaces, and smart Prolog six-pass information management systems. compiler and interactive editor, and the free GeoBase natural query language Turbo Prolog is a declarative language database, which includes commented which uses deductive reasoning to solve source code on disk, ready to compile. programming problems. (GeoBase is a complete database designed and developed around U.S. Turbo Prolog's development system geography. You can modify it or use it lias is.") includes: A complete Prolog compiler that is a variation of the o Minimum system configuration: IBM PC, Xl, Al, Clocksin and Mellish Edinburgh standard Prolog. Portable, 3270, PCjr, and true compatibles. PC·DOS D A full-screen interactive editor. (MS·DOS) 2.0 or later. 384K RAM minimum. o Support for both graphic and lext windows. o All the tools that leI you build your own expert systems and AI applications with unprecedented ease. Suggested Retail Price $99.95 (Not Copy Protected)

Turbo Prolog is a trademark and Turbo Pascal is a reg,stered Irademark 01 Borland International, Inc. IBM AT. Xl, and PCjr are reglslered trademarks 01 IlItcrnalional Business Machines Corp. MS-DOS is a registered trademark 01 Microsoft Corp. BOR 0016C TBRIII IABIC® The high-speed BASIC you've been waiting lor!

You probably know us for our Turbo Pasca/~ and Turbo Prolog:- Well, we've done it again! We've created Turbo Basic, because BASIC doesn't have to be slow.

If BASIC taught you how to walk, Turbo Basic will teach you how to run! With Turbo Basic, your only speed is "Full Speed Ahead"! Turbo Basic is a complete development environment with a lightning fast compiler, an interactive editor and a trace debugging system. And because Turbo Basic is also compatible with BASICA, chances are that you already know how to use Turbo Basic. Turbo Basic ends the basic confusion There's now one standard: Turbo Basic. And because Turbo Basic is a Borland product, the price is right, the quality is there, and the power is at your fingertips. Turbo Basic is part of the fast-growing Borland family of programming languages we call the "Turbo Family." And hundreds of thousands of users are already using Borland's languages. So, welcome to a whole new generation of smart PC users! Free spreadsheet included with source code! Yes, we've included MicroCalc, our sample spreadsheet, complete with source code. So you can get started right away with a "real program." You can compile and run it "as is," or modify it.

A technical look at Turbo Basic B Full recursion supported executable program, with separate windows B Standard IEEE floating-point format for editing, messages, tracing, and execution B Floating-point support, with full 8087 B Compile and run-time errors place you in coprocessor integration. Software emulation source code where error occurred if no 8087 present B Access to local, static and global variables B Program size limited only by available B New long integer (32-bit) data type memory (no 64K limitation) B Full 80-bit precision B EGA and CGA support B Pull-down menus B Full integration of the compiler, editor, and B Full window management

Suggested retail price: $99.95 (not copy protected)

Minimum system configuration: IBM PC. AT. XT or true compatibles. 256K One Iloppy drive PC-DOS (MS-DOS) 2.0 or later.

Turbo Basic and Turbo Pascal are registered trademarks and Turbo Prolog is a trademark of Borland Internallonal. Inc. IBM. AT. and XT are registered trademarks 01 International Business Machines Corp MS-DOS is a registered trademark 01 MicrosoH Corp. Copyright 1986 Borland International BOA 0265 EIIREIA: ll1E B'f"EB~ The solution to your most complex equations-in seconds!

If you're a scientist, engineer, financial analyst, student, teacher, or any other professional working with equations, Eureka: The Solver can do your Algebra, Trigonometry and Calculus problems in a snap. Eureka also handles maximization and minimization problems, plots functions, generates reports, and saves an incredible amount of time. Even if you're not a computer specialist, Eureka can help you solve your real-world mathematical problems fast, without having to learn numerical approximation techniques. Using Borland's famous pull-down menu design and context-sensitive help screens, Eureka is easy to learn and easy to use-as simple as a hand-held calculator. X + exp(X) = 10 solved instantly instead of eventually! Imagine you have to "solve for X," where X + exp(X) = 10, and you don't have Eureka: The Solver. What you do have is a problem, because it's going to take a lot of time guessing at "X." With Eureka, there's no guessing, no dancing in the dark-you get the right answer, right now. (Ps: X = 2.0705799, and Eureka solved that one in .4 of a second!) How to use Eureka: The Solver It's easy. You can then tell Eureka to 1. Enter your equation into the • Evaluate your solution full-screen editor • Plot a graph 2. Select the "Solve" command • Generate a report, then send the output 3. Look at the answer to your printer, disk file or screen 4. You're done • Or all of the above

Some of Eureka's key features Eureka: The Solver includes You can key in: ~ A full-screen editor ~ A formula or formulas ~ Pull-down menus ~ A series of equations-and solve for ~ Context-sensitive Help all variables ~ On-screen calculator ~ Constraints (like X has to be ~ Automatic 8087 math co-processor < or = 2) chip support ~ A function to plot ~ Powerful financial functions ~ Unit conversions ~ Built-in and user-defined math and ~ Maximization and minimization problems financial functions ~ Interest Rate/Present Value calculations ~ Ability to generate reports complete with ~ Variables we call "What happens?," like plots and lists "What happens if I change this variable to ~ Polynomial finder 21 and that variable to 271" ~ Inequality solutions

Minimum system requirements: IBM PC, AT, Xl, Portable, Suggested retail price: $99.95* 3270 and true compatibles. PC· DOS (MS-DOS) 2.0 and later. 384K. (not copy protected)

Eureka The Solver is a trademark of Borlend International, Inc. IBM. AT, and XT are registered trademarks of International Business Machnes Corp. MS-DOS is a registered trademark of M,crosolt Corp. Copyright 1986 Borland International BOA 0221 'InlroduCIOIY p"ce expires July 1. 1987 - Borland - Software OllDBll fODAY ~------~ II BORLAND II =1"-INTERNATIONAL , I 4585 Scotts Valley Drive Scotts Valley, California 95066 I . ~ I I To Orde~ t'" ~, California By Credit call I Card,. ' ... ;' (800) I Call (800) 742-1133 I 255-8008 In Canada call I -.. (800) 237-1136 1.. ______

EDITOR QUICK REFEREnCE

~ LINE UP 1f ~~9~ CHARACTER _ n~ CHARACTER WORD LEFT ~ RIGHT RIGHT ~ LINE DOWN

~ PAGE DOWN

'I' ' • l' ~"" Jf liI!"-~\' DE·G"~7Ie·<·'::'~:~~: "I~ . FInD 1 f3LOCk (Ctri)~ DELETECHARACTERI,Ctrl~----. Q~ FA FIND I~+-+~ (Ctrl T '1 Q~ DELETE WORD IlCtrl A./l FIND & CHANGE I ~ ~I~NG MARK END (Ctrl Y I), DELETE LINE I (Ctrl ~L 'l REPEAT LAST FIND I Ctrl) K T~ MARK WORD J K C.I OPTIONS: U -UPPER/LOWER CASE I. Ctrl COPY BLOCK I W-WHOLE WORDS ONLY (Ctrl K V '1 MOVE BLOCK I B -BACKWARDS ( Ctrl K Y G -GLOBAL DELETE BLOCK I N -NO qUESTION

(Ctrl rEID END EDIT FEll TunES: THE CRITICS' CHOICE: One-Step Compile: No hunting &fishing "Language deal of the century ... Turbo expeditions! Turbo finds the errors, takes you Pascal: it introduces a new programming to them, lets you correct them, and instantly environment and runs like magic." recompiles. You're off and running in record -Jeff Duntemann, PC Magazine time. "Most Pascal compilers barely fit on a disk, Built-in Interactive Editor: WordStar~like but Turbo Pascal packs an editor, compiler, easy editing lets you debug quickly. linker, and run-time library into just 39K bytes Automatic Overlays: Fits big programs into of random access memory." small amounts of memory. -Dave Garland, Popular Computing MicroCalc: A sample spreadsheet on your "What I think the computer industry is disk with ready-to-compile source code. headed for: well-documented, standard, IBMe PC Version: Supports Turtle Graphics, plenty of good features, and a reasonable color, sound, full tree directories, window price." routines, input/output redirection, and -Jerry Pournelle, BYTE much more. LOOIC IlT TUnaO [Jot"!!

5l' More than 500,000 users worldwide. 5l' Turbo Pascal named "Most Significant Product of the Year" by 5l' Turbo Pascal is the de facto industry PC WEEK. standard. 5l' Turbo Pascal 3.0-the fastest Pascal 5l' Turbo Pascal won PC MAGAZINE'S development environment on the award for technical excellence. planet, period.

Options for 16-8it Systems: 8087 math co-processor support for intensive calculations. Binary Coded Decimals (BCD): eliminates round-off error! A must for any serious business application. (No additional hardware required.)

Minimum System Configuration: Turbo Pascal 3.0 requires 64K RAM, one disk drive, Z80, 8088/86, 80186, or 80286 microprocessor running either CP/M-80 2.2 or greater, CP/M-86 1.1 or greater, MS-DOS 2.0 or greater, or PC-DOS 2.0 or greater.

4585 SCOTTS VALLEY DRIVE '.,I INTERNATIONAL SCOTTS VALLEY, CALIFORNIA 95066

Turbo Pascal is a registered trademark and MicroCalc is a trademark of Borland International, Inc. CP/M is a registered trademark 01 Digital Research Inc. IBM is a registered trademark of International Business Machines Corp, MS-DOS is a registered trademark of Microsoft Corp. zao is a registered trademark of Zilog Corp I S 8 N 0 - 8 7 5 2 4 - 0 0 3 - 8 WordStar is a registered trademark of MicroPro International. BOR 0017 EDITOR QUICK REFEREnCE

BaIAttO I~.. , INrINUIrIONAL

~ LINE UP 1r ~~9~ CHARACTER _ n~ CHARACTER WORD LEFT ~ RIGHT RIGHT ~ LINE DOWN

~ PAGE DOWN

DtEE~f:E" ';".':" 'r~~1 '" FInD ' ' • ..;f1~ ""'; J, BLQCI{ , .- """. ,( . " (Ct;l GJ DELETE CHARACTER ICCtriXQYF~ fiND I~~~ ( Ctrl T f), DELETE WORD J\... Ctrl ~ Q A./l fiND &. CHANGE I MARK BEGINNING MARK END --..~,...... ( Ctrl Y I} DELETE LINE I (Ctrl (L REPEAT LAST fiND J Ctrl.l K T./, MARK WORD I OPTIONS: U -UPPER/LOWER CASE \",Ctrl K C.....: COPY BLOCK J W-WHOLE WORDS ONLY (Ctrl K V 1 MOVE BLOCK B -BACKWARDS I (Ctrl K Y G -GLOBAL DELETE BLOCK J N -NO QUESTION

(Ctrl ryx:I;!) END EDIT FEll TUnES: THE CnITICS' CHOICE: One-Step Compile: No hunting &fishing "Language deal of the century ... Turbo expeditions! Turbo finds the errors, takes you Pascal: it introduces a new programming to them, lets you correct them, and instantly environment and runs like magic." recompiles. You're off and running in record -Jell Duntemann, PC Magazine time. "Most Pascal compilers barely fit on a disk, Built-in Interactive Editor: WordStar~like but Turbo Pascal packs an editor, compiler, easy editing lets you debug quickly. linker, and run-time library into just 39K bytes Automatic Overlays: Fits big programs into of random access memory." small amounts of memory. -Dave Garland, Popular Computing MicroCalc: A sample spreadsheet on your "What I think the computer industry is disk with ready-to-compile source code. headed for: well-documented, standard, IBM ~ PC Version: Supports Turtle Graphics, plenty of good features, and a reasonable color, sound, full tree directories, window price." routines, input/output redirection, and -Jerry Pournelle, BYTE much more. LOOI{ liT Tunno fJOt'll

@' More than 500,000 users worldwide. @' Turbo Pascal named "Most Significant Product of the Year" by @' Turbo Pascal is the de facto industry PC WEEK. standard. @' Turbo Pascal 3.0-the fastest Pascal @' Turbo Pascal won PC MAGAZINE'S development environment on the award for technical excellence. planet, period.

Minimum System Configuration: Turbo Pascal 3.0 requires 64K RAM, one disk drive, l80, 8088/86, 80186, or 80286 microprocessor running either CP/M-80 2.2 or greater, CP/M-86 1.1 or greater, MS-DOS 2.0 or greater, or PC-DOS 2.0 or greater.

4585 SCOTTS VALLEY DRIVE

INTERNATIONAL SCOTTS VALLEY, CALIFORNIA 95066

Turbo Pascal is a registered trademark and MicroCalc is a trademark of Borland International, Inc. CP/M is a registered trademark of Digital Research Inc. IBM is a registered trademark of International Business Machines Corp. MS-DOS is a registered trademark of Microsoft Corp. ZSO is a registered trademark of Zilog Corp. I S BN 0 - 8 7 5 2 4 - 0 0 3 - 8 'MlrdStar is a registered trademark of MicroPro International. BOR0017