| # Iron Spring PL/I Compiler ## OS/2 Version 1.0.0 1 Feb 2023 ### Release Notes

- Introduction
- License
- Contents of distribution
- Requirements
- Installation
- Sample Programs
- Using the compiler
- Linking PL/I programs
- Documentation
- Changes in the current version
- 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 OS/2 platform. For information on the Linux platform, see the corresponding document readme_linux.

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.

#### 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.EXE, the runtime DLL, the static and import libraries lib\static\prf.lib and \lib\prf.lib, and the sources for the library and sample programs.

      pli-1.0.0
        |
        +-----------------------samples----------------lib
        |                          |                    |
     plic.exe                   (Sample sources and     +--------------------------static---include----source
     (compiler executable)       %include files,        PL/I DLL (prf.dll)         |         |         |
     (documentation, etc.)       sample makefiles       Import Library (prf.lib)   |         |         +--------asm
                                 and module definition                             |         |   (PL/I source)   |
                                 file).                                            |         |               (assembler
                                                                                   |  (%include files          source)
                                                                                   |    required by
                                                                                   |     library).
                                                                                   |
                                                                          prf.lib (static library)
                                                                          OS2386.lib

#### Requirements

The folowing software is required to run the OS/2 version of the compiler:

- OS/2 Warp 4 or higher, includung eCS. Warp 3 has been reported to work, but is unsupported.
- LINK386 linker or equivalent to link object files.
  LINK386 is distributed with OS/2 and installed as part of "Optional System Utilities."

The following software is recommended:

- The JWasm assembler - necessary only to rebuild the assembler pieces of the runtime library.
- Gnu make, available from Hobbes.
  The version of make used to build the libraries is 3.81beta3.
- The WATCOM® debugger "wdw." WATCOM software is available from Open Watcom.
  Versions 1.3 and 1.4 were tested.

  The following debuger setup is not required, but will simplify debugging.

  To get the debugger to stop at the beginning of the PL/I program, make the following modifications to "setup.dbg", normally found in the <WATCOM>\binw directory.

  `elseif _dbg@dbg$os == 12 && ?@main {` | Following this
  `go/until/noflip @main` |
  `}` |
  `elseif ?@@_PLI_MAIN {` | Insert these three lines
  `go/until/noflip @@_PLI_MAIN` |
  `}` |

  After this, you will also need to link your program with a module definition file that exports the symbol "_PLI_Main" so that it is visible to the debugger. The "samples" directory contains an example .def file and linker command to do this.

#### Installation

1. Unpack the distribution file into a directory named "x:\pli-1.0.0", (Specify your desired drive in place of 'x'.)
2. Only the compiler (x:\pli-1.0.0\plic.exe) and either the static runtime library (x:\pli-1.0.0\lib\static\prf.lib) OR the DLL (x:\pli-1.0.0\lib\prf.dll) and the import library (x:\pli-1.0.0\lib\\prf.lib) are required. You should already have a version of OS2386.LIB. If you don't, you can use the one supplied in "x:\pli-1.0.0\lib\static\OS2386.lib".
3. Move the compiler to a directory in your PATH or add x:\pli-1.0.0 to your path in config.sys.
4. If you are using the DLL version of the library, move prf.dll to a directory in LIBPATH, or add (x:\pli-1.0.0\lib) to your LIBPATH in CONFIG.SYS and reboot. In order to link compiled programs you also need to make the import library prf.lib available by moving it to a directory listed in the LIB environment variable. Alternatatively, you can add the line "LIB = x:\pli-1.0.0\lib" to your makefiles.
5. If you are using the static version of the library (x:\pli-1.0.0\lib\static\prf.lib), move it [and x:\pli-1.0.0\lib\static\OS2386.lib if required] to a directory listed in the LIB environment variable. Alternatatively, you can add the line "LIB = x:\pli-1.0.0\lib\static" to your makefiles.

A later version will be installable using the WarpIN installer.

#### 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. Two makefiles are provided: 'makefile.OS2DLL' links with the PL/I DLL, 'makefile.OS2Static' links with the static library. CD to the directory "x:\pli-1.0.0\samples" and type "make- makefile.OS2DLL" for the DLL version, or "make -f makefile.OS2Static" for the static version. If you don't have make available, you can manually type the commands in the makefile. The sample programs "numwrd", "filedump", "print_listing", and "libver" 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 "x:\pli-1.0.0\lib\include" or "x\pli-1.0.0\samples" for your own programming.

