



PL/I-32 alpha Release 3.10
Software Release Bulletin


Disclaimer

The information contained in this document applies to the alpha release 3.10 of PL/I-32. 

THE IMPLEMENTERS MAKE NO WARRANTY OF ANY KIND WITH REGARD TO THIS 
MATERIAL, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The implementers shall not 
be liable for errors contained herein or for incidental or consequential damages in connection with the 
furnishing, performance or use of this material.

This material is provided for evaluation purposes only, and no contract is implied between the 
implementers and the user of this material.

The contents of this document as well as all of the included software are copyright  Hugh W. Gleaves
1996.

Win32, Windows NT and Windows 95 are trademarks of Microsoft Corporation.


1. Introduction

This document accompanies the software that comprises Release 3.10 (alpha) of the 32 bit 
PL/I compiler for Win32.

This document may appear as elaborate for an alpha release, this is not however, the case.
The development of a compiler is a large software engineering undertaking, and detailed and 
accurate technical material is a must if the software is to be tested easily by users.

This degree of technical tracking is exactly what will be used when a complete and finished 
product is produced. Every release be it alpha, beta or final will be accompanied by an SRB.

The PL/I-32 projects objective, is to create an ANSI conformant PL/I compiler for the Win32 
platform. Note the term ANSI in this document means ANSI X3.74-1987 a full featured 
standard for the language this should not be confused with the earlier, less functional ANSI 
standard sometimes referred to as Subset G, this was ANSI X3.74-1981.

This release, unlike the previous release (alpha 2.35) does not produce a usable object 
module so is not yet a true compiler.

However release 2.35 was a DOS program and suffered from all of the weaknesses that 
DOS suffers from. Further development of the DOS compiler was felt to be an unwise 
investment in terms of time and energy.

The source code for the DOS PL/I compiler has been migrated to Win32. Development is 
now done using Visual C++ on Windows NT. The first task is to complete the parser so that 
it supports the full ANSI language, later releases will include an MS-COFF object code 
generator that will allow the compilation and linking of 32 bit PL/I programs.

Release 3.1 alpha, is a Win32 console executable that performs the following:

  Syntax analysis of PL/I source code, much more complete than Release 2.35
  Construction of an internal tree representation of the PL/I source.
  Issues diagnostic messages for syntax errors.
  Declaration completion, name resolution and type checking of the tree.
  Issues diagnostic messages for semantic errors.
  Optionally dumps the resulting tree to the screen if requested.
  Produces a comprehensive listing file if requested.

The tree dumping option (+dump_nodes on the command line) is primarily used for testing 
and debugging of the compiler and has little practical use. Testers may however wish to 
ensure that the tree does correctly reflect the source.

Although code cannot be generated by this release, it does support much more of the PL/I 
syntax than the earlier DOS version, it now accepts the following in full:

  All RECORD I/O statements and associated options.
  All STREAM I/O statements and associated options.
  Full syntax of the INITIAL option on declarations.
  Full ANSI syntax of the DO looping statement.

In addition the compiler runs faster and contains a number of bug fixes for bugs that were 
present in the original DOS version but only detectable under NT.



2. Contents and Installation

The release disk contains the following files:

1. PLI.EXE The compiler itself, a Win32 (console) executable built with max optimization.
2. PLJ.EXE The same compiler with debugging support included, no optimization.
3. INTAFACE.DLL The command line parsing software.
4. *.PL1 Sample PL/I source files.
5. *.INC Sample PL/I include files.
6. ERRORS.BIN  The diagnostic message file.
7. SRB310.DOC  An MS-WORD Document for this SRB.
8. SRB310.TXT   A NOTEPAD text file for this SRB.

The release is supplied as a compressed file called PLI-32.ZIP this file should be copied to a 
directory of your choice on either a Win95 PC or a Windows NT PC. It is recommended that 
the software be used on Windows NT, very little testing has been carried out on the 
Windows 95 OS.

Naturally to exploit long file names on NT you must use an NTFS partition.

Once the file has been copied it must be unzipped doing this will unpack the files listed 
above and you may begin testing. It is probably simpler to work from the command line so it 
is suggested that you start a Win32 console session before carrying out the installation.

Note that under Windows 95 the so-called DOS Box is in fact a Win32 character mode 
session that can run full 32 bit programs the same as in NT.

