VX/MSG – OpenVMS Message Compiler

Data flow

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

The run-time flow happens inside the migrated application:

Control words

Symbols, message text, and qualifiers

A symbol name at the start of a line names the message. Message text follows in one of two delimiter styles: double quotes ("...text...") or angle brackets (<...text...>), with angle brackets supporting nesting. A trailing - continues a definition onto the next line, so a symbol, its qualifiers, and its text can span several lines. Per-message qualifiers refine a single message:

Example

A user facility for a funds-transfer service, with FAO directives left in the text for the runtime to substitute through SYS$FAO:

.facility BANKING, 2048 /PREFIX=BANK$_
.base 0
.severity ERROR

INSUFFUNDS   <insufficient funds in account !UL> /FAO_COUNT=1
ACCTLOCKED   <account !AS is locked> /FAO_COUNT=1
XFERDONE     <transfer of !UL cents completed> /FAO_COUNT=1 /SUCCESS

Here !UL (unsigned longword) and !AS (counted ASCII string) are VMS FAO directives. VX/MSG stores the message text verbatim and records the argument count from /FAO_COUNT, leaving the substitution itself to SYS$FAO and SYS$GETMSG at run time.

The message record

Each message is written to the database as a fixed-size record holding the code, the facility number, argument metadata, and the facility, symbol, and message-text strings:

typedef struct {
    U32    msgnum;            /* code with severity masked off */
    U32    facnum;
    unsigned char optinfo[4]; /* [0]=severity [1]=FAO count [2]=user [3]=reserved */
    char   facnam[32];
    char   msgnam[64];
    char   message[256];
} MESSAGE_RECORD;

Generated constant shapes

The source-generation modes emit one constant per message symbol:

Worked example

# compile the message source into the indexed database
msg -q banking.msg
#   populates SYS$MESSAGE:MESSAGES.SYS (.dat + .idx)

# generate a C header of message constants for the application build
msg -h < banking.msg > bank_messages.h

# generate FORTRAN constants
msg -f < banking.msg > bank_messages.for

Lookup path

SYS$GETMSG prefers the memory-mapped messages.shr image when it is present and falls back to the indexed database otherwise. If neither is available it returns default placeholder text, and an unknown code returns the standard SS$_MSGNOTFND status, so callers see well-defined behaviour rather than a crash. The argument metadata returned to the caller matches what the compiler wrote: the FAO argument count and the user value travel with the message text.

Viewing the database

Because the store mirrors the OpenVMS SYS$MESSAGE layout, compiled messages can be inspected from VX/DCL just as on OpenVMS, which is useful for verifying a message-source compile during a migration:

$ TYPE/PAGE SYS$MESSAGE:MESSAGES.SYS

Message constants for application code

Applications that referenced message symbols by name on OpenVMS continue to do so on Linux. VX/MSG generates constant sources for C, C headers, and FORTRAN, so C and C++ callers include the generated header and FORTRAN callers include the generated PARAMETER definitions. Each constant carries the same message code the runtime resolves, keeping the compile-time symbol and the run-time lookup in step.

Control words

Qualifiers

Severity values

Compiler flags

Runtime services

Common commands

# compile to the indexed message database
msg -q messages.msg

# generate constants
msg -c < messages.msg > constants.c
msg -h < messages.msg > constants.h
msg -f < messages.msg > constants.for

# view compiled messages via VX/DCL
$ TYPE/PAGE SYS$MESSAGE:MESSAGES.SYS