CONV$ – File Conversion

VX/CONV$ is a call-compatible reimplementation of the OpenVMS CONVERT/FDL callable interface for x86 and ARM Linux. It is the CONV$ routine family that OpenVMS applications use to copy records from one file into another whose organization and attributes come from an FDL (File Definition Language) description. Existing calls to CONV$PASS_FILES, CONV$PASS_OPTIONS, CONV$CONVERT, and CONV$RECLAIM link and run without source changes.

It is not a standalone daemon or a compiler: the callable surface is a small set of C-linkage entry points compiled into the shared VX runtime and driven by a three-call state machine. VX/CONV$ runs inside the VX/RT ecosystem, building output files from FDL definitions, reading and writing records through the VX/RMS runtime, and preserving data integrity by padding, truncating, or reporting records rather than silently corrupting them when file layouts differ.

Architecture and components

VX/CONV$ is a library, not a server. There is no daemon to administer and no separate conv binary: the entire callable surface compiles into the shared VX runtime archive (libvxrt.a) and is driven directly by the migrated application. Because CONV$ is a library, its "components" are the four exported entry points plus the RMS and FDL runtimes they delegate to.

OpenVMS routine	Role	Status
`CONV$PASS_FILES`	Queue the input file(s), the output file, an optional FDL, and an optional exception file; advance the state machine to the options stage.	live
`CONV$PASS_OPTIONS`	Load the option vector, apply defaults, and reject conflicting qualifiers; advance the state machine to the convert stage.	live
`CONV$CONVERT`	Run the conversion, fill the caller's statistics block, and reset the state machine to the files stage.	live
`CONV$RECLAIM`	Report file allocation statistics. On OpenVMS this reclaims empty index buckets; on Linux it reports allocation only (see the compatibility section).	partial

No server to administer. There is no process to start, no configuration file, and no IPC substrate. Applications link the VX runtime and call the CONV$ entry points directly, exactly as they did on OpenVMS.

Runtime dependencies

The conversion routines delegate the real work to the rest of the VX/RT toolset. This is why VX/CONV$ slots into a full OpenVMS-compatible estate rather than working in isolation.

Dependency	What CONV$ uses it for
VX/RMS (`SYS$` services)	Open, create, connect, get, put, close, and disconnect on FAB, RAB, and XAB control blocks for every input and output file.
VX/FDL (`FDL$CREATE`)	Build the output file from an FDL definition when the FDL option is set.
VX/SORT options	Shares the sort, merge, and work-file option encoding with the SORT interface.
STR$ / LIB$ routines	Marshal filename descriptors and probe for file existence.
Indexed-file layer (D-ISAM)	Handle indexed (IDX) organizations and erase existing relative and sequential output.

Component map

ApplicationCalls the CONV$ entry points

Delegates through

libvxrt.aCONV$ entry points coordinate the conversion

Uses three runtime branches

VX/FDL createFDL$CREATE builds an FDL-defined output

VX/RMS record I/OSYS$OPEN, GET, PUT, and CLOSE

Indexed-file layerIDX open and erase operations

Branches converge

Output file built and records copiedThe selected dependencies create, populate, and finalize the output

The call lifecycle

VX/CONV$ is a three-stage state machine. Each routine checks that it is being called in the right stage and, on a mismatch, resets the sequence to the start and returns an order status (CONV$_ORDER). The required order is PASS_FILES, then PASS_OPTIONS, then CONVERT.

1. PASS_FILESQueue input files, output file, FDL, and exception file

2. PASS_OPTIONSLoad defaults, apply options, and validate conflicts

3. CONVERTCopy records and write the statistics block

Normal reset loop: after each successful conversion, the sequence returns to PASS_FILES for the next run.

Wrong-order reset: a call made at the wrong stage returns CONV$_ORDER and resets the sequence to PASS_FILES.

Stage 1: pass files

Call CONV$PASS_FILES once per input file. The first call that carries an output name resets the input list and saves the output file and the optional FDL; subsequent calls with no output name append further input files, up to a maximum of 10. No input file returns CONV$_NARG; overflowing the input limit returns CONV$_INP_FILES. On success the stage advances to options.

Stage 2: pass options

CONV$PASS_OPTIONS loads the defaults, overlays the caller's option list, validates it, and advances the stage to convert. Conflicting qualifiers are rejected here before any file is touched (see the options section).

