Skip to content

MetaDataTool Utility

MetaDataTool is a command line utility to generate various kinds of metadata that is useful when working with the Streaming Integration Platform, GantrySQL, and Synergy repositories.

Platforms and Requirements

MetaDataTool is supported on Windows x64 and Linux x64 and has the following requirements:

  • Synergy licensing and an available runtime license
  • .NET 8, 9, or 10 runtime or SDK
  • Internet access to nuget.org for installation and updates

Installing and Uninstalling MetaDataTool

MetaDataTool can be downloaded and installed using the .NET CLI.

To install MetaDataTool:

C:\> dotnet tool install --global Synergex.MetaDataTool

You'll get a message that MetaDataTool was successfully installed.

During installation, the MetaDataTool command is added to your .NET tools path. On Windows, if the command is not available immediately, close your terminal window and open a new one.

To uninstall MetaDataTool:

C:\> dotnet tool uninstall --global Synergex.MetaDataTool

You'll get a message that MetaDataTool was successfully uninstalled.

Installed Version and Updates

To show the currently installed version, run MetaDataTool with the version command:

metadatatool version

For example,

C:> metadatatool version
MetaDataTool 1.0.26211.2323 built on 2026-07-30 23:23 UTC

Automatic update checks are enabled by default and occur at most once per week on startup, printing a message if a newer version is on NuGet.org. You can manage update checks using the update command:

metadatatool update [--on|--off|--status] [--help]

Optional arguments:

--on

   Enable weekly automatic update checks.

--off

   Disable weekly automatic update checks.

--status

   Show whether automatic update checks are enabled.

--help or -h

   Display usage information.

If you don't specify an argument, metadatatool update checks for a newer version immediately. For example,

C:> metadatatool update
A newer version of Synergex.MetaDataTool is available: 1.0.26204.1519 (installed: 1.0.26203.2352).
Run 'dotnet tool update --global Synergex.MetaDataTool' to install it.

C:\> dotnet tool update --global Synergex.MetaDataTool
Tool 'synergex.metadatatool' was successfully updated from version '1.0.26203.2352' to version '1.0.26204.1519'.

Using MetaDataTool

MetaDataTool can produce the following types of metadata:

  • ISAM metadata
    • From SDMS ISAM files (isamfdl mode)
    • From OpenVMS FDL files (isamfile mode)
  • SQL metadata
    • From ISAM and Synergy repository metadata (sql mode)
  • SDL key definition snippets
    • From ISAM and repository metadata (keysdl mode, plus addkeys)

The syntax for running MetaDataTool is

metadatatool <mode> [<arguments>]

Modes:

   addkeys        Add ISAM key-definition snippets to SDL schema files
   help           Display help information
   isamfdl        Generate ISAM metadata from FDL files
   isamfile       Generate ISAM metadata from ISAM files
   keysdl         Generate ISAM key definition SDL snippets
   sql            Generate SQL metadata from repository definitions
   update         Check NuGet.org for a newer version of this tool
   version        Print version information

Generating ISAM Metadata from FDL Files (isamfdl)

In isamfdl mode, the utility reads one or more OpenVMS FDL files and produces ISAM metadata files.

metadatatool isamfdl --input <file> [--output <directory>] [--verbose]

Required arguments:

--input <file> or -i <file>

   Specify the FDL file(s) or an input list file with the files to process.

Optional arguments:

--output <directory> or -o <directory>

   Optionally specify where output files are created.

--nokeytruncwarn

   Suppress key name truncation warnings.

--norelwarn

   Suppress relative file warnings.

--verbose or -v

   Display more messages to the console.

--help or -h

   Display usage information.

Specifying a single FDL file as input creates a single output file with the same base name and a .JSON extension. Specifying a wildcard or an input file containing a list of FDL files creates an output file named FILES.JSON.

Input list files may contain blank lines and comments that begin with #, !, or ;. Relative paths in input list files are resolved using the list file's directory.

