DECDMAC / DECINVM — Define & invoke macro (DCS Pn ; Pn ; Pn ! z ... ST / CSI Pn * z)

Byte forms

Every common string-literal form so you can paste-and-search either direction.

Description

DEC VT520 / VT525 macro facility — two paired sequences. **DECDMAC** (Define Macro) is a DCS frame with intermediate `!` (0x21) and final `z` (0x7a) that stores the body `<MACRO-BODY>` under integer handle `Pid` (0–63). Parameters: - `Pid` — macro number (0–63). - `Pdt` (delete-type) — `0` (default) overwrite this macro only; `1` delete **all** macros before storing. - `Penc` (encoding) — `0` (default) body is plain 7-bit / 8-bit terminal bytes; `1` body is hex-encoded (every two hex digits = one byte) — the hex form lets the macro safely contain ESC, ST, `;`, and other parser-sensitive bytes that would otherwise terminate the DCS frame early. **DECINVM** (Invoke Macro) is a CSI sequence with intermediate `*` (0x2a) and final `z` — `\x1b[<Pid>*z` replays whatever was stored under that handle as if those bytes had arrived freshly on the wire (any embedded SGR, cursor moves, OSC, etc. all execute in normal parser state). **Use case** (historical): forms-data-entry terminals — a host application defined a stable set of cursor-position + box-drawing macros at session start, then drove the screen via short DECINVM calls instead of repeating the heavy CSI sequences thousands of times across the page. Saves wire bytes on slow serial links (the original motivation), and lets the terminal cache the cursor-positioning work. **Modern relevance**: essentially nil. Only xterm implements both at meaningful fidelity (with `disallowedColors` / `allowMacro` resources defaulting to **off** for security — a remote process defining macros that later get invoked is a small but real shell-integration / clipboard-injection attack surface). Modern emulators (alacritty / kitty / wezterm / ghostty / Windows Terminal) silently ignore both. Use for: VT520-faithful emulator test suites, forms-terminal preservation work, and exotic demos.

Spec citation: DEC VT520 RM (DECDMAC / DECINVM) / xterm-ctlseqs

Parameters

Examples

# Define macro 1 = 'cursor-home + clear screen', then invoke twice.\nprintf '\033P1;0;0!z\033[H\033[2J\033\\\\'\nprintf '\033[1*z'   # invoke — clears screen\nprintf '\033[1*z'   # invoke again — still clears

import sys\n# Hex-encoded body so the macro can contain ESC safely:\nbody_hex = '1b5b481b5b324a'           # ESC[H ESC[2J\nsys.stdout.write(f'\x1bP2;0;1!z{body_hex}\x1b\\\\')\nsys.stdout.write('\x1b[2*z')   # invoke macro 2

// Define a 'red bold' SGR macro then invoke at every log line:\nfmt.Print("\x1bP3;0;0!z\x1b[1;31m\x1b\\\\")\nfor _, line := range lines { fmt.Print("\x1b[3*z" + line + "\x1b[0m\n") }

// Wipe all macros and store a fresh one in slot 0:\nprocess.stdout.write('\x1bP0;1;0!zHELLO\x1b\\\\')\nprocess.stdout.write('\x1b[0*z')   // prints HELLO

/* Define macro 7 = SGR reset; invoke at end of every styled span. */\nprintf("\x1bP7;0;0!z\x1b[0m\x1b\\\\");\nfor (int i = 0; i < n; ++i) {\n    print_colored(items[i]);\n    printf("\x1b[7*z");\n}

Terminal support

xterm

yes

Linux console (fbcon)

no

macOS Terminal.app

no

iTerm2

no

Windows Terminal

no

cmd.exe / ConPTY

no

kitty

no

alacritty

no

WezTerm

no

Ghostty

no

GNOME Terminal

no

Konsole

no

tmux

no

GNU screen

no

Related sequences

• DECRQSS — Request Selection or Setting (DCS $ q ... ST)
• DECRSPS — Restore Presentation State (DCS $ t ... ST)
• DECSTR — Soft terminal reset
• RIS — Reset to Initial State (full terminal reset)

In the family cookbook

↗DCS cookbook · 5. Stateful save / replay — DECDMAC (define macro) and DECRSPS (restore presentation state)