Stage 3: convert

CONV$CONVERT performs the copy, writes the statistics back into the caller's block, and resets the stage to files so the next conversion starts cleanly.

Single, process-global context. The stage, the option vector, the statistics, and the file control blocks are module-level state shared across the process, matching the single-context OpenVMS callable interface. Concurrent conversions on separate threads share that state, so run conversions sequentially rather than in parallel within a process.

Conversion options

CONV$PASS_OPTIONS takes a counted array: the first element is the number of option words that follow, and the remaining elements populate a 19-slot option vector. The named slots are:

Index	Option	Index	Option	Index	Option
0	`create`	7	`key`	14	`read_check`
1	`share`	8	`pad`	15	`write_check`
2	`fast_load`	9	`padchar`	16	`fdl`
3	`merge`	10	`truncate`	17	`exception`
4	`append`	11	`exit`	18	`prolog`
5	`sort`	12	`fixed_control`
6	`work_files`	13	`fill_buckets`

Defaults

Before the caller's list is overlaid, the vector is zeroed and then these defaults are applied: create = 1, fast_load = 1, sort = 1, and work_files = 2. All other slots default to zero.

Consistency check

CONV$PASS_OPTIONS rejects contradictory requests up front with CONV$_CONFQUAL ("conflicting qualifiers") in any of these cases:

An FDL filename was passed, but the fdl option is not set.
The fdl option is set while create is clear.
Both pad and truncate are set.

Which options change behaviour today. On the current Linux conversion path, the options that alter the conversion are fdl, pad, padchar, and truncate. The remaining slots (share, merge, append, sort, key, work_files, fixed_control, fill_buckets, read_check, write_check, exception, prolog, exit) are accepted and stored for call compatibility so existing option vectors pass through unchanged. Confirm the exact option encoding against the CONV$ API reference before relying on a specific option's effect.

The convert path and record integrity

CONV$CONVERT runs a top-level loop that creates the output file, then opens each input file in turn and copies its records into the output. The output can be local or on a remote node.

How the output file is created

When the fdl option is set, the output file is built first from the FDL definition through FDL$CREATE, giving the output an explicit organization and attributes.
When there is no FDL, the output organization defaults to the input's own organization, so the conversion copies attributes rather than reformatting. Any pre-existing output is removed first: indexed files are unlinked, and relative or sequential files are erased through the indexed-file layer.
If the output resolves to a remote node, the copy is handled with an SSH-based transport, with network failures mapped back to RMS status values (for example an SSH transport failure maps to RMS$_NETFAIL).

Record-size policy

The record copy loop is where the "preserves data integrity" guarantee actually lives. For each record read from the input, VX/CONV$ compares the input and output maximum record sizes and applies one of three policies:

Case	Behaviour	Result
Sizes equal	Copy the record verbatim.	copied
Input longer than output	If `truncate` is set, shrink to the output size; otherwise reject the record.	truncated, or `CONV$_RTL` (record too long)
Input shorter than output	If `pad` is set, pad with `padchar` to the output size; otherwise reject the record.	padded, or `CONV$_RTS` (record too short)

A record that cannot be safely resized is counted as an exception rather than silently corrupted. The routine returns a record-too-long or record-too-short status, and the exception count is reported back in the statistics block. This is the substance behind the product's data-integrity claim: records are either copied faithfully, resized under an explicit option, or flagged, never truncated by accident.

Read one input recordUse RMS GET, then compare input and output maximum record sizes

Choose one size policy

Sizes matchCopy the record verbatim

Input is longerTruncate only when allowed, otherwise count a CONV$_RTL exception

Input is shorterPad with padchar only when allowed, otherwise count a CONV$_RTS exception

All outcomes continue

Write or flag the recordUse RMS PUT for accepted records, then continue until end-of-file

Final report: files processed, records handled, exceptions counted, and validity status.

Callable routines and linkage

The four CONV$ routines are exported under both their upper-case (CONV$...) and lower-case (conv$...) names, so existing object references resolve unchanged. Each routine returns an OpenVMS condition value by value: odd means success, even means failure.