If you mistakenly attempt to compile a Unicode file, you will get errors, this is mentioned 
simply because NOTEPAD.EXE under Windows NT can save files in Unicode format, this 
can happen inadvertently sometimes and can give the impression of a compiler bug !

The compiler needs no special system settings or the like. It simply runs stand-alone with no 
need to set environment variables or anything.

You will notice that there is a program called PLJ.EXE, this is the same code exactly, except 
that it is a debug build. If you discover what appears to be strange or buggy behaviour then 
you should run the same PL/I source through this debug build, if the problem goes away, 
then it indicates either a genuine bug in the compiler or a possible optimizer problem in the 
Visual C++ compiler used to build the optimized executable.






3. Changes since Release 2.35 for DOS

The following changes have been made to the compiler:

3.1 Long file names
This release supports long file names as used on UNIX, Win32 and OS/2.
You are no longer confined to the restrictive 8.3 DOS format. This change also applies to 
include files.

Include files MUST however end with a suffix of INC and PL/I source files must end with the 
suffix of PL1, the filename may also contain periods in addition to the one in the suffix.

3.2 Long identifiers
This release also supports a maximum identifier length of 64 characters, this of course 
includes procedure and other labels, as well as declaration names.

However a restriction may be imposed later on the length of identifiers for external names.

3.3 Exception handling
This release exploits Win32 exception handling in the main control module of the compiler. 
This allows graceful termination when a runtime exception occurs. Such exceptions can 
occur in any software, but are an obvious possibility in an alpha release compiler.

3.4 Enhanced PL/I Parser
This release accepts almost the full ANSI syntax for PL/I, this includes all RECORD and 
STREAM I/O statements and options. It also includes full support for iterative DO as well as 
the INITIAL option on declarations.

The following ANSI language features are not yet supported by the parser:

  The PACKAGE statement.
  Comma separated declarations, e.g. DCL NAME CHAR(10), CTR DEC(9), P1 POINTER;
  Subscripted labels.
  Syntax checking of PICTURE specs, e.g. DCL A  PIC 999ZZ99 is accepted.
  Enquiries and enquiry tokens, e.g. (: and :) are regarded as invalid tokens.
  Prefix operators in expressions e.g. X = T * (B - X) *  -H ; will elicit syntax errors.
  Assignments of the form: A,B,C = 100;

These remaining shortcomings will of course be addressed in a future release.

Note that PL/I preprocessing is NOT part of the ANSI standard for the language and is 
therefore not supported.


4. Known Faults
4.1 Builtin functions
The compiler does not yet default the attributes of builtin functions, this can cause the 
semantic phase to behave unpredictably, causing the compiler to trigger a runtime 
exception. 
4.2 Source file suffix
If the source file ends in a 3 character suffix, and that suffix is not PL1, then the compiler still 
attempts to compile it.
4.3 File/Entry constants
The declaration of arrays of file and entry constants is currently accepted, this is invalid use 
of the language.
4.4 Assignments
Only minimal semantic validation is performed on the target of assignments, thus illegal 
assignment targets are not reported.
4.5 Conversions
Although some conversions are inserted by the semantic phase, this is incomplete and 
some illegal combinations of operands in expressions are not reported. However if 
binary/decimal and fixed/float operands appear together in an arithmetic expression 
conversion is recognized and correctly highlighted in the .LST file.
4.6 Command line parser
The proprietary and generic command line parser appears to behave oddly sometimes under 
Windows 95, it behaves correctly under Windows NT however. This only applies to the 
interactive menu, straightforward command line use is fine.
This problem is being investigated and will be rectified in due course.



5. Brief user guide

This section explains general use of the compiler and the meaning of the various supported 
command line options.

This is not intended as a complete user manual or language reference and some familiarity 
with the PL/I language is assumed.

The compiler currently accepts only the ASCII character set, EBCDIC is not accepted.
5.1 Command line arguments
To see what command line arguments are available type the following at the command 
prompt (Drive C: is used only as an example):

C:\ PLI ; <Enter>

the semicolon (which may appear anywhere) on the command line, causes an interactive 
user friendly menu to appear:


------------------------- PL/I 32 Optimizing Compiler --------------------------
source_file:
-list:         no                                 -nesting:   no
-mapcase:      no                                 -error:     no
-optimize:     no                                 -bounds:    no
-ndp:          no                                 -table:     no
-beep:         no                                 -system:    no
-code:         no                                 -unrefs:    no
-semantic:     no


