# About the Iron Spring PL/I Library [OS/2]

The Iron Spring PL/I Library is copyright Iron Spring Software, 2023

The complete library is released under the terms of the Gnu Lesser General Public License (LGPL)

No library manager is shipped with with standard OS/2 Warp 4 or its toolkit. As a convenience to users who might want to modify or extend the library, an unmodified executable of the Open Watcom® Library Manager (wlib.exe) is included.

>     Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved.
>     Source code is available under the Sybase Open Watcom Public License.
>     See http://www.openwatcom.org/ for details.

The text of the complete license for Open Watcom software is included.

In the following, <release> represents the current release. For this version that is pli-1.2.0.

This document describes the details of the OS/2 version of the library. For the Linux version see library_linux.

The supplied makefile will build a static object library in <release>\lib\static\prf.lib, and a DLL and import library in <release>\lib\prf.dll and <release>\lib\prf.lib.

The complete library sources are found in <release>\lib\source (PL/I source code), <release>\lib\source\asm (OS-independent assembler source code and includes), and <release>\lib\include (PL/I include files). Operating system dependent sources are in <release>\lib\source\OS2 and <release>\lib\source\linux To modify the library, make your changes to the source, cd to <release>\lib, and type make os2. The makefile is built for Gnu make and compatibles, it currently will not work with wmake.

To add a procedure to the library, after coding the source, you need to add its entry to <release>\lib\prf.def for the import library. Ordinals 250 and up are expected to be available for user procs. You will also need to add the object file name to <release>\lib\prf.lbc, the command file for wlib.

The startup procedure "_pli_Start" (<release>\lib\asm\plistart.asm) needs to be linked with the main procedure, and references the external symbol "_pli_Main", which is defined for each OPTIONS(MAIN) procedure. To simplify linking, a copy of this code is stored in the import library. Since "_pli_Main" is not defined in the library code, a dummy module (<release>\lib\OS2\dummy.asm) is linked into the DLL to provide its resolution. plistart is stored in the static library with the other runtime procedures, and no dummy is required.

Since the compiled PL/I code specifies the library to be linked (prf.lib), both the import library and the DLL have the same name. The <release>\samples directory gives an example of how to choose the desired library.

The directory <release>\lib\include contains definitions of the data areas used by the library, with descriptive comments. The following might be of particular interest:

desc.inc
  Definitions of PL/I "data descriptor" formats.
dsa.inc
  The PL/I standard stack frame header for a procedure or BEGIN-block.
fcb.inc
  The PL/I "file control block".
gbl.inc
  Global data used by PL/I program and library. Note the this control block contains eight bytes reserved for user data.
plitabs.inc
  The definition of the stream output "tabs" control block. This is intended for the use of user programs.
  See the IBM PL/I for MVS and VM Programmers' Guide for a description of PLITABS.
xcpt.inc
  Definitions of hex values and text descriptions of OS/2 system exceptions.

Iron Spring PL/I version 1.2.0, 5 15 Nov 2023.