Troubleshooting

This chapter covers common issues you may encounter when compiling or running RPG programs with Triton RPG, and how to resolve them.

Compile-Time Errors

TRNxxxx Diagnostics

Every compiler diagnostic carries a code like TRN2001. Look up the code in the Diagnostic Reference for a detailed explanation and remedy. The compiler reports every error it finds before stopping - read the full list, as later diagnostics often clarify earlier ones.

"Externally-described file has no available layout"

The compiler cannot find a .pf (physical file) or .dspf (display file) matching the file name declared in your program. Ensure the DDS file is in a directory listed by --dds-path:

rpgc --dds-path dds/ myprogram.rpgle

The file must be named to match the RPG file declaration: a program that declares DCL-F CUSTMAST or FCUSTMAST needs a file named CUSTMAST.pf (case-insensitive) in the DDS path.

"Undefined variable" After Adding a Field to DDS

If you add a field to a DDS file but the compiler does not see it, verify that the DDS file is in the --dds-path and that the record-format name in the DDS matches what the RPG program expects. The compiler resolves externally-described fields at compile time from the DDS source, or - when verify mode is enabled with --verify-jdbc-url - from the database catalog. Without verify mode a change made only in the database is not seen; the DDS on the --dds-path is what the compile reads.

Runtime Errors

ClassNotFoundException

The JVM cannot find a class on the classpath. Common causes:

JDBC_URL environment variable is not set

Your program uses SQL, disk files, or data queues, which require a database connection. Set the JDBC environment variables before running:

export JDBC_URL='jdbc:as400://myhost;libraries=MYLIB'
export JDBC_DRIVER='com.ibm.as400.access.AS400JDBCDriver'
export JDBC_USER='myuser'
export JDBC_PASSWORD='mypassword'
java -cp out:triton-rpg.jar:jt400.jar MYPROGRAM

If your program does not use any database features (no EXEC SQL, no externally-described disk files, no data queues), it does not need these variables. See JDBC Database Connectivity for details.

VerifyError or AbstractMethodError

These are JVM-level errors that typically indicate a compiler bug. Please report them - include the RPG source, the compiler version (rpgc --version), and the full stack trace. See Getting Support below.

RpgHaltException (Exit Code Non-Zero)

The RPG program executed a SETON on an H-indicator (H1 - H9) or encountered an unhandled error. This is normal RPG behavior - the program is signaling an abnormal end. Check the program's logic for the condition that triggered the halt.

RpgStatusException (Status Code in Message)

A runtime operation failed with an RPG status code. The status code in the exception message corresponds to the standard IBM i status codes:

Stack Traces

When reporting an issue, include the full Java stack trace. If the program crashes, the JVM prints the trace to standard error. To capture it:

java -cp out:triton-rpg.jar MYPROGRAM 2>error.log

Include the full trace as printed; it is what makes the report actionable.

Getting Support

When contacting support, include:

1. Compiler version: output of rpgc --version
2. RPG source: the smallest program that reproduces the issue
3. DDS files: any .pf or .dspf files the program uses
4. Command line: the exact rpgc command and java command used
5. Full error output: compile-time diagnostics or runtime stack trace
6. Database: which database backend and JDBC driver version

Email support@whitehorn.ltd or use the client portal at portal.whitehorn.ltd.