Iron Spring PL/I Compiler

Linux Version 0.9.9b
21 Jul 2017

Release Notes

Introduction

This document provides information on using the Iron Spring PL/I compiler and compiled programs on the Linux platform. For information on the OS/2 platform, see the corresponding document
readme_os2.

The current version still contains bugs. As a user of beta software, you can help improve the compiler. See the section Reporting bugs.

Trademarks
eComStation is a trademark of Serenity Systems International.
Gnu is a trademark of the Free Software Foundation.
IBM is a trademark of IBM, Inc.
Intel is a trademark of Intel Corporation.
Iron Spring is a trademark of Iron Spring Software.
Linux is a registered trademark of Linus Torvalds.
VAX is a trademark of Hewlett-Packard, Inc.
WATCOM is a trademark of Sybase, Inc. and its subsidiaries.
Library heap manager based on code Copyright (c) 2001-2006 Wolfram Gloger.

License

<boring-legal-stuff>
This license a legal agreement between you and Iron Spring Software. Your use of this software signifies that you agree to the terms of this license.

Iron Spring Software grants you the right to use and copy the Iron Spring PL/I compiler and library freely. You may distribute programs compiled using the compiler and/or linked with the library under any terms you wish without restriction. The source to the library is licensed under the terms of the Gnu Lesser General Public License (LGPL).

All material is copyright Iron Spring Software, 2014, 2015.

THE COMPILER AND LIBRARY ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COMPILER AND LIBRARY IS WITH YOU. SHOULD THEY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
</boring-legal-stuff>

Contents

This distribution includes the executable for the PL/I compiler plic, the static library lib/static/libprf.a, and the sources for the library and sample programs.

  pli-0.9.9b
    |
    +-----------------------samples----------------lib
    |                          |                    |
 plic                       (Sample sources and     +--------------------------static---include----source-----------alt
 (compiler executable)       %include files,                                   |         |         |                 | 
 (documentation, etc.)       sample makefiles                                  |         |         +--------asm      |
                             and module definition                             |         |   (PL/I source)   |     (alt storage   
                             file).                                            |         |               (assembler management)
                                                                               |  (%include files          source)
                                                                               |    required by                                                                                      
                                                                               |     library).
                                                                               |
                                                                     libprf.a (static library)

Requirements

The folowing software is required to run the Linux version of the compiler:
The following software is recommended:

Restrictions

Version 0.9.9b has a number of restrictions. The most significant are:

Installation

  1. The distribution file is supplied as a gzipped tar file. Unpacking it will create a directory named "pli-0.9.9b".
  2. Only the compiler (pli-0.9.9b/plic) and the static runtime library (pli-0.9.9b/lib/libprf.a) are required.
  3. Move the compiler to a directory in your $PATH such as /usr/bin, and move libprf.a to a directory such as /usr/lib. Alternatatively, you can specify which directory the library is in in your makefiles.
    An installation procedure is provided. cd to the 'pli-0.9.9b' directory and type 'make install' (with suitable authority). This procedure moves the compiler to '/usr/bin' and creates a symlink 'plic' referencing it, and moves the library to '/usr/lib' and creates the symlink 'libprf.a'.

A later version will be installable using one or more of the standard package managers.

Sample Programs

The file samples/samples.html contains a list of all the sample programs. The comments in each program contain information on using the program.
  1. Test the sample programs. In this release only static linking is supported. CD to the directory "pli-0.9.9b/samples" and type "make -f Makefile.Linux" without the quotes, case is significant.. The sample programs "numwrd", "filedump", "libver", "print_listing", and "task" build to executables, the remainder should generate object files.
  2. Test numwrd. Enter "./numwrd 123". The program should display the result "one hundred twenty-three".
  3. You might want access to the %INCLUDE files in "pli-0.9.9b/lib/include" or "pli-0.9.9b/samples" for your own programming.

Using the compiler

The "samples" directory contains three sample makefiles that can be used to compile and link PL/I programs. You should copy these and modify them for your requirements. "LC_make" and "LCC_make" both use gcc to drive the linker; the program entry will be libc's "_start". "SA_make" calls ld directly and should be used only for programs that don't call any C functions. The program entry will be PL/I's "main". In all cases the static PL/I runtime linkary "libprf.a" is required, indicated by "-lprf" in the linker command.

The Iron Spring PL/I Compiler Programming Guide describes the PL/I compiler options available.

Linking PL/I programs

The following examples show different methods of linking PL/I programs.