You may navigate the menu using either the TAB or  keys, and you may cycle menu 
options using the keys  and  . The menu is constructed with full awareness of the 
number of lines and columns specified for the console.

Pressing F1 will display an explanation string for the currently selected menu option.

The ESC key will abort the menu and return you to the command prompt.

The ENTER key will cause the program (in this case the PL/I compiler) to begin execution 
using the selected options.

Edit fields may be edited as expected, using the cursor keys.

The menu is built in accordance with any specified command line arguments, for example if 
the following is entered:

C:\ PLI +semantic massive.pl1 +nesting ;

then the menu will appear as expected, but the options semantic and nesting will have the word 
yes assigned to them instead of the default no.

Of course if the semicolon is omitted then no menu is displayed and execution proceeds as 
usual for a command line program.

The command line parsing software (INTAFACE.DLL) is a generic function that builds the 
menu and validates and converts command line arguments, based on definition strings that 
are passed in by the application.



The menu is thus built at runtime by parsing these definition strings. This facility is not 
peculiar to PL/I-32 indeed it was developed earlier and separately.

Only some of its functionality is used in PL/I-32, it can do a number of quite powerful 
operations and makes the programmers job a lot easier than conventional methods of 
managing command line arguments.

Arguments that have a yes/no type of behavior are called switches and are selected by 
prefixing the argument name with a + or - sign.

Thus -mapcase means: I dont want mapcase to be used while +mapcase means the 
opposite.

Because switches are specified by name, there is no problem in sorting them out at runtime 
so they may appear in any order on the command line.

5.2 Compiler output
The compiler will report all diagnostics to the standard output, this is the console screen 
under normal circumstances. If +error was selected, then the diagnostics are also written to 
a file that has the same name as the source but with the suffix .ERR

Listing files are modeled on the listing facilities provided by mainframe and minicomputer 
compilers, the file has the suffix .LST, an example of a listing from the alpha 3.10 release is 
shown below:

Win32 (NT/95) dates, times, version-no's etc not yet ported.
Please update LIST.C to remove this msg etc.
OPTIONS: +listing +nesting +code 

        1   0  conv:
        2   0  
        3   0     proc options (main);
        4   1  
        5   1     dcl b      bin(15);
        6   1     dcl d      dec(3);
        7   1  
        8   1     b = d + b;
        9   1  
       10   1     end;
       11   0  
       12   0      

ATTRIBUTES AND CROSS REFERENCE TABLE

PROCEDURE conv ON LINE 3                                                                           

NAME            CLASS     SIZE         LOC   ATTRIBUTES

d               automatic 2            0004  dec(3,0) internal fixed dcl 6                         

b               automatic 2            0006  bin(15,0) internal fixed dcl 5                        

spt_cv_dec_to_short                                                                                
                static    8            0002  entry external dcl 0 (N/A)                            


CONVERSIONS REQUIRED BY THIS COMPILATION

OPERATOR             USAGE COUNT

cv_fixed_bin                   1


LENGTH OF STACK FRAMES:

BLOCK NAME                        LINE No     STACK

conv                                 3            8              
                                           



The compiler also reports some helpful statistics, for example:

D:\PLI-32>pli largetst +code +semantic <Enter>

COPYRIGHT Hugh W. Gleaves 1996
COMPILATION STATISTICS FOR PL/I Release 3.10 alpha
LARGETST.PL1

PHASE        SECONDS      ERRORS    WARNINGS        DISK
initialize         0           0           0           0
syntax             0           0           0          23
declare            0           0           0           0
semantic           1           0           0           0
allocator          0           0           0           3
translate          0           0           0           7
totals             1           0           0          33

SOURCE STMTS 148
SYMBOL TABLE 5530
CODE SIZE    3496
STATIC SIZE  722
LINES/MINUTE 21720
STMTS/MINUTE 8880


The PHASE column lists the names of the phases that were executed during compilation.

The SECONDS column displays the number of elapsed seconds taken by each phase. The 
ERRORS/WARNING column displays the number of diagnostic messages produced by each 
phase. The DISK column displays the amount of disk I/O carried out by each phase.

The DISK column is only very approximate and has not been enhanced to reflect its true 
meaning under Win32. Under DOS it represented the number of 512 byte sectors either read 
or written by each phase.