#### Using the compiler

The "samples" directory contains two sample makefiles that can be used to compile and link PL/I programs. You should copy these and modify them for your requirements. "Makefile.OS2Static" is an example of a compile and link using the static version of the runtime library. "Makefile.OS2DLL" is an example linking against the runtime DLL. The library named "prf.lib" contains object files in the static directory, and import definitions for the runtime DLL in the non-static directory.

#### Linking PL/I programs

The following command statically links a PL/I program with the runtime library.

`LINK386 /m:f /a:8 /st:0x100000 ${OBJ},,,${LIBDIR}\prf.lib+${LIBDIR}\OS2386.lib,${DEF};`

- Command should be contained on one line.
- Replace ${OBJ} with the name of your compiled object file (.obj)
- Replace ${LIBDIR} with the name of the directory containing the static library. For example, the default is \pli-1.0.0\lib\static
- Replace ${DEF} with the name of your module definition files (.def). See the LINK386 reference for a description of module definition files. This is not required for a VIO (non-PM) program, so it could be omitted and the ';' placed after 'OS2386.lib'.

The following command links a PL/I program with the PL/I runtime DLL.

`LINK386 /m:f /a:8 /st:0x100000 ${OBJ},,,${LIBDIR}\prf.lib,${DEF};`

- Command should be contained on one line.
- Replace ${OBJ} with the name of your compiled object file (.obj)
- Replace ${LIBDIR} with the name of the directory containing the PL/I runtime expore library. For example, the default is \pli-1.0.0\lib
- Replace ${DEF} with the name of your module definition files (.def). See the LINK386 reference for a description of module definition files. This is not required for a VIO (non-PM) program, so it could be omitted and the ';' placed after 'OS2386.lib'.
- The PL/I DLL must be in $LIBPATH when the program is executed.

#### 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 in HTML will be available as part of a future release.

Documentation for the IBM compiler is available online.

#### Changes