This command uses gcc to link a PL/I program with libc, and use C's malloc and free for heap storage management.
gcc -o ${EXE} ${OBJ} ${ALTDIR}/fhs.o ${ALTDIR}/ghs.o -lprf -Wl,-M >${MAP}

This command uses gcc to link a PL/I program with libc, and use PL/I's heap storage management.
gcc -o ${EXE} ${OBJ} -lprf -Wl,-M >${MAP}

This command uses ld to link a standalone PL/I program with no reference to libc.
ld -z muldefs -Bstatic -M -e main -t -o ${EXE} \ ${OBJ} \ -lprf \ >${MAP}

64-bit Linux Considerations

The Iron Spring PL/I compiler, and compiled PL/I programs, will run on a 64-bit system as 32-bit applications. The following steps are required:

Documentation

The
Iron Spring PL/I Compiler Programming Guide contains a description of the features of the compiler. Except as noted in the Programming Guide under Compiler Differences and Restrictions this compiler is compatible with the IBM "PL/I for MVS and VM Compiler 1.1". A complete language reference will be available as part of a future release.

Documentation for the IBM compiler is available online.

Changes

Changes in the current version
Added external structure _pli_argc containing argc, *argv[] and *envp[] equivalent to arguments to a C main().
Changes in version 0.9.9
Added ROUND builtin.
Added compiler option "-N" to generate line number information for debugging.
 
Changes in version 0.9.8
Stream I/O data lists can now contain items with Type-3 DO iteration.
Added PRECISION, ATAN, and ATAND builtins.
Fixed problems with OVERFLOW handling and conversion of FLOAT constants.
Changes in version 0.9.7
Added builtins REVERSE, AFTER, BEFORE, TRIM, LTRIM, RTRIM, and SEARCH.
Aggregate array assignment of adjustable arrays now works. Assignment of arrays with matching attributes now optimized to block move.
Changes in version 0.9.6
Added builtin functions IAND, IEOR, INOT, IOR, ISLL, and ISRL.
Added builtin subroutine PLISRTD.
FIXED DECIMAL OPTIONS(IBM) attributes for IBM mainframe format packed decimal data.
Changes in version 0.9.5
The keyword MEDIUM is accepted as an ENVIRONMENT option for compatibility with VSE PL/I.
Various fixes for STREAM INPUT, pictured data and CONTROLLED storage.
Changes in version 0.9.4
The Procedure Map has been added as an optional part of the listing. This lists the offset and type of each statement to simplify debugging of trap conditions.
CTLASA is now supported for PRINT files.
0.9.4 is primarily a bugfix release. Numerous problems with adjustable and CONTROLLED aggregates have been fixed.
Changes in version 0.9.3
*The sizes of some FLOAT variables have been increased to fix problems with conversions between binary and decimal float. Any programs using FLOAT data should be recompiled.*
*Any programs using OPTIONS(FROMALIEN) entries should be recompiled.*
A limited version of CONTROLLED storage has been added. See the Programming Guide for description.
The ALLOCATION and MAXLENGTH builtins are now implemented.
Multiple iteration specifications are now allowed for the DO statement.
The L-Format item is now supported for input.
The OPEN statement now accepts TITLEs of the form DD_XXX where DD_XXX is an environment variable supplying the actual name of the file.
The ENVIRONMENT option INTERACTIVE can be used to identify a file assigned to a terminal.
Changes in version 0.9.2
PL/I multitasking has been added, including the TASK, EVENT, and PRIORITY options of the CALL statement, the WAIT statement, and the COMPLETION and STATUS builtin functions and pseudovariables.
SIZE is now recognized as a synonym for the STORAGE builtin function.
Structure assignments BY NAME are now allowed.
EXTERNAL data items are now aligned on a DWORD (4-byte) boundary instead of 8-byte.
Changes in version 0.9.1
The SINH, COSH, TANH, and CS builtins have been added.
The PACKAGE statement is now supported.
The INITIAL CALL option is now supported.
Floating-point pictures are now allowed, for output only.
Changes in version 0.9.0
The compiler now supports Linux as a host and a target.
The ERF, ERFC, and EXP builtins have been added.
Page headings have been added to the compiler listings.
 

Bugs Fixed

