RepositoryAPI 6.1.4

RepositoryAPI

RepositoryAPI is a Synergy .NET class library for reading metadata from a Synergy Repository database. It wraps the Synergy/DE ddlib API in an object model rooted at CodeGen.RepositoryAPI.Repository.

Use it to inspect repository structures, fields, files, keys, templates, formats, enumerations, relations, and tags. The library also derives metadata that is useful to CodeGen consumers, such as language-specific data types and names suitable for SQL and xfODBC.

This is a metadata reader. Although a number of model properties have public setters, the library contains no API that writes the changed objects back to the Repository. Treat the loaded objects as an in-memory snapshot.

Contents

• Project and runtime requirements
• Quick start
• Repository lifecycle
• Metadata object graph
• Repository API
• Metadata models
• Collections and loading behavior
• CodeGen extensions and data mappings
• Enums
• Errors and lookup behavior
• JSON considerations

Project and runtime requirements

The project targets .NET Standard 2.0 and its public types are in the CodeGen.RepositoryAPI namespace. It depends on these Synergy/DE components:

• Synergex.SynergyDE.ddlib to access Repository metadata;
• Synergex.SynergyDE.synrnt for the Synergy runtime;
• Synergex.SynergyDE.synxml when using custom data mappings; and
• Newtonsoft.Json for serialization attributes.

The default project at DotNetCore/RepositoryAPI/RepositoryAPI.synproj compiles the Synergy source held in the sibling CodeGen/RepositoryAPI directory. A consuming application must be able to locate the Synergy runtime and either:

• have a default Repository configured for dd_init; or
• supply the Repository main and text file paths when opening the API.

Quick start

This C# example opens a specific Repository, retrieves one structure, and walks its field and key metadata.

using System;
using System.Linq;
using CodeGen.RepositoryAPI;

var mainFile = @"C:\SynergyDE\rps\rpsmain.ism";
var textFile = @"C:\SynergyDE\rps\rpstext.ism";

using (var repository = new Repository(mainFile, textFile, true))
{
    // `true` makes RpsField.Name use the Repository alternate name when set.
    var customer = repository.GetStructure("CUSTOMER");

    Console.WriteLine($"{customer.Name}: {customer.Length} bytes");

    foreach (var field in customer.Fields)
    {
        Console.WriteLine(
            $"{field.SequenceNumber,2} {field.Name,-30} " +
            $"{field.DataType}/{field.DataTypeSubclass} " +
            $"offset={field.StartPosition} size={field.Size}");
    }

    var primaryKey = customer.Keys.FirstOrDefault(k => k.SequenceNumber == 1);
    if (primaryKey != null)
    {
        Console.WriteLine($"Key: {primaryKey.Name}");
        foreach (var segment in primaryKey.Segments)
            Console.WriteLine($"  {segment.SegmentType}: {segment.Field}");
    }
}

To inspect every structure instead, enumerate repository.Structures. To avoid loading the complete Repository when only one item is needed, prefer GetStructure, GetFile, or GetTemplate.

Repository lifecycle

Repository implements IDisposable. Dispose it when finished so that the underlying ddlib session is closed and its cached collections are released.

After opening, these properties describe the session:

• MainFile and TextFile — resolved Repository file specifications.
• LastModified — Repository modification timestamp (YYYYMMDDHHMMSS).
• LastStructureAddDelete — timestamp for the last structure add/delete.
• Version — Repository version string.

Name handling and alternate names

Repository names supplied to lookups are trimmed and generally normalized to uppercase by the model loaders. Fields retain both the actual Repository name and the alternate name:

• With useAlternateFieldNames: false (the default), RpsField.Name is the actual Repository name.
• With useAlternateFieldNames: true, RpsField.Name is the alternate name when one is defined; otherwise it remains the actual name.
• RpsField.OriginalName always records the actual Repository name initially.

Metadata object graph

