Synergex.MetaDataTool 1.0.26267.2049

Synergex MetaDataTool

MetaDataTool is a command-line utility to generate various kinds of metadata useful when working with the Streaming Integration Platform, Gantry SQL, 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 can be downloaded and installed using the .NET CLI. Install MetaDataTool like this:

C:\> dotnet tool install --global Synergex.MetaDataTool
You can invoke the tool using the following command: MetaDataTool
Tool 'synergex.metadatatool' (version '1.0.26203.2352') was successfully installed.

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

Uninstall MetaDataTool like this:

C:\> dotnet tool uninstall --global Synergex.MetaDataTool
Tool 'synergex.metadatatool' (version '1.0.26203.2352') was successfully uninstalled.

Installed Version and Updates

To show the currently installed version:

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. You will see a message if a newer version is available. To see help about the update capabilities:

C:\> metadatatool update --help

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

  --on        Enable weekly automatic update checks.
  --off       Disable weekly automatic update checks.
  --status    Show whether automatic update checks are enabled.
  --help, -h  Display this usage information.

Without an argument, checks for a newer version immediately.

To disable or re-enable automatic update checks:

C:\> metadatatool update --off
Automatic update checks disabled.

C:\> metadatatool update --on
Automatic update checks enabled.

C:\> metadatatool update --status
Automatic update checks enabled.

To check for updates immediately, and to download and install the latest version:

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).

To view help on these modes, run:

C:\> metadatatool help

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

Usage: metadatatool <mode> [<arguments>]

Modes:

   addkeys        Adds ISAM key definition SDL snippets to SDL schema files.
   help           Show this 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.

To uninstall: dotnet tool uninstall --global Synergex.MetaDataTool

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

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

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.

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

isamfdl Mode

In this mode the utility reads one or more OpenVMS FDL files and produces ISAM metadata files. To see help for this function, run:

C:\> metadatatool isamfdl --help

Usage: 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>, -o <directory>
     Optionally specify where output files are created.

  --nokeytruncwarn
     Suppress key name trunctation warnings.

  --norelwarn
     Suppress relative file warnings.

  --verbose, -v
      Display more messages to the console.

  --help, -h
      Display this 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 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 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, for example:

# Input file for producing ISAM Metadata from FDL files

FDL:CUSTOMER.FDL
FDL:INVENTORY.FDL

And use a command like this:

metadatatool isamfdl --input FDLFILES.LIS

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

isamfile Mode

In this mode the utility reads one or more SDMS ISAM files and produces ISAM metadata files. To see help for this function, run:

C:\> metadatatool isamfile --help

Usage: 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>, -o <directory>
     Optionally specify where output files are created.

  --verbose, -v
      Display more messages to the console.

  --help, -h
      Display this 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 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 file name 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, for example:

# Input file for producing ISAM Metadata from ISAM files

DAT:CUSTOMER.ISM
DAT:INVENTORY.ISM

And use a command like this:

metadatatool isamfdl --input DATAFILES.LIS

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

sql Mode

In this mode the utility reads one or more FILE definitions from a Synergy repository and produces SQL metadata files. To see help for this function, run:

C:\> metadatatool sql --help

Usage: 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 (pick one):

  --all, -a
      Process all file repository definitions.

  --files <file1> [<file2>...], -f <file1> [<file2>...]
      Process these specific repository file definitions.

  --input <file>, -i <file>  Read file definition names from a list file
      Process repository file defininitions listed in an inmput list file.

Optional arguments:

  --output <directory>, -o <directory>
      Optionally specify where output files are created.

  --individual
      Produce an outout file for each file definition.

  --format-odbc
      Output format: xfodbc (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
      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>, -r <main-file> <text-file>
      Specify the Synergy repository files to use.

  --verbose, -v
      Display additional processing details.

  --help, -h
      Display this 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 because
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

keysdl Mode

In this 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. To see help for this function, run:

C:\> metadatatool keysdl --help

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

Required arguments:

  --input <file>, -i <file>
      The ISAM metadata file to read.

Optional arguments:

  --repository <main-file> <text-file>, -r <main-file> <text-file>
      Specify the Synergy repository files to use.

  --output <directory>, -o <directory>
      Optionally 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, -v
      Display additional processing details.

  --help, -h
      Display this 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.

addkeys Mode

This mode adds SDL key-definition snippets generated by keysdl to existing SDL schema files. It supports a single schema containing all structures or a directory containing one str-*.sdl schema file per structure.

C:\> metadatatool addkeys --help

Usage: 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, or 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>
      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 this 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:

• Update the VERSION file in the repository root if necessary.

• Then in Visual Studio:

  • Select Release mode
  • Build > Rebuild Solution
  • 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.

License

This project is licensed under the BSD 2-Clause License. See LICENSE.