VX/ACMS – Application Control and Management System

Workspace lifetimes

Workspace handle

Every workspace in VX/ACMS is identified by a handle passed through the CBOR IPC frames:

{
  shm_id:  uint32  // POSIX shm name index
  offset:  uint64  // byte offset within the mapping
  length:  uint32  // record byte length
  version: uint16  // layout_hash low word (checked at first access)
}

CDD integration

Record layouts are authoritative in the CDD database (banking.cdd.db) built by vxcdd --add. Both the ADU compiler and the COBOL/C compilers consume CDD views; no hand-maintained struct duplicates. The layout_hash is a deterministic hash of the flattened CDD field list; a mismatch between the task .so and the server .so causes a hard install-time error.

System workspaces

Task Definition File (TDF)

A TDF defines one or more tasks. Each task declares its workspaces, task arguments, and a BLOCK of steps. A minimal task:

REPLACE TASK FUNDS_TRANSFER
    WORKSPACES ARE
        ACCOUNT_WKSP,
        TRANSFER_WKSP,
        AUDIT_WKSP;

    TASK ARGUMENTS ARE
        ACCOUNT_WKSP WITH ACCESS MODIFY,
        AUDIT_WKSP   WITH ACCESS WRITE;

    BLOCK
        EXCEPTION HANDLER
            MOVE "FAILED" TO AUDIT_WKSP.MSG;
            EXIT TASK;

        PROCESSING CALL READ_ACCOUNT
            USING ACCOUNT_WKSP;

        IF ACCOUNT_WKSP.BALANCE < TRANSFER_WKSP.AMOUNT THEN
            MOVE "NSF" TO AUDIT_WKSP.MSG;
            EXIT TASK;
        END IF;

        PROCESSING CALL DEBIT_ACCOUNT
            USING ACCOUNT_WKSP, TRANSFER_WKSP;
    END BLOCK;
END DEFINITION;

Step types

Group Definition File (GDF)

A GDF defines a server group: which server image (.so) to load, which procedures it exports, and lifecycle hooks:

REPLACE SERVER GROUP BANKING_SERVERS
    PROCEDURE SERVER IMAGE IS "/opt/acms/servers/banking_servers.so";
    INITIALIZATION PROCEDURE IS BANKING_INIT;
    TERMINATION PROCEDURE IS   BANKING_TERM;
    CANCEL PROCEDURE IS         BANKING_CANCEL;
    PROCEDURES ARE
        READ_ACCOUNT,
        DEBIT_ACCOUNT,
        LOG_AUDIT;
END DEFINITION;

Application Definition File (ADF)

An ADF registers tasks and server groups under a named ACMS application. It maps task selectors (used at ACMS$CALL time) to TDF-defined tasks and GDF-defined server groups:

REPLACE APPLICATION BANKING
    TASKS ARE
        FUNDS_TRANSFER     USING TASK GROUP BANKING_TASKS;
    SERVER GROUPS ARE
        BANKING_SERVERS;
END DEFINITION;

TDL keyword reference

Calling ACMS$CALL from C

/* Minimal ACMS$CALL from C: funds transfer */
#include <acms_si.h>

acms_session_t  sess;
acms_status_t   rc;

/* sign in */
rc = ACMS$SIGN_IN("operator", &sess);
if (rc != ACMS_NORMAL) exit(1);

/* populate TASK ARGUMENTS workspaces via shm handle */
memcpy(ws_account.shm_ptr, &account_rec, sizeof(account_rec));
memcpy(ws_transfer.shm_ptr, &transfer_rec, sizeof(transfer_rec));

/* call task */
rc = ACMS$CALL(&sess, "BANKING", "FUNDS_TRANSFER",
               ws_array, 2, 0);
if (rc != ACMS_NORMAL) handle_error(rc);

ACMS$SIGN_OUT(&sess);

Server module ABI (C / C++)

Each server group .so must export an acms_server_module_v1 struct:

