Sage X3 L4g

Sage X3 L4G — Development Assistant (V12)

L4G (langage de 4ème génération), also called "X3 script", "4GL", "Adonix", or "SAFE X3 script", is the proprietary scripting language of the Sage X3 / Sage Enterprise Management ERP. It's what you write in .src (source / subprograms) and .trt (treatment / processing) files to customize screens, validate data, orchestrate transactions, call reports, and extend business logic on top of the X3 standard.

This skill targets V12 (and by extension V7+), covering the modern stack: Classes, Representations, Pages, Syracuse, REST endpoints. Legacy Classic syntax (Masks, Inpbox) is still included because it runs unchanged in V12 and a lot of production code uses it.

This skill gives you enough context to read, write, review, and debug L4G correctly — avoiding the common traps that bite anyone coming from mainstream languages (C/Java/Python).

When to use this skill

Trigger whenever the user:

• Asks to write or review a Sage X3 script, subprogram, process, or "action champ"
• Pastes code with [M:...], [F:...], [V], [L], [S] prefixes, Trbegin, Readlock, Funprog, Subprog, Call ... From ..., Onerrgo, Local File, Mask, Inpbox, Gosub
• Mentions Sage X3 customization, specific activity codes, personalization, vertical development, migrating Classic/V6 to V7/V12
• Mentions three-letter uppercase abbreviations in brackets (e.g. [BPC], [ITM], [GACC], [F:SOH], [M:FNC]) — these are standard X3 table/mask/class references
• Talks about "specific screens", "entry transactions", "screen customization", "supervisor", "GACTION", "GESAUT"

Don't trigger on generic 4GL discussions unrelated to Sage (e.g. Informix 4GL, OpenEdge ABL, Oracle Forms) unless Sage X3 is explicitly involved.

Mental model — the essentials you must internalize

L4G is not a general-purpose language. It was designed around the X3 runtime ("engine" / adonix), which wraps the compiler, the screen manager, and the database driver. Four things make L4G look strange at first:

1. Everything is UPPERCASE and case-insensitive for symbols, but keywords are case-sensitive in form

Variable names like FOO, Foo, fOo all refer to the same symbol — the editor rewrites them as FOO. Keywords like For, If, Endif, Local, Value, Return are reserved words. The convention is PascalCase for keywords, UPPERCASE for identifiers.

2. Class prefixes in brackets tell you where a variable lives

Omitting the prefix is allowed when unambiguous, but always include it when reading or writing code you didn't author — it makes scope explicit and prevents subtle bugs.

3. Comments use :# inline or # at start of line

# This is a full-line comment
Local Integer I : # This is an inline comment after a statement separator

The colon : is the statement separator (not a line terminator like ; in C). You can put multiple statements on one line:

If [S]fstat : Rollback : End [V]CST_AERROR : Endif

4. fstat is the status code that nobody prints but everyone must check

Every database or sequential-file operation sets [S]fstat. Zero means success; anything else means an error occurred. Always check fstat after Read, Readlock, Write, Rewrite, Delete, Update, For, Openi, Openo, or you will ship silent bugs.

Reference files — consult these when needed

This skill is organized by concern. Read the relevant reference file when you encounter its topic. Don't preload them all.

Core language and conventions

UI — Classic and V12

Integration and operations

Meta

How to respond to L4G requests

When the user asks you to write code

1. Clarify the context first. "Is this for a V6/Classic or V7/V12 target? Standard folder or X3 custom?" — V7 syntax (Funprog, classes, Method) differs materially from V6.
2. Always respect naming conventions. Custom (specific) code uses Y or Z prefix for symbols, tables, screens, messages — never overwrite standard X3 names.
3. Wrap database writes in a transaction. Trbegin / Commit / Rollback, with fstat checks after each operation. See references/database.md.
4. Use the If adxlog idiom when your subprogram may be called inside or outside an existing transaction — let the caller own the transaction if it already started one.
5. Include traces for non-trivial logic: Call ECRAN_TRACE("msg") From GESECRAN or Infbox "..." during development, removed or gated before production.
6. Format output like real X3 code: PascalCase keywords, UPPERCASE identifiers, indentation with spaces, :# inline comments.

