Pascal v 3.31 - README File
10/10/85
This document presents product information that supercedes
or is not covered in the regular documentation. In
particular, this document covers product changes and
enhancements made immediately prior to release. It is
recommended that the user review the document immediately.
------------------------------------------------------------
Differences between version 3.31 and version 3.30
------------------------------------------------------------
A. Stack size of the compiler has been increased. By using
the included EXEMOD utility, you can specify the amount of
stack space to be available during compilation. If you
specify a bigger stack, you can compile larger programs,
but you will need more memory for the compiler to run.
The compiler comes initially configured with a 40K stack.
If the compiler does not run on your machine, because of
limited memory, you may wish to change the stack size to
some smaller amount. For many programs, a stack size of
10K proves to be ample. You can use EXEMOD to decrease
the stack size.
If the compiler fails with an "out of memory" error, it is
likely that the stack is too small for the program you are
attempting to compile. You can use EXEMOD to increase the
stack size.
B. The linker has been changed so that if it is directed to
combine code segments into a physical segment whose size
is more than 65499 bytes, it will issue a warning message:
"Segment longer than reliable size." The message is only
a warning. The executible file will still be created. An
attempt to build any segment, code or data, longer than
64K will still result in a fatal error.
C. FOR LOOP control variables are no longer set to the unde-
fined value when the loop terminates. See the Reference
Manual, page 322, "$initck-" metacommand, second item #2,
which states that $initck generates code to set the value
of INTEGER range FOR-loop control variables uninitialized
when the loop terminates normally. This is NO LONGER done.
D. Files and versions are as follows:
PAS1.EXE Pascal Compiler version 3.31
LINK.EXE 8086 Object Linker version 3.04
LIB.EXE Library Manager version 3.02
EXEPACK.EXE EXE File Compression Utility version 3.00
EXEMOD.EXE EXE File Header Utility version 3.00
------------------------------------------------------------
Memory Management Details
------------------------------------------------------------
MEMAVL returns the number of bytes from the top of the
heap to the end of DGROUP. If the heap needs to grow, it
will use this space. It should be noted that the space
allocated for the heap can only grow and NEVER SHRINK.
Therefore, during the course of a program, the value re-
turned by MEMAVL can only DECREASE (as the heap grows) and
NEVER INCREASE. The following diagram illustrates this
concept:
--------------------------------- DGROUP:MAX
! FREE SPACE NOT IN HEAP !
---------------------------------
! HEAP !
---------------------------------
! STACK !
---------------------------------
!STATICALLY ALLOCATED PART OF DS!
--------------------------------- DGROUP:0
FREECT(0)*2 returns the number of free bytes in the heap
plus the value returned by MEMAVL.
FREECT(0)*2-MEMAVL returns the number of free bytes in the
heap itself.
In version 3.2, a Pascal program allocates all of free
memory to itself. In version 3.3x, a Pascal program re-
turns space it doesn't need to DOS. Therefore, in version
3.3x, DGROUP is at the top of the allocated space, and
offset 2 in the MS-DOS data area returns the segment para-
graph for the top of DGROUP. See also page 164 of the Mi-
crosoft Pascal Compiler User's Guide for further discuss-
ion of the "upper memory limit."
------------------------------------------------------------
Differences between version 3.30 and version 3.20
------------------------------------------------------------
A. The following sections have been modified or added to the
Microsoft Pascal User's Guide.
Update: Microsoft Pascal 3.3
Appendix A - Differences Between Versions 3.2 and 3.3
Appendix E - Mixed-Language Programming
Appendix F - Error Messages
Microsoft LIB - Library Manager Reference Manual
B. The following files are provided with the Pascal v 3.3
release, but are not completely documented in the User's
Guide. Whatever (additional) information is required to
use these files is provided in this document.
EXEPACK.EXE - Utility for packing .EXE files in order to
reduce their size and allow faster loading (refer to
subsection A.10 of the Microsoft Pascal User's Guide).
EXEMOD.EXE - Utility for viewing and modifying certain
header information in .EXE files (refer to subsection
A.11 of the Microsoft Pascal User's Guide).
CEXEC.LIB - Portion of Microsoft C library providing
routines to support the use of the MS-DOS 'exec'
function (function call 4B hex).
PASEXEC.INC - Interface declarations and documentation for
routines in CEXEC.LIB
DEMOEXEC.PAS - Example program demonstrating how to use
the routines provided in CEXEC.LIB.
EMOEM.ASM - Customization for the 8087.
LVARSTK.OBJ - This object file provides a variable stack.
Note: The version of LINK.EXE is actually v 3.02 (not 3.01,
as documented).
Please refer to the update notice at the beginning of the
User's Guide for a complete list of the files which have
been added to the Pascal v 3.3 release.
C. If your machine has an 8087 or an 80287, you should read
this closely to see if this pertains to your hardware
configuration. All Microsoft languages which support the
8087 need to intercept 8087 exceptions in order to
properly detect error conditions and provide reliable and
accurate results. The math libraries which contain the
8087 exception handler and emulator (MATH.LIB and
8087.LIB) are designed to work without modification with
the following machines:
IBM PC family and compatibles, Wang PC
(any machine which uses NMI for 8087 exceptions)
Texas Instruments Professional Computer
There is a source file EMOEM.ASM included with the release
that can be modified. Any machine which sends the 8087
exception to an 8259 Priority Interrupt Controller (master
or master/slave) should be easily supported by a simple
table change to the EMOEM.ASM module. In the file there
are further instructions on how to modify the file and
patch libraries and executables.
If your computer is not listed, and you need to modify the
EMOEM.ASM program, please contact your hardware
manufacturer for the specific information on the 8087 and
what needs to be modified. If your hardware manufacturer
is not aware of the changes that need to be made they
should contact the Microsoft OEM Group.
The Microsoft Retail Product Support Group is not equipped
to help out in the customization of the EMOEM.ASM program.
D. The library file, CEXEC.LIB, contains the following
routines extracted from the Microsoft C compiler library
(Version 3.0).
system - Invokes COMMAND.COM with a user-specified command
line.
spawn - Loads and executes a specified .COM or .EXE file
(i.e., executes a child process).
The file PASEXEC.INC contains INTERFACE declarations
allowing these routines to be called from Pascal and
extensive comments explaining how to use them.
The file DEMOEXEC.PAS contains an example program
demonstrating the use of these routines.
E. The following is an updated list of language features,
noted in the User's Guide or Reference Manual, that are
not implemented in this release.
1. MARKAS and RELEAS are not supported in the release.
2. The $initchk metacommand does not check for
uninitialized REAL variables.
3. OTHERWISE is not accepted in RECORD declarations.
4. Code is generated for PURE functions, but no checking
is done.
5. The extend level operators SHL, SHR and ISR are not
available.
6. No checking is done for invalid GOTOs.
7. READ, READLN, and DECODE cannot have M and N
parameters.
8. Enumerated I/O, permitting the reading and writing of
enumerated constants as strings, is not available.
9. The metacommands $tagck, $standard, $extend, and
$system can be given, but have no effect.
10. The $inconst metacommand does not accept string
constants.
F. This section documents product features which are not
described in the User's Guide or Reference Manual.
1. Both the Pascal compiler and the runtime library
associate the name "ERR" with the MS-DOS standard error
device handle (generally abbreviated as stderr). Recall
that stderr is mapped to the physical console and,
unlike stdin and stdout, is not redirectable. Thus, the
command syntax:
PAS1 ERR;
will cause the Pascal compiler to expect source code
from the keyboard rather than a file named ERR.PAS.
Similarly, the command syntax:
PAS1 TEST,,ERR;
will cause the source listing output to written to the
console screen rather than a file named ERR.LST.
Finally, note that a file variable may be explicitly
attached to 'ERR' with, say, the ASSIGN procedure and,
thereby, attached to stderr.
2. Both the compiler and the runtime use the Xenix
compatible I/O system in MS-DOS 2.xx/3.xx (MS-DOS 1.xx
is no longer supported). Thus, both the compiler and the
user's program will access files in other directories if
the proper pathnames are specified.
Since MS-DOS has a limit on the number of 'handles' that
may be simultaneously open for I/O, the user may
occasionally encounter an error 1034 ("too many open
files"). This may happen during execution of PAS1.EXE,
if there are nested include files. It may also occur at
runtime if the user tries to have too many files open at
the same time. In most cases, the problem is easily
circumvented using the "FILES = <number>" statement in
the CONFIG.SYS file (see your MS-DOS manual for
details). However, there is a fixed upper limit in MS-
DOS of 20 handles (five preassigned plus 15 others) that
any single program may have open simultaneously.
3. There have been several recent changes to the behavior
and capabilities of the EXEMOD and EXEPACK utilities
provided on this release which are not covered in the
printed manuals.
EXEPACK attempts to prevent you from compressing a file
onto itself. It is not infallible - it can be fooled by
a statement of the form:
EXEPACK TEST.EXE .\TEST.EXE
If it detects an attempt to compress a file onto itself
it will issue the message:
exepack: cannot pack file onto itself
and exit with return code 1. Also, when using EXEPACK
to compress an .EXE file with overlays, the compressed
file should be renamed back to the original name of the
linked file to avoid the overlay manager prompt (see
Overlays in the User Guide).
EXEMOD has an undocumented switch, /h, which can be seen
in the usage prompt (it is not shown in the Users Guide
description of the usage prompt). This option CANNOT be
used with any of the other options, and it is equivalent
to typing:
EXEMOD PROG.EXE
That is, it simply displays the header fields of the
.EXE file without modifying them.
EXEMOD has also been modified to work correctly on
packed (via EXEPACK) files. When it recognizes a packed
file, it will print the message:
exemod: (warning) packed file
If the stack value is changed, it modifies the value
that SP will have AFTER expansion. If either min or
stack is set, min will be corrected as necessary to
accomodate unpacking or stack. Setting max operates as
it would for unpacked files.
If the header of a packed file is displayed, the CS:IP
and SS:SP values are displayed as they will be after
expansion, which is not the same as the actual values in
the header.
The compiler executable files (PAS1, PAS2, and PAS3) are
not packed on the distribution diskettes. We recommend
that when you set up your own diskettes (as recommended
in the manual or otherwise), you run EXEPACK on all the
compiler executable files. You'll notice that the
savings is not great on most of them.
Note: Refer to the MS-DOS Programmer's Reference manual
for further information on .EXE file headers.
4. Controlling the Stack Size - the /STACK Linker option:
/STACK:number
The /STACK option allows you to specify the size of the
stack for your program. The number is any positive
value (decimal, octal, or hexadecimal) up to 65,536
(decimal). It represents the size, in bytes, of the
stack.
Note: The EXEMOD utility, can also be used to change the
default stack size.
5. The allocation of memory for the stack is somewhat more
flexible than a simple fixed stack.
In the User's manual, there is a warning that the
compiler front end and back end now use a fixed stack
and that, since the ratio of stack and symbol table
space varies from one compilation to another, some
programs that used to compile with previous versions,
will now fail for lack of memory. This is not strictly
the case. There is still a maximum amount of stack
space, but when the initial allocation of space for
symbol tables is exhausted, space will be allocated from
the area reserved for the stack. This will cause a
slight reduction in compilation rate if your program is
big enough for this to happen. If, however, your
program fails to compile because of lack of stack space,
(usually as a result of a very complex expression), you
can use EXEMOD on the compiler itself to increase the
space initially reserved for the stack.
Your code compiled with this version will, by default,
use a fixed stack and you may see changes in its
behavior if it tends to use a lot of heap space or a lot
of stack. On the other hand, the fixed stack makes it
much safer to compile with stack checking disabled.
If you want your program to use the stack space for
excess heap items, link with the object module,
LVARSTK.OBJ. Then, your program will have the same
flexibility in its stack allocation as do the compiler
passes themselves. If you further use EXEMOD to change
the default stack size to a much larger number, your
program will behave pretty much as it did with previous
versions, although allocation from the stack space is
not as efficient as from the initial heap space. In this
case, you should also compile with stack checking
enabled since unprotected collisions between the stack
and the heap can lead to unpredictable behavior.
6. The SIZEOF function has been enhanced. It is now
permissable to omit the second parameter if the variable
is a pointer to a super array. Thus, SIZEOF(P^), where P
is a pointer to a super array, is now a valid
expression. Note, however, that if in P^ has not been
allocated (with a NEW), SIZEOF(P^) is undefined. It is
the programmer's responsibility to check that P^ has
actually been allocated before using this form of the
SIZEOF function.
G. This section notes corrections to the documentation.
1. Microsoft User's Guide - Appendix A.8 - page 149:
The 5th paragraph starts out:
"The memory allocation is preset to 6144 (6K)
bytes...."
This paragraph is actually referring to the Stack size,
and the 6K is incorrect. To verify the actual size of
the stack of the compiler passes that you have received,
please use the EXEMOD utility which displays the header
fields of an .exe file.
2. Microsoft Pascal User's Guide - Appendix A.12 - Page
156:
The segment contents for a Pascal program in memory are
listed below (from the highest memory location to the
lowest).
Heap - The "heap" is the area of the default data
segment (DGROUP) that is available for dynamic
allocation at runtime via the NEW procedure. It does not
belong to a named segment and will not show up on a link
map.
STACK - The STACK segment contains the user's stack,
which is used for all LOCAL data items.
_BSS - The _BSS segment contains all UNINITIALIZED
STATIC DATA.
EEND, EDATA - Defined and used by the runtime library.
CONST - The CONST segment contains all CONSTANTS.
P3CE, P3C, P3CB, P2CE, P2C, P2CB, P1CE, P1C, P1CB, P3IE,
P3I, P3IB, P2IE, P2I, P2IB, P1IE, P1I, P1IB, XCE, XC,
XCB, XIE, XI, XIB - Defined and used by the runtime
library.
COMADS - Not used. Part of FORTRAN runtime support.
_DATA - The DATA segment is the default data segment.
All INITIALIZED GLOBAL and STATIC data reside in this
segment.
NULL - The NULL segment is a special purpose segment
that occurs at the beginning of DGROUP. The NULL segment
contains the compiler copyright notice. This segment is
checked before and after the program executes. If the
contents of the NULL segment change in the course of
program execution, it means that the program has written
to this area. This is usually caused by the use of an
uninitialized adr variable, ads variable or pointer. The
error message "Null pointer assignment" is displayed to
notify the user.
__FBSS - Not used. Part of C runtime support.
C_ETEXT - The C_ETEXT segment marks the end of the code
segments. It contains no data and is therefore a segment
of zero length.
Code segments (listed as "module" in the illustration
on page 156) - Each module is allocated its own code
segment (also called a text segment). Code segments are
not combined, so there are multiple code segments.
However, all code segments have class CODE.
It should be noted that segmented memory above DGROUP
may be accessed by the Pascal user via the long heap
allocator. Please refer to Section 8.2.1 in the Pascal
User's Guide for a decription of the necessary library
procedures.
When implementing an assembly language routine to call
or be called from a Pascal program, you will probably
refer to the code and _DATA segments most frequently.
The code for the assembly language routine should be
placed in a user-defined segment with class CODE. Data
should be placed in whichever segment is appropriate to
their use, as described above. Usually this is the
default segment _DATA.
If linking with MS-FORTRAN (3.30) routines, segments for
COMMON blocks or LARGE data items occur between __FBSS
and NULL. Each COMMON block has its own segment(s) and
class. Segments allocated for LARGE data items all have
class LARGE. In the case of a COMMON block with the NEAR
attribute, the segment occurs between EEND and _BSS,
which is then combined in DGROUP.
If linking with MS-C (3.0) routines, data segments,
outside of DGROUP, required for the C routines are
occur between __FBSS and NULL. These segments will have
class name FAR_DATA or FAR_BSS depending on whether they
hold initialized C variables or uninitialized C
variables.
3. Microsoft Pascal User's Guide - Appendix A.12 - Page
158:
The following instructions in the entry and exit
sequences are NOT required:
inc bp
dec bp
The following instructions are included in order to
maintain compatibility with XENIX C, and therefore they
are OPTIONAL:
extrn __chkstk:far
call __chkstk
The following instructions are included in order to
maintain compatibility with MS-DOS C modules, and
therefore they are OPTIONAL:
push di
push si
pop di
pop si
4. Microsoft Pascal User's Guide - Appendix D.2 - page
176:
It is not permitted to mask the invalid operation bit on
the 8087 control word.
5. Microsoft Pascal Reference Manual, Chapter 8.4.1 - page
92:
A TERMINAL mode file should be accessed as a file of
TEXT if input is to be READ from it. In particular,
since the console/keyboard is always treated as a
TERMINAL mode file, it should always be accessed as a
file of TEXT for READing. If single character,
unbuffered, unechoed input from the keyboard is
necessary, the function DOSXQQ should be used to call
for this service from MS-DOS directly (see Appendix B,
Version Specifics, of the Microsoft Pascal User's
Guide).
6. Microsoft Pascal Reference Manual, Chapter 15.2 - page
240:
The function, LMULOK, is the very function ultimately
called to perform the multiplication in any integer4
product (e.g., the code generated for i := j * k;, where
i,j,k: integer4, will invoke LMULOK). Direct access to
this routine is supported so that the user can perform
an integer4 multiplication which overflows without
having the program abort with a fatal runtime error.
The value of the product is well-defined only in the
case where the product does not overflow (i.e., LMULOK
returns TRUE). The reason for this is that the overflow
condition is generally detected before the
multiplication is complete and computation ceases as
soon as the overflow is detected. The documentation
indicates that the product is always computed and
returned and this is clearly incorrect!
H. The following public variables, defined in entx6l.asm in
earlier versions of MS-Pascal, no longer exist in version
3.3.
BEGHQQ
BEGMQQ
CURHQQ
ENDHQQ
ENDMQQ
MAXMQQ
The following public variables, defined in entx6l.asm in
earlier versions of MS-Pascal, still exist in version
3.30. Note, however, that only CESXQQ, CRCXQQ, CRDXQQ and
DOSEQQ are intended for direct access by the user.
CESXQQ - DOS saved ES value (for command line)
CLNEQQ - last line number encountered
CRCXQQ - value of CX for DOS call
CRDXQQ - value of DX for DOS call
CSXEQQ - pointer to sourcef context list
DGRMQQ - segment of DGROUP
DOSEQQ - DOS return code
HDRFQQ - Unit F open file list header
HDRVQQ - Unit V open file list header
PNUXQQ - pointer to unit initialization list
RECEQQ - machine error context, program segment
REFEQQ - machine error context, frame ptr
REPEQQ - machine error context, program offset
RESEQQ - machine error context, stack ptr
STKBQQ - stack start, to fix long GOTO
STKHQQ - stack limit, to check overflow
UPCX87 - offset address of 8087 error context
I. When reporting a suspected problem with the compiler to
the Retail Product Support Group, we ask that you please
provide the following information to help us in tracking
down the problem.
1. The shortest possible example which can be used to
demonstrate the alleged problem (the example should be
provided in source code, on a standard 5 1/4" MS-DOS
disk or a hard copy listing if it is very short).
2. A complete description of the symptoms of the problem
including complete directions on reproducing these
effects with the supplied example (compilation options
used, libraries linked with,...,etc.).
3. The compiler version number (from the logo that is
printed out when you run PAS1).
4. Your system configuration, both hardware (machine,
total memory, coprocessor,...,etc.) and software
(version of DOS, terminate-and-stay-resident utilities
or unusual system software, free memory as indicated by
chkdsk,...,etc.).
Having this information will be of immense help to us in
our effort to diagnose and solve your problem.
