Language Versions and Migration

An MDL script is written in one language version, declared by its first statement:

mdl 1;

create persistent entity Shop.Customer (
  Name: String(200)
);

A script file with no header is mdl 0, the alpha language. The rest of this manual documents mdl 1; this page is the one place that documents what mdl 0 means differently, and how to move a script from one to the other.

Two rules make the move safe (ADR-0011):

• A script never changes meaning because a newer mxcli runs it. A change of meaning, or a new rejection, applies only under the header that introduces it. Without the header the old meaning is kept, and the construct warns with an MDL-V1-* code.
• A deprecated spelling is a respelling. It means exactly what its new form means, warns with an MDL-DEPR* code, and mxcli fmt --upgrade rewrites it. It is refused only from the version named in its entry.

Every warning that carries one of these codes ends with a pointer such as (mxcli help MDL-V1-LIMIT1). That command prints the code’s entry: the old form, the new form, whether fmt --upgrade rewrites it, and the version that refuses it. mxcli syntax <topic> --deprecated lists the old spellings of one topic.

mdl 1 is frozen

mdl 1 was frozen at beta. It is a contract: a later change of meaning needs a new version, mdl 2, and a script headed mdl 1; means the same under every later mxcli release. What that changes in practice:

Before the freeze mdl 1; warned “preview: may still change” (MDL-LANG01); that warning is gone. A header after the first statement must name the same version as the first: mdl 0; after mdl 1; is an error, and so is mdl 1; part-way through a script that started without one.

What a script without the header means

Each construct below is refused under mdl 1; and accepted without the header, where it keeps its old meaning and warns with the code shown.

Strings without the header

A script without the header (mdl 0) still reads a backslash before n, r, t, \ or ' as an escape — 'C:\temp' holds a tab — and check warns MDL-V1-ESCAPE for each literal whose value changes under mdl 1. Write the backslash-free form ('it''s') to mean the same under both.

In a microflow or nanoflow expression, without the header 'C:\\temp' stores 'C:\temp' and 'it\'s' stores 'it''s': the stored expression is the same value, spelled as Studio Pro spells it.

describe --mdl 0 keeps the mdl 0 escapes (\n, \\): in a flow’s expression and an XPath constraint it writes a stored backslash as \\, so the description reads back as the stored value under mdl 0. mxcli fmt --upgrade rewrites an mdl 0 script’s escaped strings to the mdl 1 form. An expression whose string holds an escaped line break is written as the expression Mendix stores for it, since an expression that spans lines is stored exactly as written.

Without the header a template literal that spans lines and has no parameters is an expression instead — the template is {1} and the literal its parameter — and check warns MDL-V1-TEMPLATE. With with ({n} = …) parameters it is the template text under both versions.

How to migrate a script

1. Commit the script first, so the upgrade is one reviewable diff.

2. Upgrade it with the project it runs against, and let the upgrade add the header. Never type mdl 1; by hand: the upgrade adds it only after rewriting every construct whose meaning the header would change, and refuses when one has no rewrite.

   mxcli fmt --upgrade -w -p app.mpr script.mdl
   

   The header is the default since the freeze; --header still says so explicitly, and --header=false upgrades the spellings alone.

   The project (-p) answers what the script alone cannot: whether find(…) over a flow’s result is the string function or the list operation, which bare commit statements the stored flows run without events, and which create or modify statements exec would refuse under the header. The project is only read.

3. Read what it reports on stderr. A deprecated spelling with no mechanical rewrite is left in place and listed as “not upgraded”; a header-gated construct with no rewrite blocks the header, and the file keeps its version. Fix those by hand (mxcli help <code> says how) and upgrade again.

4. Check it against the project, the way exec will read it:

   mxcli check script.mdl -p app.mpr --references
   

   check -p reports everything exec would refuse under the header, computed by the same code exec uses, so a refusal shows up here and not halfway through a run.

5. Run it twice. The first exec applies the script; the second must write nothing, and report every document unchanged. A second run that writes is a script that does not say what the project holds — the upgrade’s job is to make it say so — and is worth reporting.

   mxcli exec script.mdl -p app.mpr
   mxcli exec script.mdl -p app.mpr   # expect: nothing written
   

Test files (.test.mdl, .test.md) are upgraded the same way: the statements in their blocks are rewritten, and doc comments (@test, @expect, …), separators and prose are kept byte for byte. The header goes on the first line of a .test.mdl file and on the first line inside each mdl-test block of a .test.md file; --header=false declines it, as for a script. The runner and check read it, so a test body means under the header what it means in a script (see Test Formats).

One dialect per file. Upgrade a headerless file before editing it; do not add mdl 1 statements to an mdl 0 file.

What the upgrade does, in order

mxcli fmt --upgrade changes nothing but the constructs below; comments, layout and keyword case survive, and the result is re-parsed before it is written.

