FWD » Core Development » Conversion Tools

The Debug Adapter Protocol is a platform independent protocol for separating the debugging back-end from the debugger UI. As such it allows the same back-end debugging support to be used by multiple IDEs.

It is an open standard, originally created by Microsoft for the VSCode product. It is being adopted by multiple IDEs now and it is a kind of companion to the Language Server Protocol.

It is required to be built for our VSCode extension in #11355.

FWD 4GL debugger (DAP) and VS Code extension: what works today (2026-10-29)

• Overview
• Getting started
• Debugging features
  • Breakpoints
  • Stepping and threads
  • Call stack
  • 4GL ⇄ Java mode
  • Variables
  • Watch, hover, Debug Console
  • Set Value
• Java View
• Limitations
• Useful tips
• Status

Overview¶

The FWD 4GL debugger debugs converted 4GL programs from VS Code at the level of 4GL statements. It attaches to a running FWD server and works on the preprocessed .cache file of each program in the conversion folder (cvt/…/<program>.p.cache, .w.cache, .cls.cache): breakpoints, stack frames and steps all refer to .cache lines, include files included. A toggle switches the same session to the generated Java at any time, and the Java View shows the generated Java beside its .cache file, kept in sync by the cursor and by debug stops. The FWD runtime is unchanged: the server only needs JDWP enabled.

Getting started¶

1. Convert the project with this FWD build and run ant deploy, so every program gets a <program>.dbgmap file next to its .cache.
2. Build FWD in the project's p2j tree (./gradlew jar); the extension starts the debug adapter from there. The adapter needs a JDK (setting fwd4gl.server.java, default java).
3. In the extension folder (tools/vscode-4gl): npm install (first time only), npm run compile, then F5 "Run Extension (clean)", and open the converted project folder (the one with cfg/p2j.cfg.xml) in the new window.
4. Start the server with JDWP: cd deploy/server && ./server.sh -d (JDWP port 2080). The server then runs interpreted, so everything is slower.
5. Add the attach configuration to launch.json (also offered as the snippet "FWD 4GL: Attach to FWD server"):

{ "type": "fwd-4gl", "request": "attach", "name": "Attach to FWD server",
  "host": "localhost", "port": 2080 }

6. Optional attribute projectRoot points to the converted project when it is not the open folder. Start the debug session, open cvt/…/<program>.cache, set breakpoints, then run the client.

Same FWD build on both sides. The adapter and the server must run the same FWD build. Otherwise the Debug Console shows FWD version mismatch and Buffers, Shared, System, handle attributes and buffer fields show <unavailable: FWD version mismatch> and Set Value is refused (breakpoints, stepping, stack, Locals and Program still work). Fix: rebuild FWD, run ant deploy.prepare (or ant deploy) in the project, restart ./server.sh -d and attach again.

Attach errors say what is wrong, e.g. No JDWP agent at host:port (start the server with -d) or JDWP refused the connection; another debugger may be attached (only one debugger can attach to a server).

Debugging features¶

Breakpoints¶

• Set on lines of .cache files. A breakpoint on a blank, comment, DEFINE or END line moves to the next statement with code in the same block; the dot shows the adjusted line.
• A breakpoint that cannot be placed stays unverified with the reason (no 4GL map, map stale: …, class not loaded yet — installed when the class loads).
• Breakpoints work in loops (every iteration), in several programs at once, on include lines, and can be added or removed while stopped.
• Conditions (Edit Breakpoint → Expression): a 4GL expression; stops only when it is yes. An error or a non-LOGICAL result stops and prints Breakpoint condition error: ….
• Hit counts, counted over hits whose condition held; they restart when any breakpoint of the file is edited:

Form	Stops at
N or ==N	the Nth hit only
>N, >=N, <N, <=N	hits compared with N
%N	every Nth hit

• Logpoints (Log Message): each {expression} is replaced by its value (or <error: …>), the line goes to the Debug Console and the thread runs on.

Stepping and threads¶