Also the LINES/MINUTE and STMTS/MINUTE figures are implemented using low resolution 
counters (that were available in DOS) and become less reliable as the source files get 
smaller.












5.3 Command line argument definitions

source_file
This is where the source file name is typed, the .pl1 suffix is optional.

+list
If specified then the compiler will generate an annotated source listing, this is a file with the 
same name as the source file but has the suffix .LST instead.

+mapcase
Specify this option if the source is upper case, e.g. an IBM mainframe source file. This 
causes the compiler to accept upper case keywords. The compiler default is -mapcase in 
this mode keywords are expected to be lower case, but upper and lower case characters are 
distinguished in identifiers. If +mapcase is selected then all keywords are expected to be in 
upper case as are identifiers, lower case and upper case are thus NOT distinguished in this 
mode. 

+optimize
This option is not yet implemented.

+ndp
This option will be removed in a future release. It was used to specify the use of a math 
coprocessor by the DOS code generator in early alpha releases.

+beep
This option causes a PC beep to be generated whenever an error message gets issued and 
also when the compilation is complete, this is a useful audible cue when running long tests 
on lots of source files.

+code
This option will cause the generation of a DOS object file. The option should not be used and 
will not be correctly implemented until a later release. The object file created by release 3.10 
is invalid and unusable under Win32.

+semantic
This causes the semantic phase to be run after syntax and declaration processing has been 
carried out. This phase is less complete than the parser but still performs a large amount of 
validation, type checking and processing.

+nesting
This option causes block and do-group nesting depths to be shown in the listing file, also 
because this option implies a listing it forces one, irrespective of the -list option.

+errors
This option causes an error file to be produced, this file has the same name as the source 
file but has the suffix .ERR

+bounds
This is a code generation option and has no relevance to this alpha release. On the DOS 
compiler it caused the insertion of runtime array access checking code.

+table
This option is not yet implemented.



+system
This option results in an assembler-like listing being produced by the code generator, this 
code appears in the .LST file. This is a code generation option (in fact it forces +code) and is 
not relevant to release 3.10.

+unrefs
This causes the compiler to check for the existence of declared but unreferenced variables 
unused individual structure members are of course not reported. This checking currently 
occurs in the allocate phase which is only run when code generation has been requested.



5.4 Secret arguments
For development purposes the compiler has a number of secret options. These can be 
seen in the menu by first specifying the +secret option on the command line. These options 
are not intended to be seen by conventional users, but may prove interesting and useful 
when testing the compiler.

+debug
This simply prints out a few information lines about full pathanmes used.

+trace_pass2
This causes the activity of the semantic phase to be seen on a per-line basis.

+dump_nodes
This causes a formatted HEX dump to be displayed after compilation. It shows all nodes 
together with their address and any associated child nodes.

+trace_heap
This causes the activity of the node allocator to be displayed.

+trace_code
This causes the activity of the code generators code patcher to be displayed, this shows 
where in the code stream any patches are made, such as those needed to set backward 
offsets in loops etc.

+halt
This causes the compiler executable to sleep when compilation is complete, it is useful 
when debugging the compiler under Windows NT.

5.5 Contacting the implementers
You may contact either of us at the following email addresses:

Hugh W. Gleaves:	gleeh@tulletts.sprint.com
Alan Mazonowicz:	the_maz@dircon.co.uk

If you discover what you suspect is a bug, then please email the associated source and 
include files or a description in sufficient detail for us to reproduce it.

It is often possible with compiler bugs to iteratively simplify the source code yet still 
reproduce the bug, if possible please attempt this as it can save you having to send what 
might be quite large source files.

Remember it is mainly the parser (that is syntax analyzer) that is being tested here, you may 
also specify +semantic as this should correctly process references and expressions for the 
full syntax, however as explained earlier the semantic phase (which does type checking etc.) 
is known to be incomplete, as with builtin functions for example.

In a nutshell valid ANSI PL/I should generate NO syntax errors and invalid syntax PL/I 
SHOULD generate syntax errors. 
PL/I-32 (alpha 3.10) Software Release Bulletin

10


13
Copyright  Hugh W. Gleaves 1996.

PL/I-32 (alpha 3.10) Software Release Bulletin 

Copyright  Hugh W. Gleaves 1996.


