VX/CDD - Common Data Dictionary / Repository
Overview
VX/CDD brings the OpenVMS Common Data Dictionary and CDD/Repository workflow to Linux. It preserves shared, language-independent field and record definitions so applications can continue to draw consistent declarations from one managed dictionary.
The product combines a compatible CDD$ callable interface, CDO, CDDL and DMU utilities, source ingestion, compiler-facing include expansion and multi-language extraction. Existing definitions and application integration points can be retained while the underlying repository moves to a modern, maintainable platform.
<div class="s7-tech-embed" data-vxcdd-body-embed="1" data-technical-mega-embed="1" lang="en"><h2 id="architecture">Architecture and components</h2><p>VX/CDD provides a shared dictionary store with compatible management, extraction and application interfaces. Definitions enter through CDO, CDDL, SQL DDL or structured record sources, then become reusable fields and records that can be rendered for each target language.</p><div class="table-wrapper"><table><thead><tr><th>OpenVMS capability</th><th>VX/CDD component</th><th>Purpose</th></tr></thead><tbody><tr><td>CDD/Repository</td><td>VX/CDD dictionary</td><td>Stores repositories, directories, fields, records, members, variants and SQL definitions.</td></tr><tr><td>CDDSHR callable interface</td><td><code>libvxcdd</code></td><td>Provides the compatible <code>CDD$</code> session and element operations used by existing applications and tools.</td></tr><tr><td>Compiler dictionary expansion</td><td><code>vxcddpp</code></td><td>Expands dictionary references for supported source languages and can pass the expanded source to the selected compiler.</td></tr><tr><td>CDO, CDDL and DMU</td><td>Command utilities</td><td>Manage dictionary content, compile definitions, browse directories and extract records.</td></tr><tr><td>CDD extraction</td><td><code>vxcdd</code> and extract APIs</td><td>Ingest definitions, list content and render reusable declarations for target languages.</td></tr></tbody></table></div><h6>Definition flow</h6><div class="cdd-definition-flow" aria-label="Source definitions enter the VX/CDD dictionary and branch to two consumer paths"><div class="cdd-flow-card"><span class="cdd-flow-label">Source definitions</span><strong>CDO, CDDL, SQL DDL, or record sources</strong><span>Managed definitions enter through supported source formats.</span></div><div class="cdd-flow-connector">Stored in</div><div class="cdd-flow-card cdd-flow-dictionary"><span class="cdd-flow-label">Shared store</span><strong>VX/CDD dictionary</strong><span>Maintains reusable fields, records, members, variants, and SQL definitions.</span></div><div class="cdd-flow-connector">Branches to two consumer paths</div><div class="cdd-flow-consumers"><div class="cdd-flow-card cdd-flow-consumer"><strong>Language extraction</strong><span>Renders native declarations for supported target languages.</span><div class="cdd-flow-result"><span class="cdd-flow-label">Consumed by</span><strong>Application builds</strong></div></div><div class="cdd-flow-card cdd-flow-consumer"><strong>CDD$ session access</strong><span>Exposes compatible callable dictionary operations.</span><div class="cdd-flow-result"><span class="cdd-flow-label">Consumed by</span><strong>Existing tools and code</strong></div></div></div></div><div class="callout"><strong>One definition, many consumers.</strong> A field or record is maintained once and rendered in the native declaration form required by each supported language.
</div><h2 id="dictionary-model">Dictionary model and source ingestion</h2><p>The dictionary is organised as a hierarchy of repositories, directories and named definitions. Fully qualified names identify an element unambiguously when the same short name appears in more than one directory.</p><div class="table-wrapper"><table><thead><tr><th>Dictionary object</th><th>Purpose</th></tr></thead><tbody><tr><td><strong>Repository</strong></td><td>Top-level namespace for a dictionary.</td></tr><tr><td><strong>Directory</strong></td><td>Hierarchical grouping such as <code>CDD$TOP.BANKING.CUSTOMER</code>.</td></tr><tr><td><strong>Field</strong></td><td>One typed data element that can be reused across records.</td></tr><tr><td><strong>Record</strong></td><td>An ordered aggregate of members with a defined storage layout.</td></tr><tr><td><strong>Member</strong></td><td>A local, included, based-on, structured or variant element within a record.</td></tr><tr><td><strong>Variant</strong></td><td>An overlay of alternative record layouts selected by the application.</td></tr><tr><td><strong>SQL source</strong></td><td>Schema definitions retained for analysis and SQL dialect conversion.</td></tr></tbody></table></div><h6>Accepted source formats</h6><div class="table-wrapper"><table><thead><tr><th>Format</th><th>Typical use</th></tr></thead><tbody><tr><td>CDO source</td><td>Define and manage fields, records and directories using the native CDD command language.</td></tr><tr><td>CDDL source</td><td>Compile CDD Data Definition Language files into the selected dictionary directory.</td></tr><tr><td>SQL DDL</td><td>Ingest domains, tables and columns for inventory and dialect conversion.</td></tr><tr><td>Structured record dumps</td><td>Load existing record definitions, including nested structures.</td></tr></tbody></table></div><p>Directory ingestion follows dependency order so shared SQL domains and mapped CDDL sources are available before dependent CDO definitions are processed. Unsupported file types are reported rather than silently ignored.</p><h2 id="language-extraction">Language extraction and compiler integration</h2><p>VX/CDD renders one central definition into the declaration style expected by each target language. Applications can continue to use dictionary references in their source while the build process expands those references into native declarations.</p><div class="table-wrapper"><table><thead><tr><th>Target</th><th>Rendering</th><th>Availability</th></tr></thead><tbody><tr><td>CDD</td><td>Original CDO definition</td><td><span class="ac-live">Extraction and preprocessing</span></td></tr><tr><td>COBOL</td><td>Data definitions with levels and PIC clauses</td><td><span class="ac-live">Extraction and preprocessing</span></td></tr><tr><td>Fortran 90</td><td>Derived type declaration</td><td><span class="ac-live">Extraction and preprocessing</span></td></tr><tr><td>FORTRAN 77</td><td>DEC STRUCTURE and RECORD declarations</td><td><span class="ac-live">Extraction and preprocessing</span></td></tr><tr><td>C</td><td><code>typedef struct</code> declaration</td><td><span class="ac-live">Extraction and preprocessing</span></td></tr><tr><td>C++</td><td>Compiler-facing dictionary include expansion</td><td><span class="ac-v1">Preprocessing only</span></td></tr><tr><td>DECforms IFDL</td><td>FORM RECORD declaration</td><td><span class="ac-live">Extraction</span></td></tr><tr><td>VAX Pascal</td><td>TYPE and RECORD declaration</td><td><span class="ac-v1">Extraction only</span></td></tr><tr><td>VAX BASIC</td><td>RECORD and END RECORD declaration</td><td><span class="ac-live">Extraction</span></td></tr></tbody></table></div><h6>Source-level dictionary references</h6><p>The preprocessor recognises established dictionary include forms in COBOL, C, C++, Fortran and FORTRAN 77. It can write expanded source for review or invoke the configured compiler with the expanded source and original build options.</p>
<pre>COBOL COPY CUSTOMER-RECORD FROM DICTIONARY.
C #pragma dictionary CDD$TOP.BANKING.CUSTOMER
Fortran INCLUDE 'CDD$TOP.BANKING.CUSTOMER'</pre>
<div class="callout"><strong>Existing source stays recognisable.</strong> Dictionary references remain part of the application source, while VX/CDD supplies the target platform declaration during the build.
</div><h2 id="management-utilities">CDO, CDDL and DMU utilities</h2><p>VX/CDD includes familiar management tools for interactive use, scripted dictionary builds and operational access on Linux.</p><div class="table-wrapper"><table><thead><tr><th>Utility</th><th>Role</th><th>Typical operations</th></tr></thead><tbody><tr><td><code>CDO</code></td><td>Common Dictionary Operator</td><td>Define, inspect, copy, move, change, purge, verify and extract dictionary elements.</td></tr><tr><td><code>CDDL</code></td><td>CDD Data Definition Language compiler</td><td>Compile definition files into the active repository and directory.</td></tr><tr><td><code>DMU</code></td><td>Dictionary Management Utility</td><td>Create or delete dictionaries, list directories, set defaults and extract definitions.</td></tr><tr><td><code>vxcdd</code></td><td>Cross-platform dictionary tool</td><td>Ingest sources, inventory content, extract declarations and convert SQL schemas.</td></tr></tbody></table></div><h6>CDO command language</h6><p>The CDO engine supports interactive commands and script files. Its top-level operations include <code>DEFINE</code>, <code>SHOW</code>, <code>DELETE</code>, <code>SET</code>, <code>DIRECTORY</code>, <code>ENTER</code>, <code>COPY</code>, <code>CHANGE</code>, <code>MOVE</code>, <code>PURGE</code>, <code>EXTRACT</code> and <code>VERIFY</code>.</p>
<pre><span class="kw">DEFINE DIRECTORY</span> BANKING.
<span class="kw">SET DEFAULT</span> BANKING
<span class="kw">DEFINE FIELD</span> CUSTOMER_ID
<span class="kw">DATATYPE IS</span> UNSIGNED NUMERIC SIZE IS 10 DIGITS.
<span class="kw">DEFINE FIELD</span> CUSTOMER_NAME
<span class="kw">DATATYPE IS</span> TEXT SIZE IS 40 CHARACTERS.</pre>
<h6>SQL schema conversion</h6><p>Ingested SQL DDL can be analysed, retained and rendered for Oracle, PostgreSQL, SQLite, MySQL, MariaDB and SQL Server. This gives database migration teams a consistent inventory alongside application record definitions.</p><h2 id="callable-api">CDD$ callable interface</h2><p><code>libvxcdd</code> provides the CDD/Plus callable contract used by existing applications and utilities. The interface preserves the established routine names, packed OpenVMS descriptors, session lifecycle, metadata tags and condition values expected by compatible callers.</p><h6>Session lifecycle</h6><style>
.s7-tech-embed .cdd-lifecycle {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 10px;
margin: 1.5rem 0;
padding: 16px;
border: 1px solid var(--s7t-border);
border-radius: 10px;
background: rgba(255, 255, 255, 0.01);
list-style: none;
}
.s7-tech-embed .cdd-definition-flow {
margin: 1.5rem 0;
padding: 16px;
border: 1px solid var(--s7t-border);
border-radius: 10px;
background: rgba(255, 255, 255, 0.01);
}
.s7-tech-embed .cdd-flow-card {
min-width: 0;
padding: 14px 16px;
border-radius: 8px;
background: var(--s7t-surface);
color: var(--s7t-text);
}
.s7-tech-embed .cdd-flow-card strong,
.s7-tech-embed .cdd-flow-card span:last-child {
display: block;
}
.s7-tech-embed .cdd-flow-card strong {
margin-bottom: 4px;
}
.s7-tech-embed .cdd-flow-card span:last-child {
color: var(--s7t-muted);
font-size: 0.9em;
line-height: 1.45;
}
.s7-tech-embed .cdd-flow-label,
.s7-tech-embed .cdd-flow-connector {
font-family: var(--s7t-mono);
color: var(--s7t-accent);
font-size: 0.76em;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.s7-tech-embed .cdd-flow-label {
margin-bottom: 8px;
}
.s7-tech-embed .cdd-flow-connector {
padding: 10px;
text-align: center;
}
.s7-tech-embed .cdd-flow-dictionary {
border: 1px solid var(--s7t-note-bd);
background: var(--s7t-note-bg);
}
.s7-tech-embed .cdd-flow-consumers {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 10px;
}
.s7-tech-embed .cdd-flow-consumer {
border-top: 3px solid var(--s7t-accent);
background: var(--s7t-surface2);
}
.s7-tech-embed .cdd-flow-result {
margin-top: 10px;
padding-top: 10px;
border-top: 1px solid var(--s7t-border);
}
.s7-tech-embed .cdd-flow-result .cdd-flow-label {
display: block;
margin-bottom: 4px;
}
.s7-tech-embed .cdd-step {
min-width: 0;
padding: 15px;
border-top: 3px solid var(--s7t-accent);
border-radius: 6px;
background: var(--s7t-surface2);
color: var(--s7t-text);
}
.s7-tech-embed .cdd-number {
display: block;
margin-bottom: 10px;
font-family: var(--s7t-mono);
color: var(--s7t-accent);
font-size: 0.76em;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.s7-tech-embed .cdd-step strong,
.s7-tech-embed .cdd-step span:last-child {
display: block;
}
.s7-tech-embed .cdd-step strong {
margin-bottom: 4px;
overflow-wrap: anywhere;
}
.s7-tech-embed .cdd-step span:last-child {
color: var(--s7t-muted);
font-size: 0.9em;
line-height: 1.45;
}
@media (max-width: 800px) {
.s7-tech-embed .cdd-lifecycle,
.s7-tech-embed .cdd-flow-consumers {
grid-template-columns: 1fr;
}
}
</style><ol class="cdd-lifecycle" aria-label="CDD callable interface session lifecycle"><li class="cdd-step"><span class="cdd-number">01</span><strong><code>CDD$ATTACH</code></strong><span>Acquire a user context.</span></li><li class="cdd-step"><span class="cdd-number">02</span><strong><code>CDD$START_SESSION</code></strong><span>Begin the dictionary session.</span></li><li class="cdd-step"><span class="cdd-number">03</span><strong><code>CDD$SET_ANCHOR</code> or <code>CDD$SET_DEFAULT</code></strong><span>Select the dictionary location.</span></li><li class="cdd-step"><span class="cdd-number">04</span><strong><code>CDD$FETCH_START</code> / <code>CDD$FETCH_NEXT</code></strong><span>Iterate matching dictionary content.</span></li><li class="cdd-step"><span class="cdd-number">05</span><strong><code>CDD$GET_ELEMENT</code></strong><span>Return the selected element metadata.</span></li><li class="cdd-step"><span class="cdd-number">06</span><strong><code>CDD$END_SESSION</code></strong><span>Close the dictionary session.</span></li><li class="cdd-step"><span class="cdd-number">07</span><strong><code>CDD$DETACH</code></strong><span>Release the user context.</span></li></ol><div class="table-wrapper"><table><thead><tr><th>Routine group</th><th>Purpose</th></tr></thead><tbody><tr><td><code>CDD$ATTACH</code>, <code>CDD$DETACH</code></td><td>Acquire and release a user context.</td></tr><tr><td><code>CDD$START_SESSION</code>, <code>CDD$END_SESSION</code></td><td>Control dictionary sessions and transaction scope.</td></tr><tr><td><code>CDD$SET_ANCHOR</code>, <code>CDD$TRANSLATE</code></td><td>Select and resolve dictionary locations.</td></tr><tr><td><code>CDD$DEFINE_ELEMENT</code>, <code>CDD$CHANGE_ELEMENT</code></td><td>Create or update elements from compatible metadata buffers.</td></tr><tr><td><code>CDD$FETCH_START</code>, <code>CDD$FETCH_NEXT</code>, <code>CDD$FETCH_END</code></td><td>Iterate matching dictionary content.</td></tr><tr><td><code>CDD$GET_ELEMENT</code></td><td>Return an element as a CDDSHR-compatible metadata buffer.</td></tr><tr><td><code>CDD$COPY_ELEMENTS</code>, <code>CDD$ERASE_ELEMENT</code>, <code>CDD$PURGE_ELEMENT</code></td><td>Copy and manage element versions.</td></tr><tr><td><code>CDD$VERIFY</code>, <code>CDD$VERSION</code></td><td>Verify a dictionary and report interface version information.</td></tr><tr><td><code>CDO$INTERPRET</code></td><td>Execute a CDO command through the callable interface.</td></tr></tbody></table></div><p>The documented callable surface contains 27 <code>CDD$</code> routines and 2 <code>CDO$</code> routines. Higher-level extraction entry points are also available for applications that need rendered text without manually traversing metadata buffers.</p><div class="callout"><strong>Compatibility is defined at the interface boundary.</strong> VX/CDD reproduces the byte layouts, tag ordering and condition handling consumed by established CDD clients.
</div><h2 id="compatibility">Compatibility and validation</h2><p>VX/CDD is designed around the OpenVMS CDD contract rather than a new, product-specific representation. Dictionary metadata, relationship tags, array bounds, variant structures, descriptors and status handling follow the established CDD model so existing consumers see familiar data.</p><div class="table-wrapper"><table><thead><tr><th>Compatibility area</th><th>Coverage</th></tr></thead><tbody><tr><td>CDD hierarchy</td><td><span class="ac-live">Repositories, directories, fields, records and qualified names</span></td></tr><tr><td>Record structures</td><td><span class="ac-live">Included fields, based-on members, arrays, nested structures and variants</span></td></tr><tr><td>CDD$ metadata</td><td><span class="ac-live">Compatible metadata buffers, entity tags, relationship tags and descriptors</span></td></tr><tr><td>Management tools</td><td><span class="ac-live">CDO, CDDL and DMU command workflows</span></td></tr><tr><td>Language extraction</td><td><span class="ac-live">CDD, COBOL, Fortran, C, FORTRAN 77, IFDL, Pascal and BASIC</span></td></tr><tr><td>C++ dictionary expansion</td><td><span class="ac-v1">Available through the source preprocessor</span></td></tr><tr><td>Pascal dictionary expansion</td><td><span class="ac-v1">Extraction is available; preprocessor expansion is not currently included</span></td></tr></tbody></table></div><h6>Validation approach</h6><p>Representative dictionaries cover scalar datatypes, nested records, arrays and multi-arm variants. Extracted structures and callable-interface metadata are compared with OpenVMS CDD behaviour and compiler-produced declarations to verify both source meaning and storage layout.</p><div class="callout"><strong>No silent substitution.</strong> A compatibility mismatch is treated as an implementation issue to correct, not as a reason to change the calling application or redefine the OpenVMS contract.
</div><h2 id="quick-reference">Quick reference</h2><h6>Common command patterns</h6><div class="table-wrapper"><table><thead><tr><th>Task</th><th>Command pattern</th></tr></thead><tbody><tr><td>Ingest a source directory</td><td><code>vxcdd --cdd=cdd.db --adddir=./schema</code></td></tr><tr><td>Extract one record as C</td><td><code>vxcdd --cdd=cdd.db --extr=CUSTOMER_RECORD --lang=c</code></td></tr><tr><td>List dictionary records</td><td><code>vxcdd --cdd=cdd.db --list=records</code></td></tr><tr><td>Expand and compile COBOL</td><td><code>vxcddpp --cdd=cdd.db --compile customer.cob</code></td></tr><tr><td>Run one CDO command</td><td><code>CDO /EXECUTE="SHOW REPOSITORIES"</code></td></tr><tr><td>Browse with DMU</td><td><code>DMU DIRECTORY</code></td></tr></tbody></table></div><h6>Supported SQL targets</h6><div class="kw-grid"><div>Oracle</div><div>PostgreSQL</div><div>SQLite</div><div>MySQL</div><div>MariaDB</div><div>SQL Server</div></div><h6>Dictionary location order</h6><p>When no path is supplied, VX/CDD checks <code>VX_CDD</code>, then <code>CDD_TOP</code>, then the configured CDD setting, and finally <code>./cdd.db</code>.</p></div>
