VX/ACMS – OpenVMS ACMS(TDF,MDF,GDF,ADF) to C++

From definitions to a running executable

At its simplest, VX/ACMS bundles the TDF, MDF, and procedures (built as dynamic libraries) into a single executable unit. This mirrors how ACMS applications behave on VMS, but instead of requiring a separate transaction monitor, VX/ACMS integrates these components directly into the C++ runtime.

The same codebase serves two integration levels. The simplest embedded deployment binds the components into one executable with no transaction monitor. The full deployment is a live, multi-process ACMS runtime built from the same translated modules, so a project can start embedded and grow into the process model without re-translating.

How the four relate

The MDF names the tasks a submitter can select; the ADF binds task groups and server pools; the GDF rosters servers, procedures, workspaces, and tasks; each TDF is one task's step program. Workspace record layouts come from CDD, which keeps a workspace's C struct and its COBOL copybook byte-identical.

A Task Definition File (TDF)

A TDF declares its workspaces and task arguments, then a labelled sequence of steps. This banking demo task reads a customer record through an exchange step, dispatches to a server procedure, and uses a CONTROL FIELD action part to branch on the operator's key:

REPLACE TASK banking_task:funds_transfer_task

DEFAULT FORM IS banking_form;

USE WORKSPACES account_wksp,
               transfer_wksp,
               sendctrl_wksp,
               audit_wksp;

TASK ARGUMENTS ARE account_wksp  WITH ACCESS MODIFY,
                   transfer_wksp WITH ACCESS READ,
                   audit_wksp    WITH ACCESS WRITE;

BLOCK WITH FORM I/O

get_request:
    EXCHANGE
        TRANSCEIVE RECORD   account_wksp, transfer_wksp
        SENDING             account_wksp
        RECEIVING           account_wksp, transfer_wksp
        WITH SEND CONTROL   sendctrl_wksp;
    ACTION IS
        CONTROL FIELD sendctrl_wksp.ctrl_key
        "QUIT"  : EXIT TASK;
        "CANCL" : EXIT TASK;
        NOMATCH : MOVE "     " TO sendctrl_wksp.ctrl_key;
        END CONTROL;

post_debit:
    PROCESSING
        CALL PROCEDURE debit_account_proc
        IN    banking_write_server
        USING account_wksp, transfer_wksp, audit_wksp;
    ACTION IS
        IF (ACMS$T_STATUS_TYPE = "B") THEN
            GET MESSAGE INTO audit_wksp.messagepanel;
            GOTO PREVIOUS EXCHANGE;
        END IF;

END DEFINITION;

A Group Definition File (GDF)

The GDF binds servers, procedures, workspaces, and tasks. Both the plural PROCEDURES ARE and singular PROCEDURE IS server clauses are accepted. The adu --gdf pass emits one server module per SERVER, with a procedure table indexed by procedure id:

SERVERS ARE
    banking_read_server:
      PROCEDURE SERVER IMAGE IS "banking_default:banking_read_server.exe";
      INITIALIZATION PROCEDURE IS banking_read_init;
      RUNDOWN ON CANCEL IF INTERRUPTED;
      PROCEDURES ARE find_customer_proc, read_account_proc,
                     account_details_proc;
    banking_write_server:
      PROCEDURE SERVER IMAGE IS "banking_default:banking_write_server.exe";
      INITIALIZATION PROCEDURE IS banking_write_init;
      PROCEDURE IS debit_account_proc;
END SERVER;

TASKS ARE
      funds_transfer_task : TASK IS banking_task:funds_transfer_task;
      enquiry_task        : TASK IS banking_task:enquiry_task;
END TASKS;

Supported TDF control structures

Full step and statement set

Procedure servers and dynamic linking

Procedure servers follow the same rules as ACMS, using dynamic linking. VX/ACMS maps ACMS dynamic calls onto the Linux equivalents dlopen and dlsym, so compiled ACMS procedures behave like their VMS counterparts. This also lets ACMS tasks call VX/DCL when the TDF permits it. A server image is a .so that exports one registry symbol, which the server-process host loads and validates by ABI version before dispatch:

typedef struct acms_server_module_v1 {
    uint32_t            abi_version;    /* == ACMS_MODULE_ABI_VERSION (1) */
    const char         *server_name;    /* matches SERVER name in the GDF */
    const char         *runtime;        /* "c" | "cxx" | "netcobol" | "gnucobol" */
    uint32_t            n_procedures;
    const acms_proc_t  *procedures;     /* static, indexed by proc_id (0..N-1) */
    acms_status_t     (*init)  (acms_runtime *rt);
    acms_status_t     (*term)  (acms_runtime *rt);
    acms_status_t     (*cancel)(acms_runtime *rt, uint32_t task_id);
    uint64_t            layout_hash;    /* over all workspace layouts */
} acms_server_module_v1;

Dispatch is by index (procedure id), not by name: the controller learns the name-to-id mapping from the server's startup frame, then issues indexed calls. Each procedure entry is { name, entry, n_workspaces }, and the entry signature passes workspace handles by reference so a procedure reads and writes the shared workspace directly.

Procedure-callable services

A step procedure may call only the three exception raisers. Because $ is not a portable C identifier character, the link symbols use underscores, and the VX tools reconcile the real ACMS$RAISE_* callers:

ACMS$ service surface

The agent-facing service library exposes the OpenVMS ACMS$ callable API. Condition values follow the VMS convention, where bit 0 set means success.

Transaction handling

VX/ACMS does not execute commit and rollback itself. That responsibility is assumed to belong to Oracle or another modern transaction manager. The original ACMS commit and rollback structure is kept intact in the translated code, but the database layer is now what actually executes it.

Menus and user interfaces

MDF (Menu Definition Files) generate a C-style menu structure that closely mimics MENU and TASK definitions. The menus can be displayed in VX/DECFORMS or processed into standard console-based menu systems, so legacy ACMS menus behave the same way inside the Linux and Windows runtime.

RMS recovery

VX/ACMS supports the RMS Recovery syntax, so a task that uses it still translates and runs. Recovery logic itself is not yet implemented in VX/RMS; RMS support is planned to extend based on client needs. Tasks that rely on RMS recovery therefore translate cleanly today, with the recovery behaviour arriving in a later VX/RMS update.

Command-line flags

Build steps

The ADU command-line interface is intentionally minimal today. VX/ACMS is designed to move ACMS applications forward into C++, rather than to perpetuate the traditional ACMS command surface, so the focus is on translation quality rather than reproducing every legacy operator command.

Divergences from OpenVMS ACMS, and why

Definition file types

Each opens with REPLACE <KIND> <path>:<name> and closes with END DEFINITION;.

adu command line

adu [--cdd db] [--tdf|--gdf|--mdf|--adf|--msg] [--compile]
    [--parse-only] [--strict] [--pedantic] [--skip-report] <src> <out>
adu --decompile <src>
adu --manifest project.man
adu --standin

Compile to a shared object

adu --compile ... out.cpp
    runs: c++ -std=c++20 -shared -fPIC ... out.cpp -o out.so

Supported TDF control structures

Procedure-callable services

Session API

Success test

Condition values follow the VMS convention: bit 0 set means success. ACMS$_NORMAL is the canonical success code.

Runtime dependencies