CONV$ routine	Function
`CONV$CONVERT`	Convert data format
`CONV$PASS_FILES`	Pass files for conversion
`CONV$PASS_OPTIONS`	Pass conversion options
`CONV$RECLAIM`	Reclaim conversion resources

Signatures

U32 CONV$PASS_FILES  (VMS_DESCR *Ifil, VMS_DESCR *Ofil, VMS_DESCR *Fdl,
                      VMS_DESCR *Exc, U32 *flags);
U32 CONV$PASS_OPTIONS(U32 *plist, U32 *flags);
U32 CONV$CONVERT     (U32 *statblock, U32 *flags);
U32 CONV$RECLAIM     (VMS_DESCR *InFile, U32 Stats[]);

FORTRAN and external linkage

Each routine also has a FORTRAN-descriptor wrapper that trims blank-padded FORTRAN strings before calling the C entry point, so applications written in FORTRAN as well as C, Pascal, and other OpenVMS languages call the same names. This is what makes migration a link-and-run exercise rather than a rewrite.

Statistics blocks

CONV$CONVERT writes back a counted statistics array in the same shape the options are read: if the caller supplies a block and a count, that many words are copied from the four internal results.

Slot	Statistic
0	Number of files converted
1	Number of records read
2	Number of exception records
3	Number of valid records written

CONV$RECLAIM fills a separate statistics array, reporting the file allocation in 512-byte blocks.

Compatibility and status

The table below is the honest coverage matrix for the current Linux implementation: what runs today, what is accepted for compatibility but not yet fully wired, and what is out of scope.

Capability	Status
Files state machine and multi-input queue (up to 10 inputs), FDL and output capture	live
Options defaults and conflict checks (pad/truncate, fdl/create)	live
Local copy for sequential, relative, and indexed output through RMS and FDL, with statistics writeback	live
Record pad and truncate with pad character, and exception counting	live
Remote-node output copy over SSH transport	live
Option slots beyond fdl, pad, padchar, and truncate	partial: accepted and stored, not consumed on the current path
`CONV$RECLAIM`	partial: reports allocation only
OpenVMS index reclamation and bucket compaction (the full meaning of RECLAIM)	out of scope in this implementation

CONV$RECLAIM is a compatibility placeholder. On OpenVMS, CONV$RECLAIM reclaims free space in the index structure of a Prolog-3 indexed file. In this implementation it reports file allocation statistics and does not perform index reclamation. Treat it as a routine that links and returns success for compatibility, not as working index-reclaim functionality.

Status and condition codes

VX/CONV$ returns the same CONV$ condition-code vocabulary as OpenVMS. The codes the conversion path actually produces are:

Symbol	Meaning
`SS$_NORMAL`	Success.
`CONV$_ORDER`	Routines called out of order; the sequence resets to the files stage.
`CONV$_NARG`	No input file supplied.
`CONV$_INP_FILES`	Too many input files (more than 10).
`CONV$_CONFQUAL`	Conflicting qualifiers in the option vector.
`CONV$_RTL`	Record too long and truncate not requested.
`CONV$_RTS`	Record too short and pad not requested.
`CONV$_OPENIN` / `CONV$_OPENOUT`	Error opening the input or output file.

The broader OpenVMS CONV$ catalogue defines many additional index, bucket, and key error conditions. Those symbols exist for message compatibility but are not raised by this implementation, because the indexed-file reclaim and load-index paths they describe are not implemented here.

Deliberate divergences from OpenVMS CONVERT/FDL

Divergence	Reason
One process-global state machine; conversions are not re-entrant.	Matches the single-context OpenVMS callable interface, so concurrent conversions in one process are a real constraint on Linux.
Output-file preparation is delegated to RMS and the indexed-file layer.	Linux has no native RMS on-disk format; VX/RMS and the indexed-file layer provide it.
Remote output uses SSH transport, with SSH failures mapped to RMS network status.	DECnet file access is replaced by an SSH-based transport on Linux.
Non-FDL conversions copy the input's organization verbatim.	Without an FDL there is no target attribute description, so attributes are copied rather than reformatted.

End-to-end example

The sequence below exercises the full state machine to convert a sequential account-export file into an indexed file, using an FDL definition to describe the indexed output and padding short records to the new record size. The filenames use the site's banking demo domain; the routine names, argument order, option indices, and status symbols are the real API.