Repository
├── Structures : RpsStructureCollection
│   └── RpsStructure
│       ├── Fields    : RpsFieldCollection
│       ├── Keys      : RpsKeyCollection
│       │   └── RpsKey.Segments : RpsKeySegmentCollection
│       ├── Files     : RpsFileCollection
│       ├── Tags      : RpsTagCollection
│       ├── Formats   : RpsFormatCollection
│       └── Relations : RpsRelationCollection
├── Files        : RpsFileCollection
│   └── RpsFile.Structures / Keys
├── Templates    : RpsTemplateCollection
├── Formats      : RpsFormatCollection       (global formats)
├── DateFormats  : RpsFormatCollection       (predefined date formats)
├── TimeFormats  : RpsFormatCollection       (predefined time formats)
└── Enumerations : RpsEnumCollection
    └── RpsEnum.Members : RpsEnumMemberCollection

The graph intentionally contains navigation in both directions between files and structures. JSON-related navigation properties are ignored to prevent cycles; see JSON considerations.

Repository API

The main entry point exposes the following cached collections and targeted loaders.

Metadata models

The following types carry the loaded Repository metadata. Collections are List<T> derivatives, while the individual metadata objects expose direct attributes and CodeGen-derived values.

Structures and groups

RpsStructure is the central metadata type. A normally loaded structure includes its fields, keys, associated files, tags, local formats, and relations.

An explicit group can be addressed as STRUCTURE.GROUP. The loader validates that the requested field is an explicit group, promotes its member fields into a synthetic RpsStructure, and sets IsFake to true. The synthetic structure has no Repository files, keys, tags, formats, or relations.

An implicit group remains a field with GroupStructure naming the source structure and GroupFields containing fields loaded from that structure.

Fields

RpsField describes a physical Repository field plus UI, validation, and CodeGen information. The field object is loaded with the structure, including its extended text records, allowed values, selection values, numeric ranges, group members, and enumeration reference where applicable.

DefaultAuotmatic is spelled that way in the public API. It indicates whether the configured default action is applied automatically.

RpsFieldCollection inherits List<RpsField> and provides these in-place filters:

• RemoveOverlays()
• RemoveExcludedByLanguage()
• RemoveExcludedByToolkit()
• RemoveExcludedByReportWriter()
• RemoveExcludedByWeb()

Files

RpsFile describes a Repository file definition and its assigned structures.

StructureNames and OdbcTableNames are parallel lists in Repository order. When an assigned structure has no ODBC table name, its structure name is used in OdbcTableNames. Keys is populated from the file's first assigned structure, when one exists.

Keys and segments

RpsKey captures a structure key and has a Segments collection. Its main properties are:

• identity and shape: SequenceNumber, Name, KeyType, Size, Description, Segments;
• ordering and duplicates: SortOrder, Duplicates, InsertDuplicates;
• update and null behavior: Modifiable, NullKey, NullKeyValue, KeyOfReference;
• storage/visibility: Density, CompressIndex, CompressData, CompressKey, OdbcAccessible; and
• raw interop: ddlib_k_info.

Each RpsKeySegment exposes SegmentType, Position, Length, Field, Structure, LiteralValue, DataType, DataTypeName, and Order. Field and Structure apply to external segments; LiteralValue applies to literal segments. For alpha literal segments, ~ is returned as a space and the length is calculated from the resulting literal.

Templates

RpsTemplate represents a reusable Repository field template. It mirrors the field metadata that a template can supply: data type and subclass, size and precision, array dimensions, format and screen attributes, input behavior, allow/selection lists, validation ranges, prompt/help text, methods, and enumeration configuration.

Important template-specific properties are TemplateNumber, Name, ParentTemplate, Description, LongDescription, UserFieldType, DataType, DataTypeCode, DataTypeSubclass, Size, Precision, ArrayDimension, NativeSize, EnumName, and CoercedType.

It also has the CodeGen type and naming properties shared with fields: BaseName, OriginalName, OriginalNameModified, TypeCode, TypeName, CsType, VbType, SnType, SqlType, TsType, OcType, their default value counterparts, MappedField, MappingFunction, UnmappingFunction, AutoIncrement, OdbcName, and SqlName.

