FMS$ – Forms Management System

Architecture and dispatch

VX/FMS$ is a linked library, not a daemon. An application links against libfms.a (or libfmsx.a in standalone mode) and calls the FDV$ Forms Driver routines directly. The whole product is a single portable source tree: the same files build for OpenVMS and for Linux, guarded by __VMS conditionals, so behaviour on Linux tracks the VMS original rather than forking from it. Three pieces make up the product: the FDV$ Forms Driver runtime, the FMS form language and binary form format, and a terminal driver that paints forms with escape sequences.

/* public thunk: normalises the VMS ABI */
U32 FDV_D_ADLVA(S32 *video)
{
  begin_FDV();
#ifdef __VMS
  int prmcnt; va_count(prmcnt);
  if( prmcnt < 1 ) video = NULL;   /* default an omitted arg */
#endif
  call_FDV( FCC_ADLVA( video ) );
  end_FDV();
}
__AliasF(FDV_D_ADLVA, FDV$ADLVA, fdv$adlva);   /* export the VMS-visible name */

/* implementation: the real work + status ladder */
U32 FCC_ADLVA(S32 *video)
{
  enter_FDV
  if( ! video )        return_FDV( FDV__ARG )   /* bad/omitted arg */
  if( ! FMS_curr_tca ) return_FDV( FDV__TCA )   /* no terminal control area */
  if( FMS_t_cancel(FMS_curr_tca) ) return_FDV( FDV__CAN )
  /* ... do the work ... */
  return_FDV( FDV__SUC )                        /* 2719889 = success */
}

FDV$ callable routines

VX/FMS$ exports the full OpenVMS FDV$ Forms Driver set: 66 callable routines, each backed by a real implementation body. On the VMS ABI every argument is passed by reference and trailing arguments are optional, defaulted to NULL by the public thunk. The routines are grouped below by function; every routine listed is live.

Status and terminator codes

FDV$ routines return VMS-style condition codes: an odd value is success, an even value is failure, and callers test the low bit. There are 73 FDV__* codes in total, numbered contiguously from 2719889 (FDV__SUC, normal completion). The table lists the load-bearing codes an application is most likely to test or log.

A further block of field-attribute codes (for example FDV__ALPHA, FDV__NUMERC, FDV__MUSTFILL, FDV__NOHELP) describes field validation classes and is what a User Action Routine inspects.

The FMS form language and binary forms

A form is authored as a text .flg file, compiled to a binary .fbn form, and grouped with other forms into a form library. At run time FDV$LOPEN opens the library on a channel and FDV$LOAD locates a form by appending .fbn to its name. The form language and binary format match the OpenVMS originals, so existing form sources compile unchanged.

FORM NAME='ACCOUNT_INQUIRY'
    AREA_TO_CLEAR=1:23
    WIDTH=80
    BACKGROUND=CURRENT
    HIGHLIGHT=BOLD:UNDERLINE
    FUNCTION_KEY_ACTION_ROUTINE='FILTER_UAR'
    ;
TEXT (5,10) 'Account Number :'
    ;
FIELD ACCT_NO (5,27)
    PICTURE='NNNNNNNNNN'
    RESPONSE_REQUIRED
    UPPERCASE
    ;

Terminal rendering

Forms are painted by emitting escape sequences directly, not through curses. A dedicated terminal layer handles cursor addressing, line erasing, video attributes, and output flushing. Video attributes map to standard CSI sequences:

/* video attribute sequences */
BST_SEQ_VID_BEG   "\033["   /* CSI */
BST_SEQ_BOLD      "1"
BST_SEQ_UNDERLINE "4"
BST_SEQ_REVERSE   "7"
BST_SEQ_VID_END   "m"

Terminal type is auto-detected from the $TERM environment variable at startup. An X-window terminal resolves to XTERM; otherwise a prefix match selects ANSI, HFT, or VT, and anything unmatched falls back to VT. This is the main Linux divergence point: the OpenVMS original drove real VT-series hardware through the VMS terminal driver, while VX/FMS$ renders the same forms to a Linux pseudo-terminal using ANSI and VT escape sequences.

End-to-end call path

A migrated program links against libfms.a and calls the FDV$ routines exactly as it did on OpenVMS. The success test is the same: the low bit of the returned status is set on success (status & 1). The example below loads and displays a form, then reads fields from a scrolled area, checking status after each call.

/* fail fast: report the FMS message and exit on any error */
#define CHECK if( !(fmsstat & 1) ) { \
  fprintf(stderr, "FMS error %d [%s] at line %d\r\n", \
          fmsstat, FMS_disp_deb_mess_1(fmsstat), __LINE__); exit(0); }

/* simple form: select workspace, load, display, wait */
fmsstat = fdv$swksp( &acct_wksp );                        CHECK
fmsstat = fdv$load ( _DESCR("ACCOUNT_INQUIRY") );          CHECK
fmsstat = fdv$dispw( 0 );                                 CHECK
fmsstat = fdv$wait ( 0 );                                 CHECK

/* scrolled area: read fields until the terminator says stop */
fmsstat = fdv$swksp( &txn_wksp );                         CHECK
fmsstat = fdv$load ( _DESCR("TXN_HISTORY") );              CHECK
fmsstat = fdv$dispw( 0 );                                 CHECK
fmsstat = fdv$getsc( _DESCR("TXN_LINE"), &val, &trm );    CHECK

while( 1 ) {
  switch( trm ) {                    /* trm is an FDV_K_FT_* code */
    case FDV_K_FT_NXT: case FDV_K_FT_ATB:
    case FDV_K_FT_SFW: case FDV_K_FT_SNX:
      fmsstat = fdv$pft( &trm, _DESCR("TXN_LINE"),
                         _DESCR(line_buf), 0, 0 );        CHECK
      break;
    /* ... handle other terminators ... */
  }
}

Note the trailing 0, 0 passed to fdv$pft: on Linux the optional arguments a VMS caller could omit are passed explicitly as NULL, because the argument-count probe used on VMS is not available.

The complete ordered sequence, including terminal and workspace selection, library and form loading, interaction, and teardown, is shown in Architecture and dispatch: Call lifecycle.

FDV$STAT can report the last condition value at any point in this sequence.

Compatibility and divergences

The table summarises what is implemented. The core forms driver, the form language, the binary form format, terminal rendering, scrolled areas, and User Action Routines are all present and exercised.

Quick reference