VX/FDL – File Description Language Routines

Call lifecycle

The three operations share one internal flow: parse an FDL description into control blocks, act on those blocks (create a file, or the reverse: read a file and emit its description), then release any blocks that were allocated.

Primary sections

The 13 primary sections VX/FDL recognises:

FILE and RECORD attribute keywords

The secondary keywords accepted under FILE, RECORD, and related sections cover organization, record format, allocation, and file-handling options:

KEY section keywords

The KEY section carries 33 keywords, including the eight segment position and length pairs (SEG0_POSITION and SEG0_LENGTH through SEG7_*) plus area, fill, compression, and prologue attributes:

KEY data types

The 16 key data types accepted by the TYPE keyword:

Example: an indexed file

A minimal indexed FDL that VX/FDL round-trips through CREATE/FDL, using the banking demo domain:

TITLE   "Customer master, indexed by account number"

SYSTEM
        SOURCE                  "VAX/VMS"

FILE
        NAME                    "CUSTOMER.DAT"
        ORGANIZATION            indexed

RECORD
        CARRIAGE_CONTROL        none
        FORMAT                  fixed
        SIZE                    180

KEY 0
        NAME                    "ACCOUNT_NUMBER"
        TYPE                    string
        DUPLICATES              no
        CHANGES                 no
        SEG0_POSITION           0
        SEG0_LENGTH             10

FORTRAN-callable jackets

FDL$CREATE, FDL$GENERATE, and FDL$PARSE also expose FORTRAN-callable jackets (the F4_* variants). These accept FORTRAN string descriptors, unpack them, and call the C entry point, so mixed COBOL, FORTRAN, and C application code links against the same library. FDL$RELEASE has no FORTRAN jacket.

Flag bits

Four public flag bits gate the string-versus-file behaviour of FDL$PARSE and FDL$GENERATE:

Status reporting

The FDL facility defines 33 FDL$_ message codes for source compatibility, tested with the usual (status & 1) success convention. The shipping library emits FDL$_OPENFDL when a CREATE/FDL input file is not found, and otherwise returns the generic RMS and system status codes (RMS$_NORMAL, RMS$_FNF for file not found, SS$_NORMAL, and related values). FDL-facility status reporting is therefore thinner than the OpenVMS original; see the status matrix below.

Create path

