;
                       Help for Turbo Pascal (v3.0)                           

A- Introduction                         / Logical Devices   
B- Basic data types                     | Standard file I/O
C- Constants                            | Pointers
D- Type conversion                      | Including files
E- Predefined variables                 | Overlays
F- Operators                          L-| Chain and Execute
G- Compiler directives                  | Assembly routines
H- Procedures and Functions             | Internal representation of basic
   (including forward declarations)     |    data types
I- Identifiers and Types                | The heap and the stacks
J- String related routines              | Interrupt Routines in Turbo Pascal
K- Reserved Words                       \ Run-time and I/O errors
:A
                                 Introduction                                 


	Turbo  Pascal is a Pascal language implementation written  by  Borland 
International.   This  file is written for the user who is already  reasonably 
familiar with Pascal, and just wants a reference for the deeper darker secrets 
of this implementation of the language.
     This  file is intended to be a quick reference for turbo,  for those  who 
are all ready familiar with Pascal, but need technical reference material.
     If  you  can't  find  what you are looking for  anywhere  else,  try  the 
reserved  words  list.   All built in procedures are discussed there  to  some 
extent.  If it isn't there, then it isn't anywhere.
:B
                           Basic Data Types - 1/2                             


REAL       Reals  are  in the range 1E+38 to 1E-38  and  0.  The  mantissa  is 
approximately 11 significant digits. Reals occupy 6 bytes of memory.  Overflow 
in real calculations will cause an error and stop program execution.

INTEGER    Integers  range  from -32768 to 32767.  They require two  bytes  of 
memory. Overflow in arithmetic operations is not detected.

BYTE       Bytes are in the range 0..255.  They are compatible  with  Integers 
except as parameters, since BYTES require only 1 byte of memory.

BOOLEAN    Booleans have only the values TRUE and FALSE.  Each occupies a byte 
of memory. Ord(FALSE)=0, Ord(TRUE)=1.

CHAR       Chars,  like  bytes,  are in the range 0..255,  but  unlike  bytes, 
represent an ASCII character.
                           Basic Data Types - 2/2                             


STRING     An  array  type of characters which can be referred to as  a  mass. 
Strings  are dynamic,  but are given an initial maximum length between  1  and 
255.  Strings always occupy their maximum length plus 1 bytes. The first byte, 
which  can  be  referenced as StringVar[0],  holds the current length  of  the 
string.

ARRAYS    A generalized array,  holds exactly N * the size of its  constituant 
subparts, where N is the number of elements in the array.
:C
                              Constants - 1/3                                 

     Named  constants,  in  addition  to the standard method,  may  be  typed; 
assuming any of the basic data types.  The sytax is:
______________________________________________________________________________

Program ...     ;
Const
     var:type=value;
...
______________________________________________________________________________

     Values  must be unambiguous constant values.   The variables  named  will 
then  be initialized to the constant value on each distinct run (ie:  new load 
into memory).   Such constants may have their values changed, but will only be 
initialized at the next distinct load (ie:  compilation,  or load into  memory 
from a com file)  
                               Constants - 2/3                                

Representing constants:

     Numerical  (ie:  unnamed constants) may be included inline.   There are a 
variety of methods for representing these values.
______________________________________________________________________________
     Ascii:
          #num      if num is constant, then #num is the char corresponding
          ^char     ^char is the control value implied
