VX/FMS – OpenVMS Forms Management

Call dispatch chain

Each public API name is a thin dispatcher. A call to FDV$DISP resolves through a link-time alias to an internal dispatcher, which wraps the call in the VX runtime trace/return convention and hands off to the routine implementation:

On an OpenVMS host, the dispatcher reads the caller's argument count and nulls out omitted optional parameters, preserving FMS's "optional trailing argument" semantics. On Linux the fixed prototype is used. The real work lives in the per-routine implementation files, which are complete implementations rather than stubs.

VMS calling convention

Every routine returns a VMS condition value by value: odd means success, even means failure. Arguments are passed by reference as VMS descriptors (32-bit, or 64-bit descriptors under an LP64 build), matching the original VMS calling convention. This is what lets unmodified VMS source relink against VX/FMS. The canonical success status is FDV$_SUC; callers test the low bit of the return value exactly as they did on OpenVMS.

Routine reference

The table below groups the most frequently called routines by role. It is a representative selection of the 66-routine FDV$ API; every routine listed is implemented in the runtime.

Real call path

A migrated program links this session sequence unchanged against libfms. The example uses a banking demo library and tests each status with the VMS success convention:

/* 1. Attach the terminal (open the Form Driver session) */
rc = fdv$aterm(&_tca, &val0, &val1, 0, 0, 0);
if (rc != FDV$_SUC) { /* report status text and exit */ }

/* 2. Allocate and select a workspace */
val0 = 2000;
rc = fdv$awksp(&_wksp1, &val0);
rc = fdv$swksp(&_wksp1);

/* 3. Open the compiled form library and load a form */
rc = fdv$lopen(_DESCR1("BANKING_FORMS"), &val0);
rc = fdv$load (_DESCR1("ACCOUNT_INQUIRY"));

/* 4. Display the form and read all fields (trm receives the terminator) */
rc = fdv$dispw(0);
rc = fdv$getal(&_val, &trm, 0, 0);

/* 5. Tear down */
fdv$dwksp(&_wksp1);
fdv$dterm(&_tca);

The equivalent portable C entry point is declared as extern "C" int fdv$get(...); and returns the condition value by value. The same routines are the ones the callable FMS$ Forms Management System API page documents in full detail.

Statement keywords

The form language has ten top-level statement types:

Statement items and attribute flags

Statement items take a =value; attribute flags are bare keywords, most with a NO... negation. The compiler recognises the full FMS keyword set:

Date fields support MDY, DDMMMYY, MMDDYY, and DDMMYY pictures; time fields support HHMMSS and HHMMAMPM. PICTURE accepts either a literal mask (PICTURE='XXXXX-XXXX') or a count-prefixed form (PICTURE=40'X').

Example form source

A field with attribute defaults, a bound User Action Routine, a navigation order, and a help string. Comments begin with !; a statement ends with ;:

FORM NAME='ACCOUNT_INQUIRY'
    AREA_TO_CLEAR=1:23
    WIDTH=80
    BACKGROUND=CURRENT
    HIGHLIGHT=BOLD:UNDERLINE
    FUNCTION_KEY_ACTION_ROUTINE='FILTER_UAR'
    ;

TEXT (2,30) 'ACCOUNT INQUIRY' ;

ATTRIBUTE_DEFAULTS FIELD
    CLEAR_CHARACTER=' '
    NOAUTOTAB BLANK_FILL NOBOLD NOREVERSE ECHO
    LEFT_JUSTIFIED NOSUPERVISOR_ONLY NOUPPERCASE
    ;

FIELD NAME='POST_IT'  (22,64)
    PICTURE='X'
    HELP='Enter "Y" to post this transaction, "N" to abort'
    UPPERCASE
    ACTION_ROUTINE='POST_IT_UAR'
    RESPONSE_REQUIRED
    ;

ORDER BEGIN_WITH = 1
    NAME='ACCOUNT_NUMBER'
    NAME='POST_IT'
;

END_OF_FORM NAME='ACCOUNT_INQUIRY' ;

Scrolled regions are declared by line range, and a help form is linked with HELP_FORM='HELPTOPIC'. The RULE character set selects the VT line-drawing glyphs used for box borders:

SCROLL BEGIN_WITH=9  END_WITH=13 ;
SCROLL BEGIN_WITH=18 END_WITH=20 ;

Binding and dispatch

A form binds a UAR by string name, for example ACTION_ROUTINE='POST_IT_UAR' or FUNCTION_KEY_ACTION_ROUTINE='FILTER_UAR'. At run time the Form Driver dispatches by name through a generated lookup table that pairs each UAR name with its function pointer:

/* generated binding table, linked into the application */
extern char *FMS_name_field[];        /* UAR names */
extern int (*FMS_ptr_field[])(void);  /* parallel function pointers */

int FMS_find_call_uar(char *name) {
    /* locate name in FMS_name_field[], then call the paired pointer */
    for (i = 0; strcmp(name, FMS_name_field[i]) && ... ; i++) ;
    return (*FMS_ptr_field[i])();     /* invoke the UAR */
}

The name-to-pointer table is produced by the fms_uar generator, which scans the application's UAR source and emits the binding table to link in. On OpenVMS the image activator resolved UARs by name at run time; on Linux there is no image activator, so the generator materialises the equivalent table at link time. This is also how VX/FMS extends the original FMS capability by allowing dynamic linking of external C++ functions as UARs, giving migrated forms more flexibility than the OpenVMS original.

Supported terminals

• VT100, VT220, and all compatible VT-series terminals.
• DECterm under DECwindows.
• ANSI-compatible terminal emulators on Linux.

Display features preserved

Because the runtime owns terminal I/O end to end, the diagnostic tools can capture and replay the exact escape stream: fms_dump writes a form render to an escape-sequence file, and fms_compare parses those escapes back to compare a Linux render against a captured reference render for regression testing.

Platforms

The VX/FMS runtime is native on Linux, and the same sources build for other Unix platforms (macOS, HP-UX, and SCO) through build-time configuration. The library links directly into the migrated application, so the target platform is whatever the recompiled application targets.

Session skeleton

The canonical Form Driver session lifecycle:

At a glance

Status codes

Form Driver routines return VMS-format 32-bit condition values, where odd values indicate success. Field-level input conditions (for example full field, no previous field, numeric required, or help available) are reported through the same status interface, and a workspace-item form of the status is available through FDV$STAT for programs that inspect completion detail.

Related Sector7 tools

• FMS$ – Forms Management System: the callable FDV$ API companion, documented routine by routine.
• VX/RT APIs: the OpenVMS runtime environment VX/FMS integrates with on Linux.
• VX/RMS: RMS file access for the same migrated applications.
• VX/TDMS and VX/DECFORMS: sibling forms and screen-management tools in the same family.