JVM Options & Runtime Configuration for the Heirloom PL/I Runtime

Table of Contents

1. Overview
2. Diagnostic tracing
3. SQL / DB2 connections
4. Character encoding
5. Quick reference
6. Related articles

Audience: operations engineers and developers running PL/I applications migrated to Java with Heirloom.

Overview

When your PL/I programs are migrated with Heirloom, they run as ordinary Java processes on the JVM. The Heirloom PL/I Runtime reads a small set of JVM system properties (the -D options you pass on the java command line) to control diagnostics, dataset (DD) resolution, SQL connections, and a few compatibility behaviors.

This article lists the supported options, explains what each one does, and gives practical recipes.

Two rules that apply to every option below:

1. Set them at JVM start, not at runtime. The runtime reads most properties once, when the relevant class is first loaded. Setting them later in the run has no effect.
2. They are off / default unless you set them. An unset JVM behaves exactly as production expects — none of these options change behavior until you opt in.

How to pass an option

java -Dheirloom.trace=true \
     -Dsql.default.url="jdbc:db2://host:50000/MYDB" \
     -jar my-application.jar

In a container or application server, add the same -D... flags to the JVM arguments (for example JAVA_OPTS, JAVA_TOOL_OPTIONS, or the server's startup script).

1. Diagnostic tracing

These two options turn on the runtime's built-in tracer. It follows the low-level plumbing — pointer creation/resolution, storage cleanup decisions, and the transaction link/close lifecycle — so you can diagnose a live (or reproduced) problem without rebuilding or redeploying the application.

You can use either or both — enabling the file also enables tracing internally, so the two outputs compose.

CSV columns:

seq,site,thread,execId,decision,reason,structureClass,name,key,shared,global,refNull,refType,hashcode

When to use it

• A screen renders blank, a field comes back empty, or you see a "buffer too small / TOOSMALL" style error — the trace shows whether a piece of storage was reclaimed too early.
• You are investigating memory growth and want to see what the runtime keeps vs. reclaims at each transaction boundary.

Performance note: tracing is verbose and writes on hot paths. Enable it to reproduce a specific issue, then turn it off for normal operation. Tracing never throws into your application — if the trace file cannot be opened, the runtime logs a warning and simply continues without tracing.

# Reproduce once with tracing to a file, then analyze:
java -Dheirloom.trace.file=/tmp/app-trace.csv -jar my-application.jar

2. SQL / DB2 connections

When a program uses EXEC SQL, the runtime opens its database connection from JVM properties in the sql.<connection>.* namespace. The default connection is named default; named connections let one application target several databases.

java -Dsql.default.url="jdbc:db2://db2host:50000/PRODDB" -jar my-app.jar

If a referenced connection has neither a URL nor a datasource configured, the runtime falls back to the default connection. See your DB2/SQL connection setup guide for the complete attribute list and credential handling.

3. Character encoding

The runtime serializes character data using a configurable byte encoding, defaulting to ISO-8859-1 (single-byte, matching common EBCDIC-to-Latin1 migration pipelines). The active encoding can be overridden by the deployment's BE (byte-encoding) configuration value; if you need a different code page for file or terminal I/O, set it there. If nothing is configured, ISO-8859-1 is used.

Quick reference

Related articles

• How the PL/I Runtime Manages Memory — what the tracer's storage decisions mean (structures, pointers, GWA, BASED/DEFINED).
• How Transactions Are Managed (ETP + PL/I Runtime) — what the [TRACE] link / close lines represent.