# Iron Spring PL/I 1.2.0 Sample Programs

This is a brief description of the sample files distributed with Iron Spring PL/I Version 1.2.0. The samples are distributed free of any licenses or restrictions. Unless otherwise indicated all sample programs will compile and run on Linux and OS/2.

You might want access to the %INCLUDE files in "pli-1.2.0/lib/include" or "pli-1.2.0/samples" for your own programming.

The comments in each program contain information on using the program. In the following, substitute the name of the top-level directory where you installed the compiler, for example "pli-1.2.0".

## Building samples on Linux

In this release only static linking is supported.

1. CD to the "samples" directory. To build all applicable sample programs except ISAM, type "make -f Makefile.Linux" without the quotes, case is significant.
2. The ISAM sample links with libc and a C package pblisam. The file "Makefile.isam" compiles and links a load and an update program. It then runs the compiled samples to create and update an ISAM file.

## Building samples on OS/2

Two makefiles are provided: "makefile.OS2DLL" links with the PL/I DLL, "makefile.OS2Static" links with the static library.

1. CD to the directory "x:\pli-1.2.0\samples" and type "make -f 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.

## Running the samples

[OS/2 users substitute "\" for "/" in the commands]

### All

numwrd | Numwrd will convert a number between -9,999,999,999 and 9,999,999,999 to words. Enter "./numwrd 123" (or any integer of your choice). The program should display the result "one hundred twenty-three" (or your number).
filedump | filedump will print a hex/character dump of a file declared with ENV(VARLS). A sample file "vfile.dat" is provided. To execute type ./filedump vfile.dat" filedump can be used to dump any VARLS file.
hanoi | Classic "Towers of Hanoi" problem with three discs. Text-only version lists the moves made. To execute type ./hanoi
print_listing | This program will read and print PL/I compiler listing on a PCL printer. The output will be in landscape mode on letter paper, 8 lines per inch, 60 lines per page. Type ./print_listing print_listing.lst, or any other PL/I listing file.
readu | readu can read a text file as ENV(U) and print it. It is currently hardcoded to read its own source file. Type ./readu.
keysamp | keysamp creates a KEYED non-indexed file and reads it back. The file will be named "keyed.file.sample". Type ./keysamp.
refsamp | refsamp is a sample program illustrating the use of self-defining structures (REFER option). It creates a file of eight records of various lengths. to run the sample type ./refsamp. The program creates the file, and reads it back and prints it.
sorttest | sorttest is a test of PLISRTD. It sorts a test file, sort.dat, on a user-selected field name. The program defines three sort keys for the sample data file provided: STOCK_NUMBER, SALE_AMOUNT, and CUSTOMER_NAME. Type ./sorttest <key> where "key" is name of the defined sort keys. The program sorts the sample file and prints the records in sorted order.
task | task exercises PL/I multitasking. The main procedure attaches four subtasks. Each subtask displays a block character in a different color at random positions on the screen. The program runs indefinitely until ATTN is pressed. Type ./task to execute.

### Linux

spawntest | spawntest program is an example of using the sample procedure 'spawn' to create a child process. It attaches the system sort command to sort itself. To execute, type ./spawntest.
ISAM | loadsamp creates an ISAM file from data provided. updtsamp updated the ISAM file with additions, changes, and deletions from data provided. Makefile.isam compiles end executes the sample programs. Type make -f Makefile.isam to run.

### OS/2

pmhanoi | pmhanoi is an OS/2 Presentation Manager graphical version of the "Towers of Hanoi" puzzle. Type pmhanoi or click the program icon to execute.

## List of sample files

filedump.pli | Program to dump an ENV(VARLS) file in hex and characters.
vfile.dat | Sample input for filedump
hanoi.pli | "Towers of Hanoi" batch version.
hexdump.pli | Callable procedure to print a hex/character dump of a selected area of memory.
libver.pli | Program to display the current version of the PL/I library.
numwrd.pli | Command-line program to print a number in words.
print_listing.pli | Sample program to print a PL/I compiler listing on a PCL printer.
readu.pli | Example of reading a file declared with ENVIRONMENT(U).
samples.html | This file.
sorttest.pli | Procedure to test PLISRTD
sort.dat | Test data for sorttest
task.pli | Example of PL/I multitasking. The OS/2 version runs in a VIO window, the Linux version must run in a Linux console, not an xterm.
keysamp.pli | Sample program to create and read a KEYED file
Linux only samples
spawn.pli | Procedure to FORK and EXEC a child process.
spawntest.pli | Test program for spawn.
loadsamp.pli | Sample program to load an ISAM file. Sample creates two files DIREC.I and DIREC.D in the samples directory.
loadsamp.dat | Sample data for loadsamp.
updtsamp.pli | Sample program to update an ISAM file.
updtsamp.dat | Sample data for updtsamp.
Makefile.isam | Makefile to compile and run ISAM sample programs].
Makefile.Linux | Makefile to build all Linux PL/I sample programs.
OS/2 only samples
filefind.pli | OS/2 program to locate the directory entry for a file.
pmhanoi.pli | "Towers of Hanoi" as an OS/2 presentation manager program.
sample.def | OS/2 module definition file used for all sample programs except pmhanoi.
pm.def | OS/2 module definition file used for the pmhanoi sample program.
bse.inc | some PL/I declarations for OS/2 system calls. Additions always welcomed.
Makefiles and miscellaneous
LC_make, LCC_make, SA_make | Sample makefiles for Linux giving examples of compiling and linking a PL/I program. LC_make links the compiled program with libc, but uses PL/I's malloc and free. LCC_make links with libc and uses libc's malloc and free. SA_make links a PL/I program without libc.
Makefile.OS2DLL | Makefile to build all OS/2 PL/I sample programs using the PL/I runtime DLL.
Makefile.OS2Static | Makefile to build all OS/2 PL/I sample programs using the statically-linked PL/I runtime.

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