typedef struct {
    uint32_t           version;        /* = ACMS_SERVER_MODULE_VERSION (1) */
    const char        *group_name;     /* must match GDF SERVER GROUP name */
    acms_proc_entry_t *procedures;     /* null-terminated array */
    acms_vfn_t         on_init;        /* INITIALIZATION PROCEDURE, may be NULL */
    acms_vfn_t         on_term;        /* TERMINATION PROCEDURE, may be NULL */
    acms_vfn_t         on_cancel;      /* CANCEL PROCEDURE, may be NULL */
} acms_server_module_v1;

Each procedure entry maps a name string to a function pointer:

typedef struct {
    const char    *name;              /* must match GDF PROCEDURES ARE name */
    acms_proc_fn_t fn;               /* unsigned int fn(WKSP *a, WKSP *b, …) */
} acms_proc_entry_t;

/* Procedure signature: one pointer per workspace declared USING */
unsigned int READ_ACCOUNT(ACCOUNT_WKSP_t *acct) {
    /* read account record: field access via struct layout */
    if (acct->balance < 0) return ACMS$_INSUFFICIENT_FUNDS;
    return ACMS_NORMAL;
}

COBOL step procedures

COBOL procedures use the VMS-shape signature: workspace records appear as BY REFERENCE arguments in the PROCEDURE DIVISION USING clause, and the return status is conveyed through RETURN-CODE (not a function return value):

IDENTIFICATION DIVISION.
PROGRAM-ID. READ-ACCOUNT.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
    01 ACCOUNT-WKSP.
       05 ACCOUNT-ID   PIC X(16).
       05 BALANCE       PIC S9(12)V99 COMP-3.
       05 STATUS-MSG    PIC X(40).
PROCEDURE DIVISION USING ACCOUNT-WKSP.
    EXEC SQL
        SELECT BALANCE INTO :ACCOUNT-WKSP.BALANCE
        FROM ACCOUNTS WHERE ID = :ACCOUNT-WKSP.ACCOUNT-ID
    END-EXEC.
    IF SQLCODE <> 0
        MOVE "NOT FOUND" TO ACCOUNT-WKSP.STATUS-MSG
        MOVE ACMS-STEP-ERROR TO RETURN-CODE
    ELSE
        MOVE ACMS-NORMAL TO RETURN-CODE
    END-IF.
    STOP RUN.

Exception handling from server code

Call ACMS$RAISE_STEP_EXCEPTION to propagate a step-level error back to the EXC EXCEPTION HANDLER without using a C++ exception or a non-zero return value directly:

unsigned int DEBIT_ACCOUNT(ACCOUNT_WKSP_t *acct,
                            TRANSFER_WKSP_t *xfr)
{
    if (xfr->amount > acct->balance) {
        ACMS$RAISE_STEP_EXCEPTION(ACMS$_INSUFFICIENT_FUNDS,
                                  "Balance too low");
        return ACMS_NORMAL; /* control never reaches here */
    }
    acct->balance -= xfr->amount;
    return ACMS_NORMAL;
}

Pipeline steps

adu_compile flags

Full build example

# 1: compile the CDD record repository
vxcdd --add banking.cdo

# 2: compile the server group
adu_compile banking_servers.gdf \
    --cdd banking.cdd.db \
    --compile \
    --output-dir build/

# 3: compile all task definitions
adu_compile funds_transfer.tdf enquiry.tdf audit_report.tdf \
    --gdf banking_servers.gdf \
    --cdd banking.cdd.db \
    --compile \
    --output-dir build/

# 4: install the application
acmsctl install application BANKING \
    --adf banking.adf \
    --task-dir build/ \
    --server-dir build/

Incremental rebuild

Re-run only the steps for the files you changed. If you modify a CDD record, you must recompile both the task .so and the server .so that reference that workspace; the layout_hash check at install time will catch any mismatch. Use acmsctl reload application BANKING to hot-reload an updated application without restarting acmsd.

TDF step summary

ACMS$ service quick reference

acmsctl operator commands

Key file paths (default layout)