You can use OpenVMS-style logical names to specify the location of input and output files. For example, --input FDL:CUSTOMER.FDL or --output METADATA:. Note that logical names used in this way must exist in the system environment, as synergy.ini is not used.

To create metadata from a single FDL file, use a command like this:

metadatatool isamfdl --input FDL:CUSTOMER.FDL

The output file CUSTOMER.JSON will be in the current directory.

To create metadata from multiple FDL files, use an input file, like this:

# Input file for producing ISAM metadata from FDL files

FDL:CUSTOMER.FDL
FDL:INVENTORY.FDL

and a command like this:

metadatatool isamfdl --input FDLFILES.LIS

The output file FILES.JSON will be in the current directory.

Generating ISAM Metadata from ISAM Files (isamfile)

In isamfile mode, the utility reads one or more SDMS ISAM files and produces ISAM metadata files.

metadatatool isamfile --input <file> [--output <directory>]
                      [--verbose] [--help]

Required arguments:

--input <file> or -i <file>

   Specify either an SDMS ISAM file or an input list file containing the ISAM files to process.

Optional arguments:

--output <directory> or -o <directory>

   Specify where output files are created.

--verbose or -v

   Display more messages to the console.

--help or -h

   Display usage information.

Specifying a single ISAM file as input creates a single output file with the same base name and a .JSON extension. Specifying a wildcard or an input file containing a list of ISAM files creates an output file named FILES.JSON.

Input list files may contain blank lines and comments that begin with #, !, or ;. Relative paths in an input list file are resolved using the list file's directory.

OpenVMS-style logical names can be used to specify the location of input and output files. For example, --input DAT:CUSTOMER.ISM or --output METADATA:. Logical-name prefixes are retained in the FileSpec values written to metadata; for wildcard input, the actual matched filename follows the logical-name prefix. Note that logical names used in this way must exist in the system environment, as synergy.ini is not used.

To create metadata from a single ISAM file, use a command like this:

metadatatool isamfile --input DAT:INVENTORY.ISM

The output file INVENTORY.JSON will be in the current directory.

To create metadata from multiple ISAM files, use an input file, like this:

# Input file for producing ISAM metadata from ISAM files

DAT:CUSTOMER.ISM
DAT:INVENTORY.ISM

and a command like this:

metadatatool isamfdl --input DATAFILES.LIS

The output file FILES.JSON will be in the current directory.

Generating SQL Metadata from Repository Definitions (sql)

In sql mode, the utility reads one or more FILE definitions from a Synergy repository and produces SQL metadata files.

metadatatool sql --all | --files <file1> [<file2>...] | --input <file>
                 [--output <directory>] [--individual] [--format-odbc]
                 [--alternate-names] [--noarraycolunderscore]
                 [--repository <main-file> <text-file>] [--verbose]
                 [--help]

Required arguments (choose one):

--all or -a

   Process all file repository definitions.

--files <file1> [<file2>...] or -f <file1> [<file2>...]

   Process the specified repository file definitions.

--input <file> or -i <file>

   Process repository file definitions listed in the specified input file.

Optional arguments:

--output <directory> or -o <directory>

   Specify where output files are created.

--individual

   Produce an outout file for each file definition.

--format-odbc

   Use xfODBC output format (one file per definition, lowercase names)

--alternate-names

   Name columns using each field's repository alternate name. This option can be used independently of --format-odbc. In --format-odbc mode, if this option is omitted, the SODBC_ODBCNAME environment variable is also honored.

--noarraycolunderscore

   Remove the underscore before the trailing array-element index (for example, _1 becomes 1) when the repository field was an array element.

--repository <main-file> <text-file> or -r <main-file> <text-file>

   Specify the Synergy repository files to use.

--verbose or -v

   Display additional processing details.

--help or -h

   Display usage information.

A single output file named .table_definitions.json is produced, unless --individual or --format-odbc are used, both resulting in per-file output.

OpenVMS-style logical names can be used to specify the location of input and output files. For example, --input FILES.LIS or --output METADATA:. Note that logical names used in this way must exist in the system environment, as synergy.ini is not used.