Formats, tags, and relations

Enumerations

RpsEnum exposes Name, Description, LongDescription, and lazy-loaded Members. Each RpsEnumMember exposes EnumName, Name, ExplicitValue, and ImplicitValue.

When an enumeration member has no explicit value, the collection calculates its implicit value: the first member is 0; each later member increments the previous implicit value. ExplicitValue may therefore be blank while ImplicitValue is populated.

Collections and loading behavior

All Rps*Collection types inherit List<T> and are ordinary mutable lists. They are snapshots rather than live Repository queries.

Root collection properties are cached for the lifetime of the open Repository instance. Open(...) and Dispose() clear those cached root collections. For large Repositories, use targeted getters when possible and avoid touching root collections merely to test for one name.

CodeGen extensions and data mappings

In addition to direct Repository attributes, fields and templates calculate data types for C#, Visual Basic, Synergy .NET, SQL, Objective-C, and TypeScript. The computed values appear in properties such as CsType, SqlType, SnType, TsType, and their default-value counterparts.

Repository text directives

The loader checks a structure or field's user text first, then its long description, for these directives:

Each directive requiring a value must end with ;. An incomplete or malformed mapping directive raises an RpsStructureException or RpsFieldException.

Custom language and SQL mappings

DataMappings creates a DataMapping instance for SQL, C#, Visual Basic, Objective-C, Synergy .NET, and TypeScript. The default SQL mapping is selected with CODEGEN_DATABASE_TYPE:

• sqlserver (the default)
• mysql
• postgresql

Set CODEGEN_DATAMAPPING_FILE before any fields or templates are loaded to override defaults from an XML file. The file root must be DataMappings; it may contain any of the sections SQL, CSharp, VisualBasic, ObjectiveC, SynergyDotNet, and TypeScript.

<?xml version="1.0"?>
<DataMappings>
  <CSharp>
    <Alpha>string</Alpha>
    <Integer8>long</Integer8>
  </CSharp>
  <SQL>
    <Alpha>VARCHAR(l)</Alpha>
    <ImpliedDecimal>DECIMAL(l,p)</ImpliedDecimal>
  </SQL>
</DataMappings>

Supported individual mappings include Alpha, AlphaBinary, UserAlpha, UserNumeric, UserDate, UserTimeStamp, the date/time subtypes (including nullable variants), ImpliedDecimal, SmallDecimal, LargeDecimal, VeryLargeDecimal, Integer1, Integer2, Integer4, Integer8, Boolean, Enum, Binary, StructField, AutoSequence, and AutoTime.

In mapping strings, (l) is replaced with the field length; (l,p) and (l.p) are replaced with field length and precision. The complete example is available at CodeGen/RepositoryAPI/DataMappingsExample.xml.

Enums

The API exposes strongly typed enums rather than raw ddlib codes. The most commonly used enums are:

RpsKeySegmentType distinguishes field, literal, external, and record-number segments. RpsKeySegmentDataType distinguishes alpha/no-case alpha, decimal, signed/unsigned integer, automatic sequence, and created/updated timestamp segments. Use the enum properties rather than assuming raw ddlib numeric values.

Errors and lookup behavior

All library-specific exceptions inherit from RpsException, which itself inherits ApplicationException.

Targeted getters load an object and report failures by throwing one of these exceptions; they do not return null for a missing Repository object. Catch the most specific exception that your application can handle.

JSON considerations

The metadata classes use Newtonsoft.Json attributes. Enum-valued properties are decorated to serialize as names rather than numeric values. Navigation properties that can create cycles are marked JsonIgnore, including:

• RpsStructure.Files, RpsStructure.FirstFile, and RpsStructure.IsFake;
• RpsFile.Keys and RpsFile.Structures.

When serializing a large Repository graph, choose a bounded projection (for example, a structure and selected fields) rather than serializing every root collection. That keeps output manageable and avoids loading unnecessary metadata.