eg:
          writeln('This is on'^M#10'two lines');
______________________________________________________________________________
     Hex:
          $num      if num is a legal hex constant then it can be used
eg:
          for i:=$0 to $FF do mem[i+ofs]:=0;
______________________________________________________________________________
                               Constants - 3/3                                

     Strings:
          'string'  Any sequence of ascii characters inside quotes.
                    Single quotes may be built by inserting two quotes.
                    Null strings may be built by using two quotes alone.
eg:
          repeat read(answer) until answer<>'';
          writeln('Hello');
          writeln('Don''t go, please!');
______________________________________________________________________________
     Sets:
          [const1..const2]
                    const1 and const2 represent the upper and lower bounds of
                    the string.
eg:
          repeat read(kbd,c) until c in [^A..'Z'];
:D
                                Type Conversion                               

     All  ordinal scalars may be converted to one another by using their  type 
as a function name.  (Eg:  Char(65)='A', Integer('7')=55).  This includes user 
defined  ordinal types,  but does NOT include reals.   Subranges will  not  be 
mapped.   Conversion  is  done simply by relaxing  typing  constraints.   (Now 
you've seen everything.  Pascal with weak typing?
     Types  are automatically converted when calling a function or subroutine. 
Ascii  and Byte types,  however,  are incompatible and will be tagged  by  the 
compiler  unless  they  are  explicitly converted.   Bytes  and  Integers  are 
assignment,  and  value parameter compatible,  however they are NOT  reference 
compatible.   I  don't recommend ever passing bytes to integers or integers to 
bytes as VAR parameters for this reason.
     When  comparing  Bytes and Integers,  it is best to force  conversion  to 
happen.  Otherwize results will be unpredictable.

EG:
     If i_byte = Byte( j_integer ) then ...

NOTE: To convert integers to pointers, use the function Ptr(I):P
:E
                               Predefined Variables                           


     Turbo provides several built in constants which cannot be redefined, as a 
measure of convenience.  
     Pi has the value useful to such a thing
     True, False are boolean constants
     mem[] is an array of all memory
     port[] is an array of all z80 ports
     nil is the pointer equivalent of zero
     MaxInt is 32767
:F
                                Operators - 1/4                               


     This is a list of all operators available in Turbo Pascal.   There is not 
an operator for finding the result of a power operation.   However,  a  simple 
function will provide results correct to several significant digits.
______________________________________________________________________________
FORTRAN
          VALU = MU ** ZETA
______________________________________________________________________________
PASCAL
         
Function POWER(BASE,EXPN:Real):Real;
Begin
     POWER:=exp(EXPN * ln( BASE ));
End;

...
     VALU:=POWER(MU,ZETA);
...
                                Operators - 2/4                               


     Operators  of equal precedence are evaluated left to right.   The results 
of  certain operators (so called math operators) depend on the type  of  their 
source.  This table lists all possible sources, and outcomes.
_______________________________________

Operands            Result   
Integer,Integer     Integer
Integer,Real        Real
Real,Real           Real
_______________________________________
                                Operators - 3/4                               

Operator  Operation           Operand types       Result    Precedence
------------------------------------------------------------------------------
+ Unary   sign identity       Integer, Real       Tbl 1     1
- unary   sign inversion      Integer, Real       Tbl 1     1
not       bitwize not         Boolean, Integer    Tbl 1     2
*         multiplication      Integer, Real       Tbl 1     3
          set intersection    Set                 Set       3
/         division            Integer, Real       Real      3
div       integer division    Integer             Integer   3
mod       modulo              Integer             Integer   3
and       arithmetic and      Integer             Integer   3
          logical and         Boolean             Boolean   3
shl       shift left          Integer             Integer   3
shr       shift right         Integer             Integer   3
+         addition            Integer, Real       Tbl 1     4
          concatenation       string              string    4
          set union           set                 set       4
-         subtraction         Integer, Real       Tbl 1     4
          set difference      set                 set       4
                                Operators - 4/4                               

Operator  Operation           Operand types       Result    Precedence
------------------------------------------------------------------------------
or        arithmetic or       Integer             Integer   4
          logical or          Boolean             Boolean   4
xor       arithmetic xor      Integer             Integer   4
          logical xor         Boolean             Boolean   4
=         equality            scalar              boolean   5
                              string              Boolean   5
                              Set                 Boolean   5
<>        inequality          scalar              Boolean   5
                              String              Boolean   5
                              Set                 Boolean   5
>=        greater or equal    scalar              Boolean   5
                              String              Boolean   5
          set inclusion       Set                 Boolean   5
<=        Less or equal       scalar              Boolean   5
                              String              Boolean   5
          set inclusion       Set                 Boolean   5
in*       set membership      membertype, Set     Boolean   5
* only in that order.
:G
                            Compiler Directives - 1/2                         


     Select  compiler directives by putting them in comments,  preceded  by  a 
dollar-sign ($). E.g.:
{$A+}
Multiple  directives  may  be given in a single line by separating  them  with 
commas. E.g.:
{$B-,I+,V-}
{$I SNOW.DF ,V-} (Note that the Include directive parameter must have a full
                  extention or be ended with a space.)

Next Screen lists all of the options:
                             Compiler Directives - 2/2                        

Option Default Description/Notes
______________________________________________________________________________
A      A+      Generate absolute code (+=on, - allows recursion, but slow)
B      B+      I/O selection (Use CON: or TRM: for input, +=CON:)
C      C+      ^C, ^S active during I/O (+=active)
I      I+      I/O error handling (+=errors handled by Turbo)
I      nil     include files (e.g:{$Ifilename.ext} includes may not be nested)
R      R-      index range checking (array index, subrange type
	       out of bounds; +=active, slows execution)
V      V+      type checking of VAR parameters (+=on, esp. Strings)
U      U-      ^C active during normal execution (+=active, slows run)
W      W2      with statement level nesting (1-9 allowed)
X      X+      array optimization (+=speed, -=size)
______________________________________________________________________________

Additionally,  the  compiler can use specific start and end  addresses.   To 
specify a new start address,  get into the compiler options menu, and select 
S (just type S,  even though it doesn't appear in the menu).  Similarly, for 
a new end address, select E.
:H
                          Procedures and Functions - 1/5                      


     Use the keywords Function and Procedure to declare these. A procedure
may  return  or use zero or more values.    In turbo  Pascal,  value  passable 
parameters can be:  Reals,  Integers,  Bytes,  Chars,  Sets, Strings, and User 
defined ordinals.
     Normally  type  checking will be done on all parameters.  To  relax  type 
checking,  use  the $V compiler directive (Q.q.v.).   Type checking will  flag 
attempts to pass differently sized strings.   Relaxing type checking will make 
the strings function normally.   Bytes and Integers are passable directly, and 
will  cause  no  parameter  errors.   Byte and  Integer  types  are  converted 
automagically  before being passed.   (Integers are trucated,  or get an extra 
byte of 0's)
     Functions  may  use  and return zero or more values of which one  may  be 
immediately assigned (:=) to a variable of the same type as the function.  The 
legal return types for functions are  Sets,  Reals,  Strings,  Integers,  User 
defined types, Bytes and Chars.
                          Procedures and Functions - 2/5                      

     Two  special  reserved  words are provided to  make  exiting  subroutines 
easier.  These are Halt; and Exit;.
     Halt  stops  the program at that point and returns to CP/M  (without  any 
messages).
     Exit pops all local data from the stack and returns.  A function which is 
exited  will  have an undefined value unless one had been assigned before  the 
Exit call.   (It is normally bad form to assign a return value to the function 
before  the  function end.   In many implementations,  it won't work  at  all.
Turbo Pascal, however, allows the value of the function to be assigned as many 
times as you like, anywhere in the function.)
                          Procedures and Functions - 3/5                      

Syntax (revisited):
______________________________________________________________________________

Procedure Identifier(variable list);

Function Identifier(variable list):type;
begin
     ...
     Identifier:=Value_to_Return;
end;
______________________________________________________________________________

Note  that the attempt to retrieve the value of the function while inside  the 
function is considered a recursive call,  (see compiler option A, QQV) so that 
while the return value of the function can be stored any number of  times,  it 
can never be retrieved.
    Functions and Procedures may be forward declared (assuming they are not in 
an  overlay,  or external  (q.v:  Overlays,  Assembly  programming)).  Forward 
references are simple devices for creating Catch-22 procedures.) 
                          Procedures and Functions - 4/5                      
eg:
     Program Catch_22;
     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:=I*3+1;
               Writeln(I);
          end;
          I:=down(I);
     end;
                          Procedures and Functions - 5/5                      

     begin
          write('Enter an Integer: ');
          readln(x);
          x:=Up(x);
          writeln('That''s all folks');
     end.
______________________________________________________________________________
:I
                          Identifiers and Types - 1/3                         

Type
     Types  may  be Basic data types,  Arrays of types,  subranges of  scalars 
combinations  of  records and all of the above.  In general  they  follow  the 
Pascal Standard. Special notes follow
     Identifiers may include underscores (eg: Last_User)
     Absolute variables:
     Variables may be declared absolute either with respect to a constant,  or 
a variable (ie the location of the variable.)
______________________________________________________________________________

VAR  IOByte: Byte absolute $0003;
______________________________________________________________________________

                          Identifiers and Types - 2/3                        

     Variant records are declared as follows:
     Variant  records have the advantage of using less memory,  by  overlaying 
parts of the record which are never used in tandem.   In some  implementations 
of  Pascal this was the only way in which to create weak typing.   If you  are 
using  this for weak typing,  I suggest that you first look up type conversion 
(QQV).
______________________________________________________________________________

type 
     variant_type = record
          nonvariant_part: type;
          more_nonvariant_part: type;
          case optional_var : scalar_type of
               scalar_constant: (variant_1:type;
                         variant_1_continued:type
               );
               another_scalar: (variant:type);
    end; {record}
                          Identifiers and Types - 3/3                         


     Labels are the last biggie.  In the realm of labels there are three laws. 
One of them applies to Turbo Pascal, the other two are relaxed.

1.   Labels shall be declared first.   In Turbo Pascal, Labels can be declared 
anywhere  outside  of the begin end pairs (as can,  in fact,  any  declaration 
block).   Label  declarations always correspond to the  current  block,  which 
brings us to the next rule.

2.   Gotos  shall not jump out of the current block.   Such an  attempt  would 
leave  the  stack in an undefined state.   The compiler catches this  sort  of 
error for you.  See the Halt and Exit functions instead.

3.    All labels are numeric.   In Turbo Pascal,  a label can be any otherwize 
unused and legal identifier, in addition to the normal numerical kind.
:J
                          String Related Routines - 1/2                       

Val(St; Var Num; Var Pos);
     Change string St into its numeric value Num;  flagging the first  illegal 
character in Pos if any.  If Pos=0 then conversion was successful.  The number 
may not be padded on the left or right with any non-numeric characters.

Str(Num; Var St);
     Change  numeric variable Num into a string (optionally,  format  commands 
can be used, much like with writeln.

Delete

Insert

Copy(st,Pos,Num)
     Copies a substring of st starting at Pos and Num long to it's return.  If 
Pos>length  of  string then '' is returned.  If Pos isn't in [0..255]  then  a 
runtime error is created.
                          String Related Routines - 2/2                       

Concat(st,st,...)
     Also the '+' operator.   Concatenates strings, returning the concatenated 
result as its value.

Length(st)
     
Pos(Obj,Target)
     Returns zero if match isn't found
:K :TP3
:L :TP2