1. Deprecated spellings become their new form (the MDL-DEPR* table). This step runs with or without the header.
2. Bare commits are pinned (with -p, with or without the header). A bare commit $X; means with events, Studio Pro’s default; mxcli releases before that change stored it without. In a create or modify flow whose stored commit has no events, the upgrade writes commit $X without events; so that re-running the script keeps what is stored. Without -p the script is left as written and fmt prints a note (MDL067) per flow.
3. Header-gated constructs are rewritten to the spelling that keeps their mdl 0 meaning under the header (not with --header=false): the missing ; is added, / lines are deleted, a backslash escape becomes the character it stood for, retrieve … limit 1 (an object under mdl 0) becomes retrieve … first, a reassignment gets set, and a list operation becomes one statement per activity. One change is version-neutral and is rewritten without the header too (the table says which).
4. The header is added — unless a construct in step 3 has no rewrite, or, with -p, exec would refuse a statement under the header (a create or modify of a stored flow whose change cannot be spliced in, MDL-V1-REBUILD). The file then keeps its version and the rest of the upgrade still applies; --force-header adds the header anyway.

The rewrites and refusals in detail

mxcli fmt --upgrade rewrites every deprecated spelling (the MDL-DEPRnnn warnings) to its canonical form — create or replace becomes create or modify, list entities becomes list entities, on error { … } becomes on error begin … end error — and changes nothing else: comments, layout and keyword case are kept. A deprecated use with no mechanical rewrite is reported and left in place.

mxcli fmt --upgrade script.mdl                  # print the upgraded script
mxcli fmt --upgrade -w script.mdl               # upgrade in place, adding `mdl 1;`
mxcli fmt --upgrade --header=false -w script.mdl  # the spellings alone, no header

The header is added after rewriting every construct whose meaning it would change, so the script keeps doing what it did:

A construct with no mechanical rewrite is reported with the reason, and fmt refuses to add the header rather than change the script’s meaning: an unknown or mis-shaped property (MDL-V1-PROP, MDL-V1-PROPVALUE), create or replace view entity (MDL-V1-REPLACE01), a session command in a script (MDL-V1-SESSION: move it to the command line or the REPL), a nested list operation such as count(filter(…)), find/contains on a variable whose type the script does not state (when the variable holds a microflow or nanoflow call’s result, the called flow’s return type decides: a flow the script creates earlier is read from the script, and any other from the project given with -p app.mpr, so fmt --upgrade -p app.mpr rewrites it), and an escaped line break (\n) inside an expression. An escaped line break in a text template’s literal is rewritten: the break is written into the literal, which under mdl 1 is still the template text. Running fmt --upgrade on its own output changes nothing.

-p app.mpr also settles a bare commit $X; in a create or modify microflow|nanoflow, with or without the header. Since mendixlabs/mxcli#895 a bare commit means with events, Studio Pro’s default; an older mxcli stored the same statement without events. Where the stored flow commits the variable without events, fmt --upgrade -p app.mpr writes commit $X without events;, so re-running the script keeps what is stored instead of turning the event handlers on (or, inside a loop under mdl 1, being refused). A new flow, a new commit, or a stored commit with events is left as written; where the stored flow commits the variable both ways, the statement is left and reported. Without -p, fmt prints a note (MDL067) for each flow with a bare commit.

-p app.mpr also tells the upgrade which statements exec would refuse once the header is there. Under mdl 1 a create or modify microflow|nanoflow of a stored flow is applied as a patch, and a change the patch cannot make (inside a loop body or an error handler, a redrawn connector, a return added) is refused with nothing written; without the header the same statement rebuilds the whole flow (MDL-V1-REBUILD). No rewrite keeps that meaning, so fmt names each such statement and leaves the header off that file, applying the rest of the upgrade. Change those flows with alter, or drop and create them, and upgrade again; --force-header adds the header regardless. mxcli check script.mdl -p app.mpr reports the same statements (an MDL-V1-REBUILD error under mdl 1, the warning without the header), computed by the same code as exec and diff.

Behaviour changes to know about

Besides the generated tables, a few changes alter what an existing script writes. Most apply under both versions, because the old behaviour was a silent wrong write rather than a meaning a script could rely on (ADR-0011 allows fixing those everywhere); the others are gated like any MDL-V1-* change. They are listed because a script that ran before may write something different now. Where the old output can still be asked for, the entry says how.

Reference

The tables below are generated from the registries in the code (visitor.LanguageChanges, executor.LanguageChanges and mdl/deprecation) by make gen-migration-reference; CI fails when they are stale. A version above the newest one this mxcli knows (mdl 2 today) is the version that will refuse the spelling; until then it only warns.

Changes of meaning (MDL-V1-*)

22 constructs mean something different under the mdl 1; header. Without the header each keeps the meaning in the second column and warns with its code.

Deprecated spellings (MDL-DEPR*)

87 old spellings mean exactly what their new form means. They warn with their code under every version before the one in the last column, which refuses them.