By default the repository specified by the environment variables RPSMFIL and RPSTFIL is used, but you can select a specific repository by using the --repository option.

Examples:

  metadatatool sql --files CUSTOMER ORDER -output .\tables
  metadatatool sql --all --repository rps\rpsmain.ism rps\rpstext.ism
  metadatatool sql --input filelist.txt --output .\tables --individual

Generating ISAM Key Definition SDL Snippets (keysdl)

In keysdl mode, the utility reads a combination of ISAM and Synergy repository metadata and produces Synergy Data Language (SDL) files containing SDL key definition snippets that can be added to existing structure definitions.

metadatatool keysdl --input <file> [--repository <main-file> <text-file>]
                    [--output <directory>] [--nooverlayexpand] [--verbose] 
                    [--help]

Required arguments:

--input <file> or -i <file>

   The ISAM metadata file to read.

Optional arguments:

--repository <main-file> <text-file> or -r <main-file> <text-file>

   Specify the Synergy repository files to use.

--output <directory> or -o <directory>

   Specify where output files are created.

--nooverlayexpand

   Keep an exact overlay-field key match as one SDL segment instead of expanding it to the overlaid and subsequent fields.

--verbose or -v

   Display additional processing details.

--help or -h

   Display usage information.

An input file is required and specifies the ISAM metadata file to read. The file may contain either a single or array of FileMapping objects, as produced by the isamfdl or isamfile commands, or it can be a SIP MasterConfig.json file with an array of FileMapping objects in the IsamFileMapping.Mappings property.

By default, the repository specified by the environment variables RPSMFIL and RPSTFIL is used, but you can select a specific repository by using the --repository option.

OpenVMS-style logical names can be used to specify the location of input and output files. For example, --input FILES.JSON or --output METADATA:. Note that logical names must exist in the system environment, as synergy.ini is not used.

Adding ISAM Key Definition Snippets to SDL Schema Files (addkeys)

In addkeys mode, SDL key-definition snippets generated by keysdl are added to existing SDL schema files. You can specify a single schema containing all structures or a directory containing one str-*.sdl schema file per structure.

metadatatool addkeys --schemamode <single|individual> --schema <path>
                     [--snippetdir <directory>] [--clean] [--replace] 
                     [--backup] [--verbose] [--help]

Required arguments:

--schemamode <single|individual>

   Use single for one schema file containing all structures. Use individual for a directory containing one str-*.sdl schema file per structure.

--schema <path>

   The SDL schema file in single mode, or the schema directory in individual mode.

Optional arguments:

--snippetdir <directory>

   The directory containing str-*.sdl.key-snippet files. Defaults to the schema file's directory in single mode and to the schema directory in individual mode.

--clean

   Trim trailing whitespace, remove comment-only schema lines, and collapse repeated blank schema lines before adding key definitions.

--replace

   Replace existing KEY definitions for a structure instead of skipping that snippet.

--backup

   Before changing a schema file, copy its original content to a file with .backup appended to its name. Existing backup files are overwritten.

--verbose, -v

   Display additional processing details.

--help, -h

   Display usage information.

OpenVMS-style logical names can be used for the schema and snippet-directory paths. Updated schema files retain their established LF or CRLF line-ending convention.

Building a Package for Release

To package a new release of MetaDataTool:

  1. Update the VERSION file in the repository root if necessary.
  2. In Visual Studio,
    • Select Release mode.
    • Select Build > Rebuild Solution.
    • Select Build > Pack MetaDataTool.

Or run the release packaging script from the repository root:

build\Pack.ps1

Both of these methods create Synergex.MetaDataTool.<version>.nupkg in artifacts\nupkg. The package version is generated once per package from VERSION and the UTC build time in the format X.Y.YYDDD.HHMM. For example, VERSION of 1.0 can produce 1.0.26202.2005.

For an already-restored workspace, add -NoRestore to the script.

Before publishing a package to an internal feed, install it from artifacts\nupkg and run metadatatool version to confirm the package and command work as expected.