VX/TDMS – Terminal Data Management System

Call lifecycle / data flow

The compile-time flow runs offline, once per estate:

The run-time flow happens per interactive session, inside the migrated program:

The record buffers passed to TSS$REQUEST are opaque to the caller and shared with the runtime by reference; the runtime reads and writes fields at the byte offsets recorded in that request's record p-code. This is the crux of source-level compatibility: the program's RECORD variable is the same bytes the runtime edits.

The RDF request language

A request binds one or more program records to a form and moves data between them. The example below is a representative request showing the constructs VX/TDMS handles end to end: record binding with an alias, a program key, top-level and nested CONTROL FIELD cases, subscripted array mappings, and %LINE loop variables.

FORM IS ACCOUNT_INQUIRY_FORM;

RECORDS ARE ACCOUNT_REC WITH NAME ACCTREC,
            CDD$TOP.BANKING.DATA.SYST_STNDFORM_REC WITH NAME STNDFORM;

DESCRIPTION
/* Displays outstanding statements for an account. Control field is FLAG. */;

RESET FIELD %ALL;
USE FORM ACCOUNT_INQUIRY_FORM;

PROGRAM KEY IS GOLD "E"
     NO CHECK;
     RETURN "ABORT   " TO STNDFORM.RECORD_LOCK;
END PROGRAM KEY;

OUTPUT
     ACCTREC.ACCOUNT_ID                 TO ACCOUNT_ID,
     ACCTREC.STATEMENT_NUMBER[1 TO 30]  TO STATEMENT_NUMBER[1 TO 30],
     ACCTREC.SELECT_STATEMENT[1 TO 30]  TO SELECT_STATEMENT[1 TO 30];

CONTROL FIELD IS FLAG

     'START  ':
          OUTPUT STNDFORM.PGM_NAME TO PGM_NAME,
                 ""                 TO STATEMENT_DATE[1 TO 30];
          INPUT  ACCOUNT_ID          TO ACCTREC.ACCOUNT_ID;

     'ACCT   ':
          REVERSE FIELD ACCOUNT_ID;
          INPUT ACCOUNT_ID TO ACCTREC.ACCOUNT_ID;

     'DISPLAY':
          CONTROL FIELD IS DATE_FLAG[%LINE = 1 TO 30]
               "X":
                    OUTPUT ACCTREC.STATEMENT_DATE[%LINE]  TO STATEMENT_DATE[%LINE];
                    INPUT  SELECT_STATEMENT[%LINE]         TO ACCTREC.SELECT_STATEMENT[%LINE];
          END CONTROL FIELD;

END CONTROL FIELD;

END DEFINITION;

An empty string literal ("") as an OUTPUT source clears the receiving field. A CONTROL FIELD nests arbitrarily and its cases are matched against the named field's value. %LINE and %ENTRY are loop variables over subscript ranges, and field references may be dotted CDD record paths.

RDF instruction set

Subscripts are multi-dimensional with loop variables: [1 TO 30], [%LINE], [%LINE = 1 TO 100, %ENTRY = 1 TO 25].

FDU form field attributes

All represented in form p-code:

• Display Only: field not mapped for input.
• No Echo: data entered is not displayed.
• Autotab: cursor advances automatically when the field fills.
• Default value: shown at run time unless a request overrides it.
• Field help: message shown on the HELP key.
• Clear character: the fill character in empty positions.
• Clear / zero suppression: suppress a leading zero for a null numeric field.
• Validation: RANGE, CHOICE, SIZE, CHECK DIGIT.
• Video attributes: BOLD, REVERSE, BLINK, UNDERLINE.
• Access order: left-to-right, top-to-bottom field visitation.

Reserved keys: HELP (PF2/F15), MENU (GOLD-KP7), RETURN/ENTER saves field values, GOLD is the prefix for program keys.

VMS ABI

Return convention: the function result is a VMS condition value returned by value: odd means success, even means failure. Callers test ODD(...). Canonical signatures:

ret = TSS$OPEN      (channel.wlu.r [, device.rt.dx])
ret = TSS$CLOSE     (channel.rlu.r [, clear-screen.rlu.r])
ret = TSS$OPEN_RLB  (rlb-file-spec.rt.dx, library-id.wlu.r)
ret = TSS$CLOSE_RLB (library-id.rlu.r)
ret = TSS$REQUEST   (channel.rlu.r, library-id.rlu.r, request-name.rt.dx
                     [, record1.mz.r [, ... recordN.mz.r]])
ret = TSS$READ_MSG_LINE (channel.rlu.r, response-text.wt.dx
                     [, message-prompt.rt.dx] [, response-length.wwu.r])
ret = TSS$WRITE_MSG_LINE(channel.rlu.r, message-text.rt.dx)
ret = TSS$SIGNAL                                  ; signal last condition, no args
ret = TSS$COPY_SCREEN (channel.rlu.r [, file-spec.rt.dx] [, append-flag.rlu.r])
ret = TSS$DECL_AFK  (channel.rlu.r, key-id.rlu.r, key-efn.rlu.r,
                     key-astadr.szem.r [, key-astprm.rlu.v])

Routine table

TSS$HARDCOPY is honoured as the default TSS$COPY_SCREEN destination when set as a logical name / environment variable. TSS_TRIGGER_AFK (and interactive AFK:<key-id> input) fires a declared async function-key callback with the channel, key-id, and the caller's AST parameter.

Request-execution semantics

TSS$REQUEST does the real work. On every call it:

• Loads the request / form / record p-code for the named request.
• Decodes raw record buffers at compiled offsets: TEXT, signed/unsigned integer, DATE, F_FLOATING, G_FLOATING, UNSIGNED QUADWORD, and BIT all decode to display text and encode back to native storage bytes on input.
• Applies RDF OUTPUT mappings: record/literal to form, including control-field cases and indexed repeated fields.
• Renders the form: live terminal output uses ANSI cursor addressing and SGR video attributes; copy-screen output stays plain text for deterministic hardcopy comparison.
• Applies RDF INPUT mappings, validates the value (required, uppercase, numeric, choice, range, size, check digit, length), and writes it back into the raw application record buffer.
• Runs request actions: field reset, video attributes, RING BELL, SIGNAL OPERATOR, WAIT, NO WAIT.

Real call path (VAX Pascal)

A migrated program links this unchanged against libvtdms_forms; note the ODD() status test and %REF (by-reference) record passing:

{ open channel + request library }
IF NOT ODD (TSS$OPEN(TDMS_CHANNEL))                       THEN TDMS_STATUS := TSS$SIGNAL;
IF NOT ODD (TSS$OPEN_RLB('BANKING_RLB:ACCT_INQUIRY_LIB',
                          TDMS_LIB_ID))                   THEN TDMS_STATUS := TSS$SIGNAL;

{ run a request against two program records, passed by reference }
IF NOT ODD (TSS$REQUEST(TDMS_CHANNEL,
                        TDMS_LIB_ID,
                        'ACCOUNT_INQUIRY_REQ',
                        (STNDFORM),      { %REF record 1 }
                        (ACCTREC)))      { %REF record 2 }
THEN TDMS_STATUS := TSS$SIGNAL;

{ … application reads/writes fields of ACCTREC, which the runtime just filled … }

{ tear down }
IF NOT ODD (TSS$CLOSE(TDMS_CHANNEL, CLEAR_SCREEN))        THEN TDMS_STATUS := TSS$SIGNAL;
IF NOT ODD (TSS$CLOSE_RLB(TDMS_LIB_ID))                   THEN TDMS_STATUS := TSS$SIGNAL;

The equivalent portable C entry point is declared as extern "C" int TSS_REQUEST(int channel, int library_id, const char* request_name, ...);, returning the condition value by value.

Integrity properties enforced by the compiler

• Per-element offsets, not contiguous-array assumptions, so nested STRUCTURE OCCURS and CDD variant overlays are represented faithfully. Fields from different variant branches may legally share the same offset.
• Fixed record byte size is compiled and used to size the raw buffer the runtime decodes and writes.
• Semantic validation resolves every mapping operand against compiled form fields and record paths, accepting dotted paths and unique nested-suffix references, and reports form/record reference errors, missing fields, static subrange violations, occurrence-count mismatches, and type-category mismatches, each with source path, RDF line, and severity.

Pipeline steps

Worked example

# 1: compile the whole estate
tdmsc compile-all /opt/tdms/banking/cdd -o /tmp/tdms_pcode
#    → compiled=500 fields=8740 ops=22087 warnings=3 unsupported=0 errors=0

# 2: validate every mapping against compiled forms + records
tdmsc validate-semantics /tmp/tdms_pcode
#    → semantic_requests=109 semantic_mappings=5030 semantic_warnings=2 semantic_errors=0

# 3: generate C + Pascal byte-layout bindings for the record p-code
tdmsc gen-bindings /tmp/tdms_pcode -o /tmp/tdms_bindings --language all

On a representative production-scale estate this breaks down as 105 forms, 109 requests, 64 libraries, and 222 records: 500 files, 8,740 fields, 22,087 rendering ops, and 5,030 request mappings, all validated with zero semantic errors.

CLI reference

Incremental rebuilds

compile recompiles a single artifact to a single p-code file. There is no daemon to reload. The runtime reads p-code fresh at TSS$OPEN_RLB time, so a recompiled p-code file takes effect on the next run. The browser form editor writes a timestamped backup beside the file before replacing it.

What DEC's own converter drops, and what VX/TDMS preserves

Path 2 targets the native DECforms product and inherits DEC's own Converter limitations, documented in the DECforms TDMS Conversion Guide. That guide states plainly that the Converter converts forms and requests but does not convert the program, and, even for forms and requests, does not convert eight specific things. VX/TDMS was built to preserve every one of them, because it compiles from source rather than from a built .RLB file.

Path 3: the compatibility superset

Rather than force every TDMS concept into standard DECforms, VX/DECFORMS is extended to understand TDMS request syntax and runtime behaviour directly, and the same migration rewrites TSS$ calls to FORMS$. Because the compiler lowers TDMS syntax natively, most of the limitations above simply don't arise on this path: nested CONTROL FIELD IS, dependent ranges, program keys, explicit and subrange mappings, video attributes, and operator signals are all recognized constructs. Where a behaviour still needs project-specific policy, the compiler emits a compatibility diagnostic rather than silently changing meaning.

Deliberate divergences (Path 1 runtime behaviour)

Form editor

The browser-based form editor moves through a form → layout → assign → order phase model. It loads and saves the same JSON p-code the runtime consumes, validates on save, and writes a timestamped backup before replacing the file. It lists valid form p-code files in the current directory and counts and reports files that fail validation rather than hiding them. It binds to a configurable local address and port, with a no-browser flag for headless use.

tdmsc subcommands

RDF verbs

TSS$ routines

Return convention: odd = success, even = failure; test ODD(...).

P-code formats

CDD datatypes decoded / written by the runtime

Validators

Key file paths