Bugs fixed
Changes in version 0.9.9b
Bug
number
Fixed
in version
Description
3730.9.9bCompiler error for PLIFILL with expression as second argument
3720.9.9b'S' picture item prints ' ' instead of '+'
3710.9.9bSEARCH returns incorrect result with multi-character first argument
3680.9.9bREVERSE of VARYING string returns incorrect length string
3670.9.9bRUNTIME error with expressions in INITIAL attribute
3650.9.9bRuntime error with compound expressions using INDEX
3610.9.9bEmpty source file crashes compiler
3560.9.9bMultiple data items not allowed in TYPE3-DO list
3540.9.9bCompiler trap with ",," in structure declaration
3530.9.9bCompiler error converting FLOAT constant to FIXED BINARY
3510.9.9bIncorrect conversion of FLOAT constants
3480.9.9bCompiler trap on DO statement with STEP clause
3470.9.9bNested DO loop fails to loop
3460.9.9bRuntime trap for FLOAT to FIXED conversion in DO statement
3450.9.9bDO loop tests incorrectly if increment is variable
3430.9.9bError compiling some inbedded subscripts in locator qualification
3420.9.9bCompiler error with expression in SELECT statement
3400.9.9bRuntime error with INITIAL CALL
3390.9.9bStorage overlay problems
3380.9.9bComplex bit expressions may return incorrect result
3370.9.9bSTRING builtinpasses incorrect length when used as procedure argument
3360.9.9bListing lines truncate after 100 characters
3350.9.9bCompiler trap on SUBSTR with STRINGRANGE enabled and the length argument omitted
3280.9.9bError compiling subscripted statement labels
3120.9.9bError compiling type3-DO in GET/PUT
3090.9.9bCompiler not correctly derefeencing arrays of structures
3030.9.9bCompiler prematurely detects EOF in source
1910.9.9bLIKE attribute not recognized in parameter declarations
 