• Step Over, Step Into and Step Out move by 4GL statement and follow the real control flow (LEAVE, NEXT, UNDO/RETRY, ON ERROR, CATCH/FINALLY, RETURN).
• Step Into enters procedures, functions, methods, constructors, property accessors, triggers, external and persistent procedures (RUN, RUN … IN, DYNAMIC-FUNCTION, super procedures, PUBLISH subscribers, RUN VALUE).
• Step Over runs a called routine at full speed; Step Out returns to the next statement of the caller.
• DEFINE statements are not stop points; a step stops only once per line (IF x THEN NEXT. stops once).
• Continue and Pause act on the selected thread only.
• Each client session is a thread (Session <id> (<account>); appserver workers as <Type> worker #<n>). Only the session that hits a breakpoint stops; the others run on.
• Disconnect removes the breakpoints, resumes the stopped threads and leaves the server and all clients running.

Call stack¶

• In 4GL mode each 4GL routine is one frame on its .cache line, e.g. start.p:42 (FOR EACH) for the main block and process-value (start.p:95) for an internal procedure. FWD runtime frames are hidden; recursion and triggers get their own frames.
• Selecting an outer frame shows its variables and evaluates expressions in it.
• A program without a usable map appears as a dimmed Java frame marked (no 4GL map) or (map stale).

4GL ⇄ Java mode¶

Switch with the debug toolbar button "4GL ⇄ Java" (arrow-swap icon), the status bar item FWD: 4GL / FWD: Java, or the command "4GL ⇄ Java" in the command palette. Stopped threads stay where they are.

	4GL mode	Java mode
Threads	Sessions, workers, stopped threads	All JVM threads
Stack	4GL frames on .cache lines	Every Java frame on .java lines
Variables	4GL scopes	this and Java locals
Stepping	By 4GL statement	By Java line
Evaluate	4GL expressions	Not available

Breakpoints stay on .cache lines in both modes.

Variables¶

Scope	Contents
Locals	Parameters (with their mode, e.g. n (INPUT)) and variables of the routine; for the main block, the program variables; the variable of a CATCH block, only while its CATCH runs
Program	Program-level (class-level) variables, in internal procedures, functions and methods; STATIC data members with the value of the stopped session
Buffers	Buffers in scope, temp-tables (default buffer), BUFFER parameters
Shared	Shared and global shared variables, buffers, temp-tables
System	ERROR-STATUS, SESSION, THIS-PROCEDURE, SOURCE-PROCEDURE, TARGET-PROCEDURE, SELF

• Values look like 4GL: "text", 42, yes/no, ?, dates in the session DATE-FORMAT, DECIMAL as STRING() shows it, RAW and MEMPTR as a hex dump.
• Extents show [n] and expand to their elements (pages of 100).
• Handles show id and type, e.g. 1002 (PROCEDURE), and expand to their attributes. A handle the program never asked the id of shows only (PROCEDURE). An attribute whose getter reports a 4GL error shows <error: ** … (nnnn)> in place of the value; the debugged session is not affected (no message to the user, ERROR-STATUS unchanged, nothing reaches its CATCH).
• Objects show their 4GL class name and expand to data members and properties, inherited ones included. STATIC members show the value of the stopped session, or <not set in this session yet> before the session used the class.
• Buffers show record available, NO-LOCK or no record and expand to the fields of the current record under their 4GL names.
• Computed properties (GET with a body) are lazy: expanding runs the GET once.
• THIS-PROCEDURE is the procedure of the selected frame.

Watch, hover, Debug Console¶

Available in 4GL mode on the selected frame. The expression language (also used by conditions and logpoints) has literals (numbers, strings, yes/no, ?), names, name[i], buffer.field, h:ATTR, obj:Member, the operators OR AND NOT = <> < > <= >= BEGINS + - * / (and EQ NE LT GT LE GE) with 4GL semantics, and parentheses. There are no function calls, assignments, date literals or system handles as names (SESSION:…).

• Watch and Debug Console results that are extents, handles, objects or buffers expand as in the Variables view.
• Hover shows the reference under the mouse (name, buffer.field, name[i], h:ATTR chains); keywords, strings and comments give no hover. A hover never runs a computed property's GET; Watch and Debug Console do.

Set Value¶

"Set Value" in the Variables view takes an expression. Allowed: variables, parameters and extent elements of Locals and Program of type CHARACTER, LONGCHAR, INTEGER, INT64, DECIMAL, LOGICAL; ? sets the unknown value. A STATIC data member is set in the stopped session only. The value is stored as an ordinary 4GL assignment (undo applies). Refused, with a message: other types (DATE, DATETIME, HANDLE, objects, RAW, MEMPTR, RECID, ROWID), properties, buffers, buffer fields, object members, Shared and System, a whole extent, out-of-range numbers, and text into a number.

Java View¶

Shows the generated Java of a program beside its .cache and keeps both in step, with or without a debug session.

• Open: command "FWD: Open Java View", Ctrl+Alt+J, or the title-bar button on a .cache editor (from a generated .java it opens the .cache). The two also link by themselves when the .cache and its .java are both visible in two editors.
• Cursor sync, both ways: the cursor on a 4GL statement highlights all its Java lines, and a Java line highlights its 4GL statement. This includes DEFINE statements (their declaration), PROCEDURE/FUNCTION/method headers (method signature), routine END lines (closing brace) and block END lines of DO/FOR EACH/REPEAT.
• Debug stops: in 4GL mode the Java shows the statement's lines subtly and the exact line the JVM is at strongly; in Java mode the .cache shows the 4GL statement line. The highlight follows the selected Call Stack frame and clears on Continue or a step.
• The view follows the program of the active editor and never takes the focus.
• The Java tab carries a green J badge while the map is current and a yellow S when the .cache or .java changed since conversion; the status bar then shows FWD Java View: map stale — reconvert and no highlights are drawn.
• The Java file of the pair is read-only while linked.
• Closing the Java tab ends the link; hiding it behind another tab or moving it to another group does not.

Limitations¶

• Attach only: no launch of server or clients from VS Code.
• Breakpoints only in .cache files, not in the .p/.w/.cls/.i sources or in .java files.
• No exception, function or data breakpoints; no DEBUGGER system handle (#11985).
• Expressions: no function calls, assignments, date literals or system handles as names.
• Set Value: only the types and targets listed above.
• Step Over a RUN that reads many records is about twice as slow as without the debugger.
• DO j = 1 TO n revisits its header line at every iteration (REPEAT / FOR EACH do not).
• SOURCE-PROCEDURE and TARGET-PROCEDURE are shown for the innermost frame only.
• A handle attribute whose getter reports a 4GL error (e.g. DATA-SOURCE-COMPLETE-MAP of a buffer outside a dataset) shows <error: ** … (nnnn)> in place of the value; the debugged session is not affected. The OpenEdge debugger shows ? there.
• The variable of a CATCH block is shown only while its CATCH runs; a built-in error object (Progress.Lang.SysError, AppError) does not show its properties yet, and methods such as err:GetMessage(1) cannot be called from a watch.
• Watches run computed-property GETs again at every stop.
• A thread stopped by Pause shows no Buffers, Shared, System or handle attributes; step once to inspect it.
• A value read that takes more than 5 s shows <timed out>; that thread reads no more values until its next stop.
• Computed EXTENT properties show their backing field.
• Java View: DEFINE FRAME, widgets (BUTTON, RECTANGLE, IMAGE, BROWSE) and MENU have no Java lines; trigger END, property GET/SET END and a few other END lines are not mapped.
• Hover reads one line, so a line inside a multi-line comment gives no hover.
• This extension cannot run together with the #11741 extension yet: both have the same extension id.

Useful tips¶

• After a commit or rebuild of FWD: ./gradlew jar, ant deploy.prepare in the project (ant deploy when 4GL code or conversion changed), restart ./server.sh -d, attach again; skipping this gives the version mismatch.
• After changing a 4GL program, reconvert and redeploy it; until then its breakpoints stay unverified with map stale and the Java View shows the S badge.
• After an update of the extension: npm run compile and reload the extension window.
• Output channel FWD Java View gives the details of Java View failures (link failures, unreadable maps, missing Java lines).
• Debug Console messages explain refused actions and stale maps.

Status¶

• All code (debug adapter, .dbgmap generation in conversion, VS Code extension tools/vscode-4gl) is committed in a local git repository (branch 11742a, head 15dc430). Nothing is committed to bazaar yet.
• Remaining: include the changes in the bazaar branch 11741a, together with the LSP, as several themed commits (being prepared); merge tools/vscode-4gl with the #11741 extension (only extension.ts, package.json and README.md need a manual merge; the debugger files add without clashes).