/* VMS-style counted string descriptors */
VMS_DESCR ifil = { "BANKING:ACCOUNTS.SEQ" };   /* input:  sequential export   */
VMS_DESCR ofil = { "BANKING:ACCOUNTS.IDX" };   /* output: indexed file        */
VMS_DESCR fdl  = { "BANKING:ACCOUNTS.FDL" };   /* output layout description   */
U32 flags = 0, st;

/* 1. queue files: an output name resets the input list and saves output + FDL */
st = CONV$PASS_FILES(&ifil, &ofil, &fdl, /*Exc*/ 0, &flags);
if (!ODD(st)) return st;      /* CONV$_NARG / CONV$_INP_FILES / CONV$_ORDER */

/* 2. options: plist[0] = word count, then the 19-slot vector.
      set fdl (idx 16), pad (idx 8), and pad character (idx 9). */
U32 opts[1 + 19] = {0};
opts[0]      = 19;                /* number of option words */
opts[1 + 16] = 1;                 /* fdl     */
opts[1 + 8]  = 1;                 /* pad     */
opts[1 + 9]  = ' ';               /* padchar */
st = CONV$PASS_OPTIONS(opts, &flags);
if (!ODD(st)) return st;      /* CONV$_CONFQUAL if pad and truncate both set */

/* 3. convert; statblock[0] = number of statistics words requested */
U32 stats[1 + 4] = { 4, 0, 0, 0, 0 };
st = CONV$CONVERT(stats, &flags);
/* stats[1]=files stats[2]=records stats[3]=exceptions stats[4]=valid */
return st;                       /* SS$_NORMAL, or CONV$_RTL / CONV$_RTS */

Call order matters. The same three calls in the same order run on OpenVMS and on Linux without change. Calling them out of order returns CONV$_ORDER and resets the sequence, so error handling that already exists on OpenVMS behaves identically.

Quick reference

Call order

CONV$PASS_FILES (once per input; the first call with an output name resets the list) then CONV$PASS_OPTIONS then CONV$CONVERT. Any wrong order returns CONV$_ORDER and resets to the files stage.

Limits and defaults

max input files = 10

option slots = 19

statistics slots = 4

default create = 1

default fast_load = 1

default sort = 1

default work_files = 2

Options consumed on the current path

fdl

pad

padchar

truncate

Statistics (CONVERT)

files

records

exceptions

valid

Status codes

SS$_NORMAL

CONV$_ORDER

CONV$_NARG

CONV$_INP_FILES

CONV$_CONFQUAL

CONV$_RTL

CONV$_RTS

CONV$_OPENIN

CONV$_OPENOUT

On this page

Architecture and components

Stage 2: pass options

The convert path and record integrity

How the output file is created

Record-size policy

Callable routines and linkage

Signatures

FORTRAN and external linkage

Statistics blocks

Compatibility and status

Status and condition codes

Deliberate divergences from OpenVMS CONVERT/FDL

Options consumed on the current path

Statistics (CONVERT)

Status codes

Related VX tools

Frequently Asked Questions

Curious about how Sector7 can facilitate your application migration? Explore our FAQs for expert insights.

Free Code Assessment

CONV$ – File Conversion: What are the main features?

Main features include:

Full compatibility with OpenVMS CONV$ APIs
Support for data format conversion and file transfer
Option management and resource reclamation

What are common challenges in file conversion?

Common challenges include maintaining data integrity, handling proprietary formats, and ensuring compatibility. VX/CONV$ addresses these with robust conversion routines.

What is VX/CONV$ and how does it help with OpenVMS file conversion during Linux migration?

VX/CONV$ provides a call-compatible implementation of the OpenVMS file conversion API for x86 and ARM Linux platforms. It enables OpenVMS applications to convert file formats into Linux-compatible structures while preserving complete data integrity and format consistency during the migration process.

This solution allows organizations to migrate their OpenVMS applications that require file format transformations without major code modifications. For guidance on implementing VX/CONV$ in your migration project, contact our team.

Which OpenVMS CONV$ APIs are supported by VX/CONV$?

VX/CONV$ supports all key OpenVMS CONV$ APIs including CONV$CONVERT for data format conversion, CONV$PASS_FILES for file passing, CONV$PASS_OPTIONS for conversion options, and CONV$RECLAIM for resource management.