Changes in previous versions
3330.9.9aCharacter '7F'x should print as '.' in dumps
3320.9.9aArray of structures padded incorrectly
3310.9.9aSome format retetition factors raise ERROR at runtime
3300.9.9aNon-positive argument to delay raises ERROR at runtime
3290.9.9aFIXEDOVERFLOW not raised for fixed decimal operations
3280.9.9aError compiling subscripted statement labels
3270.9.9aFormat with non-integer widths raises ERROR at runtime
3240.9.9aSort sequence problems in plistrd
3230.9.9aplisrtd has undocumented minimum record length requirement
3210.9.9aStructures not padded to size of alignment
3200.9.9aLBOUND/HBOUND incorrect for adjustable arrays
3170.9.9aZERODIVIDE only raised once
3160.9.9aCONVERSION raised for GET LIST at EOF
3150.9.9aSELECT with substring argument fails to match
3120.9.9aCompiler error compiling stream do iteration
3110.9.9aRuntime trap passing adjustable string arg tp adjustabls parameter
3080.9.9aError compiling subscripted entry references
3070.9.9aDO loop doesn't iterate after GOTO
3060.9.9aFixed binary divide returns incorrect results
3050.9.9aCompiling PUT DATA(array_elem) gets error 701
3040.9.9aInvalid intrinsic call at runtime converting FLOAT to CHAR
3030.9.9aCompiler prematurely detects EOF
3020.9.9aIncorrect result length for AFTER builtin
2970.9.9(OS/2) Read format F CRLF file raises RECORD condition
2960.9.9PUT DATA(<minor structure> generates incorrect output
2950.9.9Assignment of string constant to pictured data causes error
2940.9.9Compiler error initializing too many FIXED DECIMAL array elements
2930.9.9SIZE check for FIXED DECIMAL generates incorrect code
2920.9.9Compiler error if second argument to IAND or IOR has precision<=15
2910.9.9Incorrect code generated to assign scalar to structure
2900.9.9Error in assignment of structures containing pointers
2890.9.9Incorrect alignment adding and subtracting constants
2880.9.9Incorrect scale factor for the result of the ROUND builtin
2860.9.8PUT DATA(structure) may abend or generate incorrect output.
2850.9.8LEAVE <name> does not create cross-reference entry for "name".
2840.9.8Some floating point constants convert incorrectly.
2830.9.8REVERT for the first condition established in a block may function incorrectly.
2820.9.8incorrect output using E-format.
2810.9.8Pointer compare not doing unsigned comparison.
2790.9.7Duplicate procedure names in package cause compiler trap.
2780.9.7GET LIST(string) doesn't properly check for leading quote.
2770.9.7Enabling STRINGRANGE causes various run-time errors.
2760.9.7Changes in 0.9.6 cause drifting picture characters not to appear.
2750.9.6(Linux) Main task termination doesn't terminate subtasks.
2740.9.5MAX and MIN builtins generated incorrect results for FLOAT and FIXED DECIMAL arguments.
2730.9.5Incorrect conversion of scaled FIXED DECIMAL constant to FIXED BINARY.
2720.9.5FIXED builtin not correctly handling source and target with different scale factors.
2710.9.5Scaled F-Format not formatting correctly.
2700.9.5COLUMN and SKIP(0) specifications not working for stream input.
2690.9.5Stream input RECSIZE was not defaulting to 80 if not specified.
2680.9.5TIME and DATETIME builtins not returning correct millisecond value.
2670.9.5Incorrect conversion from CHARACTER to FIXED DECIMAL.
2660.9.5Incorrect output moving bit string constant to subscripted nybble.
2650.9.5Insert characters in picture cause incorrect placement of drifting characters.
2640.9.5Compiler trap if the length or bound of adjustable or controlled data is not FIXED BINARY.
2630.9.5Compiler traps when pictured data is used as the control variable of a DO statement
2620.9.5The ADD, MULTIPLY, and DIVIDE builtins not accepting pictured arguments.
2610.9.5Incorrect message is printed for a missing %INCLUDE file.
1800.9.5(Linux) DELAY statement uses incorrect time interval.
2600.9.4Compiler trap if input file is empty.
2590.9.4Incorrect output when adjustable numeric array is passed as argument.
2580.9.4Incorrect conversion of FIXED DECIMAL to FLOAT BINARY(W62).
2570.9.4Recursive function may trap on return(W58).
2560.9.4MOD builtin traps when arguments are FIXED DECIMAL
2550.9.4Character comparison may be incorrect if first operand is constant
2540.9.4Conversion of hex bit string to character generates incorrect results
2530.9.4Source text preceding the left margin prints on previous line of compiler listing.
2520.9.4%PAGE preprocessor statement not executing ON ENDPAGE On-Unit.
2510.9.4Compiler error compiling the COPY and REPEAT builtins with a non FIXED BINARY count expression.
2500.9.4Files opened with title "stdin", "stdout", or "stderr" trap on close.
2490.9.4PUT EDIT pictured data with a P format generates incorrect output.
2480.9.4Comparing a VARYING string to spaces generates incorrect code(W40).
2470.9.4Compiler trap 11 compiling the DIVIDE builtin(W33).
2460.9.4ALLOCATing an array only allocates storage for one element(W27).
2450.9.4The BINARY builtin generates incorrect code if called with a BINARY argument(W21).
2440.9.4 INITIAL option for ENTRY variables generates incorrect code(W19).
2430.9.3 Some character compares of unequal length strings may return incorrect result for other than = and ¬=.
2420.9.3 EVENT variables in AUTOMATIC structures not properly initialized.
2410.9.3 BINARYVALUE does not treat the NULL builtin and a null pointer value equivalently.
2390.9.3 [Linux only] Arguments to _pli_mutex_init processed incorrectly.
2380.9.3 DO FOREVER causes compiler error rather than "Unimplemented" message.
2350.9.3 Negative numbers incorrect when converting base.
2340.9.3 Variables declared in a package with no storage class default to AUTO rather than STATIC.
2330.9.3 Calling CS builtin with pointer argument rather than ADDR produces incorrect output.
2320.9.3 Declaring FILE INTERNAL causes compiler error.
2290.9.3 Very large statements such as declaration of large initialized AUTO array generate compiler error or trap.
2280.9.3 Data read using input pictures containing T, I, or R incorrect.
2240.9.3 Programs with more than approximately 50 unitialized external data declarations cause compiler trap.
2230.9.3 Duplicate names identified in error in structure declarations.
2210.9.3 Calling SUBSTR with structure argument causes compiler trap.
2190.9.3 BY NAME move of array of structures moves only first array element.
2180.9.3 Moving numeric pictured data to numeric pictured causes compiler error.
2160.9.3 Indexing ignored in reference to temporary stack data, e.g. SUBSTR(expr).
2130.9.3 Base address of multi-dimensioned array computed incorrectly.
2120.9.3 Not all registers saved and restored when calling OPTIONS(FROMALIEN) entry.
2110.9.3 BINARYVALUE( ADDR(xxx) ) returns incorrect value.
2100.9.3 SUBSTR with STRINGRANGE enabled returns string at position one greater than specified.
2080.9.3 Conversion of character string to element of numeric array generates runtime error.
1860.9.3 Alternate entry to MAIN terminates when returning.
1830.9.3 PUT LIST(array) produces no output.
1820.9.3 Some FLOAT BINARY converts to FLOAT DECIMAL incorrectly.
1980.9.2 DO REPEAT should allow nonarithmetic control variable.
1970.9.2 Based variable argument to STORAGE should not require locator.
1780.9.2 Bad descriptor passed for adjustable arg if parm is also adjustable.
1770.9.2 Bad descriptor passed for adjustable string parameter.
1760.9.2 PAGESIZE(0) should suppress formfeeds.
1750.9.2 BIT builtin result may be incorrect.
1740.9.2 TIME builtin always returns 0 ms.
1730.9.2 EXIT statement causes compiler trap in GCALL.
1710.9.2 SKIP format item without relative line defaults to SKIP(0) instead of (1).
1700.9.2 Problems mapping structure containing unions.
1690.9.2 Compiler trap if dummy argument size is larger than 32767.
1680.9.2 Compiler trap on leading spaces in picture repetition factor.
1670.9.2 Compiler trap generating error message on invalid conversion to program control variable.
1650.9.2 Overly aggressive optimization of register assignments causes REGX error 990-02
1640.9.2 Based adjustable data causes various errors.
1620.9.2 SIZE not recognized as synonym for STORAGE builtin.
1610.9.2 Incorrect references generated for members of structure parameters.
1600.9.2 Incorrect assignment of arrays of unaligned bit strings.
1590.9.1 Compiler traps when builtins are called with program control arguments where computational arguments are expected, and visa-versa.
1580.9.1 Various compiler problems using the initial attribute with static unaligned bit strings.
1570.9.1 The HEXIMAGE builtin generates incorrect code when the first argument is a pointer reference (not pointer expression).
1560.9.1 The COMPARE builtin generates incorrect results after fix for bug 148.
1540.9.1 Some comparisons of character data to literals cause error 990, code 05 in MX.
1530.9.1 Incorrect code generated for conversion of scaled pictured data to arithmetic.
1520.9.1 Incorrect scaling on move of arithmentic to pictured data.
1510.9.1 Incorrect code generated for some bit string assignments.
1500.9.1 Remote formats generate incorrect code.
1480.9.1 The COMPARE builtin reverses the order of the operands.
1470.9.1 [Invalid] Unary pointer expression causes compiler trap.
1460.9.1 Converting WORD integer to FLOAT causes error 990, code 14 in MX.
1450.9.1 Entry returning expression with adjustable bounds or lengths does not produce error message.
1440.9.1 ENTRY arguments to procedures with SYSTEM linkage generate errors or incorrect code.

Modifying the Runtime Library

The document
About the Iron Spring PL/I Library Contains information necessary to modify or extend the runtime library. Most users of Iron Spring PL/I will probably not be interesting in making modifications to the library.

Support

No formal support is provided for pre-release versions of Iron Spring PL/I. Bugs will be fixed on a best-efforts basis only, and the fix included in the next distributed version. "Thank You" to a number of users who have submitted bug reports which helped improve this version of the compiler.

A Yahoo! group "ISPLI" (http://tech.groups.yahoo.com/group/ISPLI) is available as a user forum for problems, tips, etc. The developers also monitor this group.

Reporting bugs

For the current version of the compiler, a bug is one of the following:
  1. Any compiler trap.
  2. Incorrect output not caused by a flagged unimplemented feature (compile-time message 995 or run-time UNIMPLEMENTED condition.
  3. Compile-time message 990 (Compiler error).
  4. Output of the compiled program different from that produced when the program is compiled with the IBM compiler, except for differences noted.
Features not implemented in the current version will be added in future versions. In the meantime, their absence should at least be indicated by an error message.

Before reporting a bug, please make sure you are running the most recent release.

The following information is required to report a bug:

  1. A brief description of the problem (trap, incorrect output, etc.)
  2. The host operating system: OS/2 or Linux.
  3. The command-line options used to compile this program.
  4. The current compiler version obtained by running plic -V
  5. A small sample program ilustrating the problem. Please make sure you imbed or supply all the %include files required to compile the sample.
Hopefully, all this information will be small enough to be sent as plain text in a mail message. Otherwise please attach a zip file. No other formats will be accepted.

Mail bug reports to:

   bugs@iron-spring.com


version 0.9.9b, 21 Jul 2017
http://www.iron-spring.com