RPG Parser Documentation

This parser handles RPGLE, both in the fixed and in the free format, and DDS. It also offers preliminary support for RPG III (RPG/400).

Dialect	Extensions	Status
RPG IV (ILE RPG)	rpgle, rpglem, rpgleinc, sqlrpgle	Fully supported, fixed and free format
DDS	dds, pf, lf, prtf, dspf	Fully supported
RPG III (RPG/400)	rpg, rpg3, rpg38, rpgsrc, sqlrpg	Preliminary

RPG III members produce the same kind of AST as RPG IV ones: file descriptions, data definitions (including the data structures and the arrays that RPG III declares on input and extension specifications), subroutines, statements, input and output specifications and compile-time data sections. Calculation, file description, extension and input specifications are fully mapped; output specifications are mapped on a best-effort basis; control and line counter specifications are consumed without a representation in the AST. Only the first of the three conditioning indicators of an RPG III calculation specification is represented, and node positions refer to the RPG IV layout the source is adapted to, so line numbers are exact while column numbers are not those of the original member. Every unsupported construct produces a positioned issue rather than a failure: the parser always returns an AST.

It is intended to be used mainly as a JVM library. It can also be used as a command line tool.

The parser works in three different stages:

• First a list of tokens are created from some input stream (typically a File)
• Then a parse-tree is obtained by grouping the tokens and recognizing structures
• Finally an Abstract Syntax Tree (AST) is derived from the parse-tree. While the AST resembles closely the parse-tree it contains re-arrangements and simplifications that makes easier working with it.

The AST is built using the Kolasu library. This open-source library has been built by Strumenta. This tutorial on Kolasu explains how the library can be used: Building advanced parsers using Kolasu.

The AST could be used to perform analysis on the code or transformations of the code.

An example of transformations that can be created is transpilation.

Contents of the package

• Full JAR file with all dependencies
• Windows and Linux scripts to execute the JAR
• Documentation in HTML format
• An example project in Java setup with Gradle that shows how to use the RPG Parser
• An example project in Kotlin setup with Gradle that shows how to use the RPG Parser

How to use the parser

You can use the parser as a library (i.e., from code) or as a standalone program, from the command line.

How to use from the command line

This document describes how to use the RPG parser from the command line. The CLI is implemented in com.strumenta.rpgparser.cli and is distributed as a standalone JAR (rpgparser-<version>-all.jar) together with launcher scripts for Windows and Linux.

Prerequisites

• Java Runtime Environment (JRE) on the classpath. The parser has been tested with JVM 11.
• A valid Strumenta license file for the parse command. Parsing will not run unless a license is registered with --license.

Invoking the CLI

Run the JAR with java -jar:

java -jar rpgparser-<version>-all.jar COMMAND [COMMAND_OPTIONS] [ARGUMENTS...]

Running the JAR without a subcommand prints the top-level help.

Command-name casing

Subcommand names are case-sensitive. Use the exact spelling below:

Correct name	Common mistake
downloadlicense	downloadLicense, download-license
parse	—
exportsnapshot	exportSnapshot

License

Most commands require a commercial license.

Commands that require --license

Command	Option	Requirement
parse	--license PATH	Required. Path to an existing, readable license file.
exportsnapshot	--license PATH	Required. Path to an existing, readable license file.

The license path can be passed as --license path/to/file.license or --license=path/to/file.license.

The license file must exist and be readable. Symlinks are accepted.

Commands that do not require a license

Command	Purpose
downloadlicense	Download a new license from the Strumenta license service.

Downloading a license

Use downloadlicense to obtain or refresh a license. Provide your credentials and the destination path:

java -jar rpgparser-<version>-all.jar downloadlicense USERNAME PASSWORD path/to/license.file

On success, the CLI prints confirmation and the license validity period:

License successfully downloaded at path/to/license.file
StartDate: Mon Nov 04 01:00:00 CET 2024
EndDate: Sat Dec 07 01:00:00 CET 2024

Downloaded licenses expire depending on your subscription or contract. Anytime you download a license, it will be downloaded with the updated expiration date.

Commands

parse — parse RPG files

Parses one or more RPG source files (or directories) and writes each AST to a file. Supported extensions are .rpgle, .sqlrpgle, and .dds (case-insensitive). When you pass a file with another extension explicitly, it is treated as RPG LE (.rpgle). When walking directories, files with unrecognized extensions are skipped.

java -jar rpgparser-<version>-all.jar parse --license=my.license [OPTIONS] INPUT [INPUT]...

Option	Description
--license PATH	Required. License file.
-c, --charset TEXT	Charset used to read input files. Default: UTF-8.
--ignore-positions / --consider-positions	Control whether source positions are included in the AST. Positions are included by default (--consider-positions).
-f, --format [json|xml]	Output format for serialized ASTs. Default: json.
-o, --output PATH	Directory where output files are stored. Default: current directory (.). The directory is created if it does not exist.
-s, --stats	Print statistics on how many files were processed successfully and how many had errors.
-e, --error-stats	Print statistics on the prevalence of different error messages.
--no-output	Parse without writing AST files. Useful together with --stats or --error-stats.
-v, --verbose	Print additional progress messages (including per-file error/warning counts).
-h, --help	Show command help.

Arguments