When the user pastes code to review

Run the structured pass in references/code-review-checklist.md — it covers correctness, conventions, V12 idioms, security, performance, and style, ranked by blast radius. The headline red flags to surface first:

1. Missing fstat check after a database or file operation
2. Write / Rewrite / Delete without Trbegin … Commit / Rollback
3. Readlock without a matching release path (commit, rollback, or explicit unlock)
4. Long-running loops inside a Trbegin block → deadlock risk, the engine holds locks until commit
5. Onerrgo without a reachable recovery label
6. Hard-coded folder names (GESBPC vs ZGESBPC) or language-dependent strings — should use mess(n, chapter, 1)
7. Custom code that overwrites a standard symbol (no Y/Z prefix)
8. Goto across subprogram boundaries (legal but almost always a bug)
9. Next used on a For loop that was modified inside the loop body

State each issue with the exact line, explain why it's a problem, and propose the fix. Pull from code-review-checklist.md, security-permissions.md, and performance.md for the full set of checks.

V12 default idioms (prefer over Classic)

When writing new code, reach for the V12 idiom unless the user is explicitly extending Classic code:

• Classes + this instead of free-floating Subprog globals, for anything with state or more than one step — see references/v12-classes-representations.md
• Representations + pages instead of Mask + Inpbox for any new UI
• REST services (class-backed service representations) instead of classic SOAP for new integrations
• UPDTICK in Where clauses for optimistic concurrency on custom Update / Rewrite
• IMP/EXP templates (dictionary-driven) instead of hand-rolled file parsers — see references/imports-exports.md
• Workflow rules (GESAWR) instead of scattered email-sending code — see references/workflow-email.md

Classic Mask, Inpbox, SOAP, and Call … From … are all still supported and frequently encountered in existing code. Read it fluently, but don't reach for it when starting fresh.

When the user asks about V6 → V12 migration

Key shifts to mention:

• Subprog / Funprog remain, but classes (Class, Method, Public, Private, this) are the V12 idiom
• The classic Mask / Inpbox UI is superseded by Representations + Pages rendered by Syracuse, but legacy screens still run
• Local File TBL is replaced in V12 code by dependency-injected classes where possible — the DB primitives underneath (Read, For) are unchanged
• UPDTICK column and snapshot patterns are the V12 concurrency helpers
• Every published representation gets a generated REST API under /api/x3/erp/<folder>/<object> — SOAP web services remain for backwards compat

Full detail in references/v12-classes-representations.md.

A quick canonical example

A typical transactional subprogram looks like this:

##############################################################
# YTRANSFER - Transfer AMOUNT from ACCOUNT1 to ACCOUNT2
# Returns [V]CST_AOK on success, [V]CST_AERROR on failure.
##############################################################
Funprog YTRANSFER(ACCOUNT1, ACCOUNT2, AMOUNT)
Value Char     ACCOUNT1(), ACCOUNT2()
Value Decimal  AMOUNT
Local  Integer IF_TRANS

Local File ACCOUNT [ACC]

# Start a transaction only if none is already in progress
If adxlog
    Trbegin [ACC]
    IF_TRANS = 0
Else
    IF_TRANS = 1
Endif

# Debit
Update ACCOUNT Where CODE = ACCOUNT1 With BALANCE = BALANCE - AMOUNT
If fstat
    If IF_TRANS = 0 : Rollback : Endif
    End [V]CST_AERROR
Endif

# Credit
Update ACCOUNT Where CODE = ACCOUNT2 With BALANCE = BALANCE + AMOUNT
If fstat
    If IF_TRANS = 0 : Rollback : Endif
    End [V]CST_AERROR
Endif

If IF_TRANS = 0 : Commit : Endif
End [V]CST_AOK

Note: Y prefix → custom code; adxlog guard → nested-transaction safety; fstat check after each DB op → correct; two-space indent + PascalCase keywords → house style.

That's the tour. Load the relevant reference file(s) when a specific topic comes up, and always prefer to show a complete, runnable example over prose description — L4G is a language people learn by reading, not by theory.