| # Iron Spring PL/I Compiler ## Linux Version 1.4.0 26 May, 2025 ### Release Notes

- Introduction
- License
- Contents of distribution
- Requirements
- Restrictions
- Installation
- Sample Programs
- Using the compiler
- Linking PL/I programs
- 64-bit Linux Considerations
- Documentation
- Bugs fixed in the current version
- Modifying the Runtime Library
- Reporting bugs

#### 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. You can help improve the compiler. See the section Reporting bugs.

Trademarks
ArcaOS is a trademark of Arca Noae.
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, 2023.

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-1.4.0
        |
        +-----------------------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:

- Linux. PL/I should be distro-agnostic. Testing was done on Ubuntu 24.04.2 (Noble Numbat) - Kernel version 6.11.0-25-generic x86_64 At least a 2.6 kernel is required for multitasking.
  Running under Windows WSL2 has been verified to work.
- GNU Binutils - a collection of tools including a linker (ld), and an archive utility (ar).

The following software is recommended:

- The gnu C library glibc (32-bit). This may have been provided with your system. PL/I programs can be linked either with or without libc. The gnu C compiler gcc is recommended to drive the linker when linking with libc.
- The JWASM assembler - necessary only to rebuild the assembler pieces of the runtime library.
- Gnu make.
- The gdb debugger.

#### Restrictions

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

- The compiler cannot yet generate position-independent code (PIC) required to build shared objects. As a result, only static linking to the PL/I library is available.

#### Installation

1. The distribution file is supplied as a gzipped tar file. Unpacking it will create a directory named "pli-1.4.0".
2. Only the compiler (pli-1.4.0/plic) and the static runtime library (pli-1.4.0/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-1.4.0' 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 instructions and 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-1.4.0/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-1.4.0/lib/include" or "pli-1.4.0/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.

- Compiled PL/I programs have no external dependencies. If no calls are made to functions coded in the C language the only library required is the PL/I runtime library 'libprf.a'. The sample makefile 'SA_make' compiles a PL/I program and links without referencing libc.
- If any C functions are called, the PL/I program should be linked with libc; the sample makefile 'LC_make' compiles a PL/I program and uses the Gnu C Compiler (gcc) to link it. It is possible to link with ld, but using gcc eliminates libc version dependencies.
- The PL/I library includes its own heap storage management. Programs linked with libc can use libc's heap management for both PL/I and C storage, or can use separate heaps for the PL/I and C portions. As distributed the library will use separate heaps. Versions of allocate and release are provided in the directory pli-1.4.0/lib/alt will use C's malloc and free. The sample makefile 'LCC_make' shows how to link these procedures.

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}`

- Replace ${EXE} with the name of your excecutable.
- Replace ${OBJ} with the name of your compiled object file (.o)
- Replace ${ALTDIR} with the name of the directory containing the alternate storage management modules. For example, the default is /pli-1.4.0/lib/alt
- Replace ${MAP} with the name of your link map (.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}`