FDL$CREATE seeds RMS defaults into a FAB and RAB, parses the FDL text into that FAB, resolves the output file name (from the routine argument or the FDL's DEFAULT_NAME), then runs SYS$PARSE and SYS$SEARCH to compute the next version and SYS$CREATE to materialise the structure, followed by SYS$CONNECT, SYS$DISCONNECT, and SYS$CLOSE. It supports three creation modes: the legacy in-place create, an erase-then-create-in-place mode, and a build-into-a-temporary-file mode used by CONVERT/FDL.

Parse path

FDL$PARSE allocates a fresh FAB and RAB, seeds RMS type, length, and organization defaults, and cross-links the RAB to the FAB. If a defaults source is supplied it is read first (from a string when FDL$M_DEFAULT_STRING is set, otherwise from a file), then the main FDL source is read and overlaid on top (from a string when FDL$M_FDL_STRING is set, otherwise from a file). File resolution tries the VMS-to-unix name, then retries with a .FDL type appended, then retries lowercased, returning RMS$_FNF only after all three miss. The stmt single-statement parameter is accepted for source compatibility but not used in this release.

Release path

FDL$RELEASE takes the address of the FAB and RAB pointers, frees the file-name string and any extended attribute block, then the FAB and the RAB, and nulls the caller's pointers to avoid dangling references. The flags and badblk arguments are accepted but unused.

End-to-end C example

The canonical setup, call, check, and cleanup path for a C caller parsing an FDL file into control blocks. Note the ODD() status test and the address-of-pointer passed to FDL$RELEASE:

/* string descriptor for the FDL spec */
VMS_DESCR fdl;
FABDEF   *fab = 0;
RABDEF   *rab = 0;
U32       flags = 0;          /* 0 means fdl_path is a FILE spec */
U32       status;

vxrt_dsc64t(&fdl, (U16)strlen(fdl_path), (char *)fdl_path);

/* parse the FDL file into freshly allocated FAB / RAB */
status = FDL$PARSE(&fdl, &fab, &rab, &flags, /*def*/ 0, /*stmt*/ 0);
if (!ODD(status))            /* e.g. RMS$_FNF if the .FDL is absent */
    return status;

/* ... use fab / rab: SYS$CREATE, SYS$OPEN, inspect organization ... */

/* free exactly what FDL$PARSE allocated; fab and rab become NULL */
FDL$RELEASE(&fab, &rab, /*flags*/ 0, /*badblk*/ 0);
return SS$_NORMAL;

To parse an in-memory FDL string instead of a file, set flags = FDL$M_FDL_STRING and point the descriptor at the text.

CREATE/FDL

The /FDL= value is required and non-negatable; the optional trailing parameter is the output file name. The handler runs a file scan over the FDL spec to fill in device, directory, and name, and supplies .FDL when no type is given. /LOG prints a line reporting whether the file was created.

! FDL to RMS file (FDL$CREATE)
$ CREATE /FDL=CUSTOMER.FDL CUSTOMER.DAT

ANALYZE/RMS_FILE

The ANALYZE/RMS_FILE sub-syntax parses /CHECK, /FDL, /INTERACTIVE, /RU_JOURNAL, /STATISTICS, /SUMMARY, and /OUTPUT, but the handler acts only on /OUTPUT in this release: it writes the generated FDL to the named file. The other analysis qualifiers are accepted by the parser and not yet acted on. Use /OUTPUT=name.FDL to capture the FDL description.

! RMS file to FDL (FDL$GENERATE)
$ ANALYZE /RMS_FILE /OUTPUT=CUSTOMER.FDL CUSTOMER.DAT

CONVERT/FDL

! load records into an FDL-defined output file
$ CONVERT /FDL=CUSTOMER.FDL CUSTOMER.SEQ CUSTOMER.IDX

Divergences from OpenVMS FDL

• FDL$GENERATE emits organization, record format, size, and key sections, not the AREA, ACCESS, SHARING, CONNECT, or ANALYSIS statistics blocks. The host RMS layer exposes those attributes through the FAB and key descriptors only.
• The SYSTEM SOURCE line comes from the Linux or Windows host name rather than a VMS node, because there is no VMS node identity on the target platform.
• FDL-facility status reporting is reduced to a small set of codes; most work returns the generic RMS and system status values. The full set of FDL$_ symbols exists for source compatibility.
• ANALYZE/RMS_FILE honours /OUTPUT; the other analysis qualifiers are accepted but inert in this release, which implements the FDL-generation path rather than the full ANALYZE utility family.

Related pages

• VX/RMS SYS$ Routines for RMS reads and writes the RMS files that FDL defines.
• FDL$ File Definition Language API is the callable routine set this page describes.
• VX/DCL OpenVMS DCL hosts the CREATE/FDL, ANALYZE/RMS_FILE, and CONVERT/FDL commands.
• VX/DATAX OpenVMS RMS Data Exchange for moving RMS data between VMS and the target host.

Public routines

FDL$CREATE   (fdl, fname)                          // create RMS file from FDL
FDL$GENERATE (flags, fab, rab, fdl)                // RMS file to FDL text
FDL$PARSE    (fdl, fab, rab, flags, def, stmt)     // FDL to FAB / RAB
FDL$RELEASE  (pfab, prab, flags, badblk)           // free parsed FAB / RAB

Return convention: odd means success, even means failure; test ODD(status).

VX/DCL commands

$ CREATE  /FDL=CUSTOMER.FDL CUSTOMER.DAT             ! FDL to RMS file (FDL$CREATE)
$ ANALYZE /RMS_FILE /OUTPUT=CUSTOMER.FDL CUSTOMER.DAT  ! RMS file to FDL (FDL$GENERATE)
$ CONVERT /FDL=CUSTOMER.FDL CUSTOMER.SEQ CUSTOMER.IDX  ! load records into FDL-defined file

Flag bits

FDL primary sections

KEY data types

File organizations and record formats