Does VX/CONV$ work on both x86 and ARM Linux platforms?

Yes, VX/CONV$ provides full compatibility across both x86 and ARM Linux architectures, ensuring your OpenVMS file conversion applications can run on any modern Linux environment.

How does the VX/CONV$ conversion process work?

VX/CONV$ handles conversion through its four main API functions: converting data formats, passing files for processing, managing conversion options, and reclaiming system resources after completion.

How does VX/CONV$ integrate with other VX tools for file handling?

VX/CONV$ seamlessly integrates with the VX/RT ecosystem to provide comprehensive OpenVMS file conversion capabilities on Linux. This integration ensures that applications requiring file format transformations work alongside other VX tools for complete OpenVMS compatibility.

Organizations like Telstra have successfully used integrated VX tool approaches for their complex system migrations involving multiple file formats and conversion requirements.

Can VX/CONV$ handle different OpenVMS file format types?

VX/CONV$ supports comprehensive data format conversion and file transfer operations, handling the various OpenVMS file structures and converting them to Linux-compatible formats while maintaining data integrity.

Does VX/CONV$ preserve data integrity during file format conversions?

VX/CONV$ is specifically designed to ensure complete data integrity and consistency during file structure conversions. This addresses one of the most critical challenges in OpenVMS migration - maintaining data accuracy while adapting file formats for Linux environments.

What are the key benefits of using VX/CONV$ for OpenVMS file conversion migration?

VX/CONV$ enables direct porting of OpenVMS applications requiring file format conversions without major modifications, significantly reducing development costs and preserving productivity. It supports all key OpenVMS conversion operations while ensuring complete data integrity throughout the migration process.

The tool integrates seamlessly into the VX/RT ecosystem, providing organizations with a comprehensive solution for maintaining file conversion capabilities on Linux. Companies like BNY Mellon have leveraged similar VX tools for their critical system migrations involving complex file operations.

To explore how VX/CONV$ can streamline your OpenVMS file conversion migration, contact our migration specialists.

What is VX/CONV$?

VX/CONV$ is a call-compatible reimplementation of the OpenVMS file conversion API (CONV$) for x86 and ARM Linux. It lets OpenVMS applications convert file formats into Linux-compatible structures while preserving data integrity and format consistency.

Which CONV$ routines does VX/CONV$ provide?

Four: CONV$CONVERT (convert data format), CONV$PASS_FILES (pass files for conversion), CONV$PASS_OPTIONS (pass conversion options), and CONV$RECLAIM (report conversion resources).

What order do the CONV$ routines have to be called in?

They form a state machine. Call CONV$PASS_FILES first to queue the input file(s), the output file, and an optional FDL, then CONV$PASS_OPTIONS to set conversion options, then CONV$CONVERT to run the conversion. Calling them out of order returns an order status, and the sequence resets after each convert.

What CPU architectures and platforms does VX/CONV$ run on?

x86 and ARM Linux. VX/CONV$ brings the OpenVMS CONV$ file-conversion API to both of those Linux architectures.

Do I have to rewrite my OpenVMS application to use VX/CONV$?

No. The CONV$ names are exported as call-compatible entry points, including FORTRAN-descriptor wrappers, so applications that require file-format transformations migrate without major code changes.

How does VX/CONV$ relate to VX/RT and the other VX tools?

VX/CONV$ runs inside the VX/RT ecosystem. It uses VX/FDL to create output files from FDL definitions, VX/RMS for record I/O, and shares sort and merge options with VX/SORT, so it fits into a full OpenVMS-compatible toolset rather than working in isolation.

Does VX/CONV$ preserve data integrity during conversion?

Yes. Records are copied through the RMS runtime, and when input and output record sizes differ VX/CONV$ pads or truncates according to the options you set, or reports a record-size exception rather than silently corrupting data.

What options can I set for a conversion?

CONV$PASS_OPTIONS accepts an option vector controlling behaviour such as create, share, fast-load, merge, append, sort, work-files, key, pad, pad-character, truncate, and FDL usage. Defaults enable create, fast-load and sort. Contradictory combinations (for example both pad and truncate) are rejected with a conflicting-qualifiers error.

Transform Your Legacy Software Today!

Get In Touch

Unlock the potential of your legacy software with our expert migration services.