- Replace ${EXE} with the name of your excecutable.
- Replace ${OBJ} with the name of your compiled object file (.o)
- Replace ${MAP} with the name of your link map (.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}`

- Replace ${EXE} with the name of your executable.
- Replace ${OBJ} with the name of your compiled object file (.o)
- Replace ${MAP} with the name of your link map (.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:

- If ISAM is to be used, install the gnu 32-bit libc if not already installed. For Ubuntu-64 the command is:

  `sudo apt-get install gcc-multilib`

- The PL/I runtime library libprf.a should be placed in /usr/lib32.
- When linking with ld, the options required are:

      --oformat=elf32-i386
      -melf_i386

#### 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 at teampli.net.

#### Bugs Fixed

Cumulative list of bugs fixed
|  | Changes in version 1.4.0
615 | 1.4.0 | Compiler errors may generate error messages containing NULL characters
610 | 1.4.0 | Use of non-existent builtin causes compiler trap
609 | 1.4.0 | Aggregate assignment of FIXED BINARY arrays with elements shorter than four bytes incorrect
606 | 1.4.0 | Aggregate assignment of unaligned BIT arrays incorrect
593 | 1.4.0 | Operands of some short bit string comparisons aligned incorrectly
582 | 1.4.0 | Compiler trap allocating CONTROLLED variable with INITIAL option
578 | 1.4.0 | Compiler trap referencing element declared with REFER
|  | Changes in prior versions
607 | 1.3.2 | References to subscripted CONTROLLED elements causes compiler error
603 | 1.3.2 | Comparison of two files fails with compiler error. Now temporarily gets error 612: "Invalid comparison of program control data"
602 | 1.3.2 | Compiler error calling FLOAT builtin with literal constant argument
600 | 1.3.2 | F format does not print '-' for negative one-digit numbers
599 | 1.3.2 | MOD builtin traps if used in INITIAL attribute
598 | 1.3.2 | Incorrect value set for ALLOCATE REFER-object
597 | 1.3.2 | Compiler error with HBOUND. LBOUND of adjustable array
594 | 1.3.2 | SIZE builtin of a structure ending with an unaligned bit string is one byte too short
592 | 1.3.2 | PUT EDIT field widths may be incorrect for b2 and b3 format items
589 | 1.3.1 | GOTO <subscipted-label-constant> traps at runtime
588 | 1.3.1 | INITIAL attribute generates incorrect data for STATIC BIT fields before non-BIT
587 | 1.3.1 | Incorrect conversion of CHARACTER to FLOAT
584 | 1.3.1 | Incorrect output PUT EDIT with "F" format
583 | 1.3.1 | Incorrect output for PUT <minor-structure>
579 | 1.3.1 | Compiler trap on aggregate assignment of array arguments
577 | 1.3.1 | Alignment attribute not copied for LIKE structure
572 | 1.3.1 | Compiler trap referencing computational elements of structure parameters
571 | 1.3.1 | Error returning bit(1) result from some conditionals
570 | 1.3.1 | SUM builtin of array with zero lower bound causes runtime trap
568 | 1.3.1 | Reference to element of DEFINED structure incorrect
566 565 | 1.3.1 | BIT builtin returns incorrect result
551 | 1.3.1 | Structure qualification not allowed for refer object
549 | 1.3.1 | BASED AREA variable not properly initialized when allocated
448 | 1.3.1 | STRING builtin and pseudovariable incorrect output if argument is a character string
410 | 1.3.1 | ONFILE builtin returns null string in UNDEFINEDFILE On-Unit
344 | 1.3.1 | GET STRING(xx) LIST(string) raises ERROR condition
231 | 1.3.1 | ENTRY variable not allowed as argument to ENTRYADDR builtin
563 | 1.3.0 | Incorrect access to elements of array of structures
561 | 1.3.0 | Assignment to array of structures may be incorrect
560 | 1.3.0 | Result of INDEX or SEARCH builtin incorrect if used in expression
556 | 1.3.0 | LBOUND/HBOUND incorrect for adjustable array. (repeat of 320)
555 | 1.3.0 | Refer object set incorrectly for array bounds
554 | 1.3.0 | Incorrect length returned for CONTROLLED string elements
553 | 1.3.0 | STORAGE/CURRENTSTORAGE values inconsistent for adjustable based structure
552 | 1.3.0 | Refer expression not converted to FIXED BIN(31)
551 | 1.3.0 | Allow structure qualification for refer object name
550 | 1.3.0 | Element name and descriptor not passed to I/O subsystem
549 | 1.3.0 | Subscripted reference to undeclared variable causes trap
548 | 1.3.0 | Error with hardware shift instruction with constant shift amount
547 | 1.3.0 | Declaration of external array causes compiler trap
540 | 1.3.0 | No warning generated for undeclared programmer-named condition
530 | 1.3.0 | TRIM(bit string) generates garbage
454 | 1.3.0 | Error referencing BASED ENTRY variable
546 | 1.2.0 | Builtin SIZE not recognized as synonym for STORAGE
539 | 1.2.0 | Incorrect conversion of bit string constant to FIXED DECIMAL
536 | 1.2.0 | Incorrect output with PUT(bit_string) with A-Format
534 | 1.2.0 | Errors with UNSIGNED size<4
533 | 1.2.0 | Errors converting relational expression to bit string
532 | 1.1.0 | (OS/2)GOTO out of ON-Unit causes erroneous "recursive abend"
528 | 1.1.0 | Block initialization calling some library procedures traps at runtime
518 | 1.1.0 | Initialization of UNALIGNED BIT elements of STATIC structures and arrays incorrect
513 | 1.1.0 | Various errors with VARYING UNALIGNED BIT arrays
512 | 1.1.0 | Trap referencing structure with REFER option declared in another block
511 | 1.1.0 | Floating point numbers print incorrectly if smaller than 1e-16
510 | 1.1.0 | ADDR(x) may return incorrect result if x was previously referenced in the same statement
509 | 1.1.0 | Access to adjustable descriptor in containing block returns incorrect result
461 462 | 1.1.0 | SIGSEGV on aggregate assignment to array of structures
508 | 1.0.0 | Incorrect conversion of FLOAT BINARY to FIXED DECIMAL
506 | 1.0.0 | Compiler trap in some cases where statement not properly terminated
504 | 1.0.0 | Incorrect conversion of COMPLEX data
503 | 1.0.0 | Statement label should not be allowed on declaration
502 | 1.0.0 | Error using array element as control variable in DO-Statement
501 | 1.0.0 | Code comment not printing subscript for subscripted label constant
500 | 1.0.0 | GET/PUT array elements off by one
499 | 1.0.0 | CHAR to BIT conversion not handling leading and trailing blanks
498 | 1.0.0 | ONCHAR returns incorrect value
497 | 1.0.0 | Incorrect output for GET/PUT of minor structure
496 | 1.0.0 | Problems moving FIXED BIN returned value
495 | 1.0.0 | SIGNED/UNSIGNED builtins may return incorrect precision
494 | 1.0.0 | Incorrect precision converting FIXED DECIMAL to FIXED BINARY
493 | 1.0.0 | Fixed documentation of OSGetProcInfo

#### 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

Iron Spring PL/I is supported on a "best efforts" basis. Attempts will be made to fix all reported bugs, and have the fixes 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.

The Iron Spring PL/I Users' Forum (https://groups.io/g/Iron-Spring) 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 1.4.0, 26 May, 2025

    http://www.iron-spring.com