Argument	Description
INPUT	Required (at least one). Path to a file or directory. Directories are walked recursively. At least one input must be provided; otherwise the CLI exits with an error.

Output layout

• For each processed source file, the CLI writes <output-dir>/<filename>.json or <output-dir>/<filename>.xml (for example MYPGM.rpgle becomes MYPGM.rpgle.json).
• When an input is a directory, the output mirrors the input directory structure under --output, using the directory name as a subdirectory.

Examples

Parse a single file and write JSON next to the current directory:

java -jar rpgparser-<version>-all.jar parse --license=strumenta.license example.rpgle

Parse multiple inputs into a chosen output directory, with XML output and verbose logging:

java -jar rpgparser-<version>-all.jar parse --license=strumenta.license -f xml -o ./out -v sources/ example.sqlrpgle

Parse a directory and only print processing statistics (no AST files):

java -jar rpgparser-<version>-all.jar parse --license=strumenta.license --no-output --stats ./rpg-sources

Each JSON or XML file contains the AST (root) and any parsing issues.

---

exportsnapshot — export a LionWeb snapshot

Analyzes an RPG codebase (parse + symbol resolution + analyzer) and writes a StarLasu-style LionWeb snapshot: a ZIP whose entries are {partitionId}.binpb ProtoBuf chunks.

By default the command exports a full snapshot, which includes:

• traditional partitions: languages, codebase metadata, and codebase files with source code, tokens, and (semantics-enriched) ASTs
• analyzer partitions: go-to-definition catalog, sequence diagrams, and dependency graph

You can also export an analyzer-only snapshot with --kind=analyzer.

java -jar rpgparser-<version>-all.jar exportsnapshot --license=my.license [OPTIONS] INPUT_DIR

Option	Description
--license PATH	Required. License file.
--kind TEXT	Snapshot kind: full (default) or analyzer.
-o, --output PATH	Destination file for the snapshot (typically .zip or .sps). Default: rpg-analyzer-snapshot.pb.zip. Parent directories are created if needed.
--codebase-name TEXT	Logical name assigned to sources in the codebase. Default: UnnamedCodebase.
-v, --verbose	Print additional progress messages (codebase path and file count).
-h, --help	Show command help.

Arguments

Argument	Description
INPUT_DIR	Required. Directory containing the RPG codebase. The directory must exist and be readable. Files are discovered using the usual RPG extensions (for example .rpgle, .sqlrpgle, .dds).

Examples

Export a full snapshot of a codebase to the default output file:

java -jar rpgparser-<version>-all.jar exportsnapshot --license=strumenta.license ./rpg-sources

Export a full snapshot to a chosen .sps file, with a codebase name and verbose logging:

java -jar rpgparser-<version>-all.jar exportsnapshot --license=strumenta.license --codebase-name=MyApp -o ./out/myapp.pb.sps -v ./rpg-sources

Export an analyzer-only snapshot (no traditional AST/codebase-file partitions):

java -jar rpgparser-<version>-all.jar exportsnapshot --license=strumenta.license --kind=analyzer -o ./out/analyzer.pb.zip ./rpg-sources

On success, the CLI prints the absolute path of the written snapshot file.

---

downloadlicense — download a license

Described in Downloading a license above.

Getting help

Help is available at every level:

# Top-level help and command list
java -jar rpgparser-<version>-all.jar --help

# Help for a specific command
java -jar rpgparser-<version>-all.jar parse --help
java -jar rpgparser-<version>-all.jar exportsnapshot --help
java -jar rpgparser-<version>-all.jar downloadlicense --help

Quick reference

Goal	Command
Write AST JSON files	parse --license=… INPUT…
Write AST XML files	parse --license=… -f xml -o OUT_DIR INPUT…
Parse without writing files	parse --license=… --no-output [--stats] [--error-stats] INPUT…
Export full LionWeb snapshot	exportsnapshot --license=… INPUT_DIR
Export analyzer-only snapshot	exportsnapshot --license=… --kind=analyzer -o OUT.zip INPUT_DIR
Obtain a license	downloadlicense USER PASS PATH

How to use as a library

You can use this parser as any other library, directly from your code.

Download a license

You can also download an updated license using the method download license in the LicenseValidation class.

LicenseValidation lv = new LicenseValidation();
lv.downloadLicense("user", "pass", "location.license");

Using a license

This parser requires a license to be used. You can use LicenseManager to register the license by providing the license file as argument. You need to register the license once in the program.

import com.strumenta.kolasu.commercial.LicenseManager;
import com.strumenta.rpgparser.RPGKolasuParser;
[..]
LicenseManager.INSTANCE.registerLicense(new File("data/example.license"));

You can then instantiate the parser to parse your RPG code (either as a string or as a file). The simplest approach is to let the parser choose the file type from the extension:

RPGKolasuParser rpgParser = RPGKolasuParser.parserFromExtension(rpgFile);
ParsingResult<CompilationUnit> result = rpgParser.parse(rpgFile);

You can also construct a parser for a specific file type (RPGLE, SQLRPGLE, or DDS):

RPGKolasuParser rpgParser = new RPGKolasuParser(RPGFileType.RPGLE);
ParsingResult<CompilationUnit> result = rpgParser.parse(input);

Consult the cookbook for more examples of uses of the parser.