Skip to content
Developerhome
Product homepage
X3

Classes and Representations Guide

  Less than to read

1. Overview

This guide explains how generated class and representation scripts execute: which variables are in scope, how unused events/properties are now skipped, and how dimensioned fields are handled. A recent optimization introduces an exclusion mechanism so unnecessary code (unused events and properties) stops running after the first pass. Use this page as the structural “how it works” reference; use the Troubleshooting and Coding Guide for failure patterns and fixes.

2. Variable scope and label rules

Generated labels run with strict local scope. Only the variables declared for a label exist while that label executes. Anything else is undefined; logic depending on it will fail.

Important: Referencing AMETHOD inside $EVENTS (or any variable outside its label) breaks logic because it is not declared there.

Allowed variables per label (use only these):

Classes

  • $EVENTS: CURPTH (class path), AEVENT (event code)
  • $PROPERTIES: CURPRO (property code), ARULE (requested action)
  • $METHODS: AMETHOD (method code)
  • $OPERATIONS: AOPERATION (operation code)

Representations

  • $EVENTS: CURPTH, AEVENT
  • $PROPERTIES: CURPRO, ARULE
  • $METHODS: AMETHOD

New capability (parameter size)
Class method parameters and other class-level parameter passing mechanisms can now use full CLOB (character large object) values instead of being limited to 250‑character strings. Use CLOBs when:

  • You need rich or extended textual data (descriptions, serialized JSON, etc.).
  • Truncation has previously forced workarounds (splitting into multiple fields).

Guidelines:

  1. Only switch to CLOB where real added length is required (avoid unnecessary memory + transport overhead).
  2. Validate downstream consumers of CLOBs (mutations, UI, integrations) to accept larger payloads.
  3. Keep short control tokens as standard strings for speed.

3. Skipping unused execution (AINFO.EXCLUDED mechanism)

3.1 High‑level concept

A new feature avoids repeatedly executing code for events or properties proven unused. After first evaluation, those items are recorded in an exclusion structure and skipped on later passes—improving performance and reducing branching. This applies at the class instance level so it does not globally change behavior across representations or other instances.

3.2 Tracking elements

  • AINFO.EXCLUDED: Per‑instance JSON list of excluded events/properties.
  • EVENT_NOT_EXECUTED / PROPERTY_NOT_EXECUTED: Flags you set when an event or property is determined unused in this instance.

3.3 Flow

  1. First access: evaluate the event/property.
  2. If unused: set EVENT_NOT_EXECUTED or PROPERTY_NOT_EXECUTED.
  3. Append the item to AINFO.EXCLUDED.
  4. Subsequent access: check AINFO.EXCLUDED first; skip immediately if present.

3.4 Benefits

  • Eliminates redundant checks.
  • Speeds heavy classes with many dormant hooks.
  • Removes ad-hoc “early return” boilerplate.

4. Lifecycle logic (per instance)

  1. Instance creation: Create empty AINFO.EXCLUDED.
  2. Entry to $EVENTS / $PROPERTIES: Check AINFO.EXCLUDED using (CURPTH + AEVENT) or (CURPTH + CURPRO). Skip if listed.
  3. Evaluation: If executed but unused, set EVENT_NOT_EXECUTED / PROPERTY_NOT_EXECUTED and record it.
  4. Later accesses: Immediate skip via AINFO.EXCLUDED.
  5. Instance end: Discard the exclusion list.

Illustration:

Events diagram

5. Dimensioned fields handling

Dimensioned fields now rely on an internal array when not bound to a collection, reducing overhead.

Two cases:

  1. Property is Linked to a collection: Keep existing behavior; add dimensions as before.
  2. Property is not linked: Detect if dimensioned (table/activity code). For persistent classes, store the values internally (no forced collection link).

Result: faster repeated access and simpler script logic.

6. Key takeaways

  • Stay inside each label’s declared variable set.
  • Use EVENT_NOT_EXECUTED / PROPERTY_NOT_EXECUTED plus AINFO.EXCLUDED to bypass dead hooks.
  • Avoid cross‑label assumptions (e.g. AMETHOD inside $EVENTS).
  • Internal dimension handling reduces overhead for non‑collection properties.

7. Refactoring checklist

  1. Remove cross‑label variable references (AMETHOD outside $METHODS, etc.).
  2. Add logic to set EVENT_NOT_EXECUTED / PROPERTY_NOT_EXECUTED where appropriate.
  3. Check AINFO.EXCLUDED at label start and skip early.
  4. Confirm each label only uses its allowed variable set.
  5. For dimensioned non‑collection properties, leverage internal array behavior.
  6. Keep changes incremental to reduce risk.

8. Quick reference table

Context (Classes) Variables
$EVENTS CURPTH, AEVENT
$PROPERTIES CURPRO, ARULE
$METHODS AMETHOD
$OPERATIONS AOPERATION
Context (Representations) Variables
$EVENTS CURPTH, AEVENT
$PROPERTIES CURPRO, ARULE
$METHODS AMETHOD

9. When to read the companion guide

If you hit runtime failures (missing variables, bad Gosub targets, performance regressions), switch to the Troubleshooting and Coding Guide for concrete failure patterns and corrective examples.