Changes in the current version
Mapping of slack bytes in structures has changed. If you share a structure, or a pointer to a structure, between separately-compiled procedures, all procedures should be recompiled.
The compiler option "-lg" requests printing of an aggregate map.
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.
JWAsm is now used to assemble code for both the OS/2 and Linux libraries.
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 version numbering scheme was changed to more standard system.
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 1.0.0
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
|  | Changes in previous versions
492 | 0.9.10e | RANDOM not recognized as valid builtin function
491 | 0.9.10e | Aggregate listing prints sizes of arrays incorrectly
490 | 0.9.10e | PROC or ENTRY with no label crashes at compile time
483 | 0.9.10e | NOSTRG not accepted as valid condition prefix
481 | 0.9.10e | CALL TASK without task variable traps at compile time
479 | 0.9.10e | HBOUND/LBOUND/DIM incorrect for some adjustable structures
478 | 0.9.10e | Infinite loop inside Type-3 DO loop
461,462 | 0.9.10e | Run-time trap assigning elements of arrays of structures
477 | 0.9.10d | Incorrect display of DEFINED structures in aggregate listing
476 | 0.9.10d | Factored level numbers in declaration parse incorrectly
475 | 0.9.10d | VERIFY does not allow expressions as arguments
474 | 0.9.10d | Converting FIXED BINARY to BIT in operation expression returns null bit string
472 | 0.9.10d | Assigning null string to adjustable traps occasionally
468 | 0.9.10d | TRANSLATE a null varying character string traps
465 | 0.9.10d | STORAGE(x) is a restricted expression when x is not adjustable
464 | 0.9.10d | PUT LIST/DATA doesn't space if already at tab position
463 | 0.9.10d | Incorrect conversion of immediate value to UNSIGNED
457 | 0.9.10d | PUT DATA structure names off by one
456 | 0.9.10d | TRANSLATE a null varying character string traps
236 | 0.9.10d | Unable to use scalar array element in DO-Statement as TO, BY, etc. Conditionals must be scalar expressions.
455 | 0.9.10c | Error declaring parameters of subscripted entry variable structure element
453 | 0.9.10c | Size of adjustable string does not include length prefix
452 | 0.9.10c | Improper diagnosis of STRINGSIZE condition
451 | 0.9.10c | Compiler trap for UNSIGNED constant greater than 2147483647
450 | 0.9.10c | Compiler error for ENVIRONMENT clause with no specifications
449 | 0.9.10c | Incorrect code generated for complex WHEN clauses
448 | 0.9.10c | STRING builtin fails with scalar character argument
447 | 0.9.10c | ERROR condition raised at compile time with some FIXED DECIMAL constants
446 | 0.9.10c | STRING builtin doesn't concatenate elements of structure argument
445 | 0.9.10c | Compiler trap initializing STATIC numeric variable with character string
444 | 0.9.10c | VERIFY builtin traps when first argument is VARYING
443 | 0.9.10c | CALL TASK may cause compiler errors
442 | 0.9.10c | INIT attribute ignored allocating BASED variable
441 | 0.9.10c | Trap passing dummy argument to adjustable array parameter
440 | 0.9.10c | Runtime trap on some RETURN statements
439 | 0.9.10c | Incorrect handling of floating point exceptions [OS/2 only]
437 | 0.9.10c | PUT DATA(ptr) causes trap in runtime library
436 | 0.9.10c | Structure alignment problems
435 | 0.9.10c | BOUND/HBOUND/DIM may return incorrect result in expression
433 | 0.9.10c | Runtime error for n**2 where n is FIXED BIN(31)
432 | 0.9.10c | Diagnose error matching array argument with scalar parameter
431 | 0.9.10c | Issue warning message for RETURN in ON-Unit
426 | 0.9.10c | Compiler error assigning BIT(16) to FIXED BIN(16)
429 | 0.9.10b | Some declarations of variables without attributes parse incorrectly
428 | 0.9.10b | Error referencing members of a DEFINED structure
427 | 0.9.10b | Error referencing subscripted EXTERNAL data
425 | 0.9.10b | Opening nonexistent file ENV(APPEND) does not create new file
424 | 0.9.10b | UNDEFINEDFILE not caught for nonexistent file
423 | 0.9.10b | Incorrect results for & and | on adjustable bit strings
422 | 0.9.10b | Library routine _pli_TBS missing
421 | 0.9.10b | Trap accessing BIT(*) parameter
420 | 0.9.10b | Syntax error in SELECT statement not diagnosed
419 | 0.9.10b | x**2 now done inline (performance improvement)
418 | 0.9.10b | DECLARE(...),... generates erroneous error message
417 | 0.9.10b | Incorrect code generated for DO UNTIL
416 | 0.9.10b | STATIC pointers dereferenced incorrectly
415 | 0.9.10b | Incorrect code generated for DO UNTIL
410 | 0.9.10b | ONFILE builtin returns null string for UNDEFINDFILE on OPEN of ISAM file
404 | 0.9.10a | RETURN statement should be invalid in ON-Unit
403 | 0.9.10a | SIZE builtin returns incorrect value for structures
401 | 0.9.10a | KEY and INTO keywords incirrectly disgnosed on READ
398 | 0.9.10a | Incorrect conversion of CHAR to UNSIGNED
397 | 0.9.10a | STORAGE of some adjustable strings causes compiler trap
395 | 0.9.10a | Some CONTROLLED variables initialized incorrectly
394 | 0.9.10a | Some expressions in WHEN statements cause errors at runtime
390 | 0.9.10 | Incorrect output for constant expressions with mixed bases and scales
389 | 0.9.10 | Printing with E format and too small field width prints nothing if SIZE not enabled
388 | 0.9.10 | EVENT variables initialized incorrectly
387 | 0.9.10 | Incorrect error message for RETURN(structure)
386 | 0.9.10 | Incorrect error message for VALUE declaration at package level
385 | 0.9.10 | CHAR(float) should return VARYING string
384 | 0.9.10 | Procedure returning CHARACTER VARYING returns incorrect string descriptor
381 | 0.9.10 | Declaration code duplicated for parameters of external procedures
380 | 0.9.10 | Compiler error in CALL with structure argument
379 | 0.9.10 | Iterative DO containing a DISPLAY statement fails to increment
378 | 0.9.10 | References to some dased idems before the declaration cause compiler traps
377 | 0.9.10 | Label on RETURN statement returning a value causes compiler error
376 | 0.9.10 | GET STRING LIST fails with array argument
366 | 0.9.10 | GET LIST fails with tab separator
319 | 0.9.10 | Tempname fails when no directory name passed
314 | 0.9.10 | Tempname loops when passed non-directory argument
310 | 0.9.10 | Runtime error accessing arrays of COMPLETION variables

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

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.0.0, 1 Feb 2023

    http://www.iron-spring.com