What Is Repository?

Repository is a system for defining data for use across Synergy/DE products. For example, if you define a repository structure, you can use that structure in your own ISAM files, in a Synergy DBL program, in xfServerPlus and xfNetLink, in xfODBC, in CodeGen for use with Harmony Core, and more.

Repository does not store user data, but it provides a way to define and organize data so that all elements of your application can understand it. You can think of a repository as a database schema (rather than a database itself). A repository stores data definitions in two ISAM files: a main file and a text file, with the default names of rpsmain.ism and rpstext.ism.

A repository is generally used at build time rather than runtime. For example, a repository is used when compiling a .dbl source file, when creating a Synergy Method Catalog for xfServerPlus, or when generating a system catalog for xfODBC. At runtime, the relevant data definitions from a repository are already built into the application, so there’s no further need for the repository files themselves. The exception to this is when a Synergy DBL program uses the Repository subroutine library (DD_* routines) to directly access a repository, but that goes beyond the scope of this article.

This article will cover the basics of creating a repository, defining data structures and files, and using the repository in a Synergy DBL program built in Visual Studio. The examples in this article have been tested with Visual Studio 2019 (version 16.4.1) and Synergy/DE 11.1.1a, but the information should be generally applicable to many versions of Visual Studio and Synergy. Some of the information is also relevant to Linux and other non-Windows platforms, but the article presupposes a Windows environment.

Repository in Visual Studio

If you’re developing an application in Visual Studio, you can use a Repository project to create and maintain a repository and to make it available to other Synergy projects in the same solution. This is our recommended approach if you want to incorporate a repository into a Visual Studio solution. While it is possible for Synergy projects to access a repository without using a Repository project, attempting to do so can cause numerous problems. Repository projects streamline the process and help reduce potential problems.

To create a Repository project, go to the “New Project” dialog in Visual Studio. In current versions of Visual Studio and SDI, “Synergy Repository” is its own project type in the project type drop-down list, making it easy to locate. But in any version, you should be able to find the template by searching all templates for “repository.”

When a Repository project is first created, it contains a single, empty source file: repository.scm.

This is a schema file, and it represents one of two distinct ways you can use a Repository project, either by building a repository from schema or by using an existing repository. If you go to the project properties (right-click on the project in Solution Explorer and click Properties), you’ll be able to choose between these two options with the “Use existing repository” check box:

If the option is cleared, the project will build the repository ISAM files from one or more schema files (similar to how other projects build executable programs from source files). If the option is checked, the project will instead use repository files that already exist.

If you use an existing repository, you can build and maintain it either from schema files or through the Repository UI. Both of these options are also possible if you’re building the repository in Visual Studio, although some extra work is required if you want to use the UI. In this article, we’ll focus on two possibilities:

• Using an existing repository and using the Repository application to modify it.
• Building a new repository and using schema files to modify it.

Building a Repository outside Visual Studio with the Repository Application

To use an existing repository, we first need to create it. Start by configuring a Command Prompt window for Synergy (e.g., run “%SYNERGYDE64%\dbl\dblvars64”, including the quotation marks). Then navigate to the location where you want to create the repository and run the following:

set RPSMFIL=%cd%\rpsmain.ism
set RPSTFIL=%cd%\rpstext.ism
dbr RPS:rps

This will set the RPSMFIL and RPSTFIL environment variables to point to (nonexistent) ISAM files in the current directory, and then start the Repository application. (Alternatively, if you use the default filenames and have only one repository, you can specify the directory for the repository files with RPSDAT.) Note that we don’t recommend setting these environment variables directly in Visual Studio; the Repository project does that automatically so you don’t have to worry about it. But if you’re launching tools from the command line, it makes sense to set the variables to point to the correct repository because they can be used by other Synergy programs and utilities launched from the same Command Prompt window.

When we launch Repository, it appears as an empty window with the Modify menu pulled down:

The Repository functions you’ll use most often are on the Modify menu, but we can’t use any of them until we create the repository files, so let’s do that first. Open the Utilities menu and select Create New Repository. Because we set RPSMFIL and RPSTFIL before starting Repository, you’ll see a window already populated with the desired paths to the ISAM files:

When you click OK, you’ll see a message telling you that the files were created successfully, and then you’ll return to the main screen. Now the repository exists, but it doesn’t contain anything. To change this, select Modify > Structures.

Structure definitions are at the heart of Repository. Other element definitions, such as templates, formats, and enumerations, make it easier to define structures; and file definitions enable you to store and retrieve data based on structures. A full explanation of what a structure is and how it works is beyond the scope of this article. But to summarize, a structure is a custom data type consisting of one or more fields (typically of standard Synergy data types like alphas, decimals, or integers). It can also contain one or more keys, which can be used to index data when it’s stored in an ISAM file.

In relational database terms, an ISAM file is like a database table, a structure is like the definition for the table, the fields are like the columns of the table, and data records stored in the file are like rows. In fact, Repository lets you define relationships between structures for use with xfODBC, allowing ISAM files to mimic a relational database.

But for now, we’ll just define a single, simple structure. Click the Add button and type a name and description for the structure. Select “DBL ISAM” for the file type and “None” for the tag type.

When you’re done entering the information, click the Attributes button. This will create the structure and take you directly to the structure attributes screen, with the Attributes menu open:

I alluded to the functionality of fields, keys, and relations before; the other options on this menu are formats, tags, and aliases. Formats define standard ways to display certain fields. Formats can be defined at the structure level from this menu, or at the repository-wide level back in the Modify menu on the first screen. Tags are an advanced feature that uniquely distinguish different structures, and aliases are alternate names for the structure. For now, we’ll just look at fields.

As with the other windows we’ve seen so far, the list is blank because we haven’t defined any fields yet. Click Add to create a new field.

There’s a lot of information you could enter in this window, across multiple tabs, but the minimum needed to create a field definition are the field name, type, and size (in bytes). The “Prec” field enables you to specify the precision if you’re defining an implied-decimal field, and the “Dim” field lets you define an array. For information about the other fields in this window, see the Synergy/DE documentation for Defining a new field.

When you’re finished defining one field, you can add another, and repeat the process until the structure contains all the fields you need. Here, I defined one integer field and one alpha field:

This isn’t a particularly useful structure at this point, but it’s good enough for demonstration purposes. There’s just one more thing to do before the structure is finished: add a key.

It isn’t always necessary to define keys in Repository. For example, if you’re only using the structure in a Synergy DBL program, as long as the keys in the file are set up correctly in relation to the data structure, everything should work fine. But defining keys in Repository is good practice and becomes very important if you want to use xfODBC, CodeGen, and especially Harmony Core.

To define a key, close the Field Definitions window and then select Attributes > Keys. From the Key Definitions windows, click Add to create a new key for the structure.

Again, there’s a lot of information you could enter in this window. See the documentation for Defining keys for details. I’ve added a name and description for the key, and said that it’s an access key (meaning that it’s a true key in the data file). The “Sort order” and “Null key” values are auto populated, but can be modified as necessary. The essential part of the key definition is the segment list. In this key, I’ve defined only one segment. The segment type is ‘F’ (field), and it points to the field named “INTKEY”. I could define additional segments (up to 8), but I’ll keep it simple.

Click OK to finish creating the key. When you’re done adding keys, close the Key Definitions window, and then select General > Exit to return to the Structure Definitions windows. At the prompt, click Yes to save changes to the structure, and then select General > Exit a second time to return to the main menu.

Let’s do one more thing before leaving Repository: define a file. Once again, this isn’t absolutely necessary for all use cases, but it’s a good idea and may be essential depending on the Synergy products you want to use. To define a file, select Modify > Files, and then click Add.

There are a number of options here; see the documentation for Defining files for details. Enter the filename and specify the file type, a description, and the name of the file on disk (in the “Open filename” field). Then click the Assign button and click Add.

This lets you assign one or more structures to the file. Type in the name of the structure, and click OK. Close the Assigned Structures window and verify that the structure has been assigned to the file (check the Structure field below “Open filename”):

Click OK to add the file definition. Then exit out of the various screens until you close Repository.

Back in Visual Studio, in the Repository project’s properties, check the “Use existing repository” box. Then type in the path to the rpsmain and rpstext files for the repository you just created:

Save the properties and build the project. The Repository project should now be ready, so that any other Synergy projects in the solution can access the external repository files. To test this, open Repository again, this time from within Visual Studio, by selecting Tools > Synergy/DE Repository.

Go to Modify > Structures, where you should see the structure you defined:

This demonstrates that Visual Studio is able to access the correct repository based on the paths in the Repository project.

Building a Repository Inside Visual Studio with a Schema File

We’ve seen how to access an existing Repository in a Visual Studio Repository project. But the default behavior of that project type is to build a repository from one or more schema files. To demonstrate this, let’s export the schema from the repository we created.

In Repository, go to the main screen and select Utilities > Generate Repository Schema.

In the Generate Repository Schema window, the “Repository main file” and “Repository text file” values should already be populated. For the “Schema file,” navigate to the location of the Repository project and select the repository.scm file. Finally, choose the “All” option to export everything in the repository.

Click OK, and click Yes when asked whether you want to delete the existing schema file. Then exit Repository.

If you open repository.scm in the Visual Studio project, you’ll see that it’s been modified:

;  SYNERGY DATA LANGUAGE OUTPUT
…

Structure TESTSTRUCT   DBL ISAM
   Description "Test Structure"

Field INTKEY   Type INTEGER   Size 8
   Description "Integer-type field used as a key"

Field AFIELD   Type ALPHA   Size 20
   Description "Alpha field 1"

Key KEY1   ACCESS   Order ASCENDING   Dups NO
   Description "First (and only) access key"
   Segment FIELD   INTKEY

File TESTFILE1   DBL ISAM   "testfile.ism"
   Description "File for TESTSTRUCT"
   Assign TESTSTRUCT

This code is written in Synergy Data Language. This language — and the concept of schema files — far predates the introduction of Visual Studio Repository projects. But schema files are a natural fit for Repository projects, since they mirror the source code model used for most Visual Studio projects. Schema files provide a human-readable view of a repository’s contents, and they make it easier to transfer repositories between systems and include them in source control, because they’re plain text files rather than binary ISAM files.

Schema files also make it easy to duplicate and modify existing repository elements. To demonstrate this, select everything in TESTSTRUCT from the Structure keyword to just before the File keyword. Copy this text and paste it just before the file definition. Then change the name of the pasted structure to TESTSTRUCT2, and save the file

…
Key KEY1   ACCESS   Order ASCENDING   Dups NO
   Description "First (and only) access key"
   Segment FIELD   INTKEY

Structure TESTSTRUCT2   DBL ISAM
   Description "Test Structure"

Field INTKEY   Type INTEGER   Size 8
   Description "Integer-type field used as a key"

Field AFIELD   Type ALPHA   Size 20
   Description "Alpha field 1"

Key KEY1   ACCESS   Order ASCENDING   Dups NO
   Description "First (and only) access key"
   Segment FIELD   INTKEY

File TESTFILE1   DBL ISAM   "testfile.ism"
…

You’ve just created a new structure that’s identical to the first one. But this structure exists only in repository.scm, not in your actual repository. You could manually import the modified schema using Repository’s Load Repository Schema utility (or rpsutl from the command line), but since we’re interested in how Visual Studio builds Repository projects, we’ll want to stay in Visual Studio for this step. Go to the Repository project’s properties page and uncheck the “Use existing repository” checkbox. Then change the values for “RPS Main File” and “RPS Text File” back to “rpsmain” and “rpstext,” respectively, and rebuild the project.

Open Repository from Visual Studio again (Tools > Synergy/DE Repository) and look at the structures; you should see the new structure you defined by copying and pasting in the schema file.

When you built the project, Visual Studio generated new Repository ISAM files from the schema file and redirected the Repository utility to point to the new files. It’s possible to modify the repository from Repository and still build from a schema file in Visual Studio, but to do that, you need to make sure to export the schema each time you’re done making changes in Repository. Otherwise, the schema will remain unchanged, and all the changes you made in Repository will be overwritten when Visual Studio rebuilds from the schema.

When the Repository project type was introduced, it was limited to a single schema file, but more recent versions of SDI are able to handle multiple files. You may have noticed when exporting the schema that you could choose “Specific” instead of “All”; this allows you to export individual format, enumeration, template, structure, or file definitions. Using individual schema files for individual elements can have some benefits, such as making changes to a repository easier to track and manage in source control and making schema files easier to read.

To add an additional schema file to a Repository project, right-click on the project in Solution Explorer and select Add > Existing Item. Navigate to the file(s) you want to add.

As of this writing, there is no defined schema file extension, which means that you can’t filter by file type and you can’t create an empty schema file with Add > New Item. If you want to add an empty schema file to a project, just create a new text file outside of Visual Studio and add it with the Add Existing Item dialog. After you add a new schema file, make sure that it has a build type of Compile:

Using a Repository with Other Visual Studio Projects

Now that we have a project that builds a repository, we can refer to it from other Visual Studio projects in our solution. All Synergy project types are able to add a reference to a Repository project, including Traditional and .NET projects. For this example, I’ll use a Traditional Application project type:

In order for a Synergy project to use the repository from a Repository project, it needs to have a reference to that project. In Solution Explorer, right-click on References under the Synergy project, and select Add Reference:

Select the Repository project from the Projects pane, and click OK:

Now you can write some code in the new project that references the Repository. For example:

main
.include "teststruct" repository, record="testrec1"
.include "teststruct2" repository, structure="teststruct2"

record myrec
    testrec2, teststruct2

proc
    testrec1.afield = "Hello world!"
    myrec.testrec2.afield = testrec1.afield

endmain

This code demonstrates two different .INCLUDE directives that refer to the repository. The first one includes a Repository structure as a local record that can be used directly (testrec1). The second one includes a Repository structure as a structure, which can then be used as the data type for a structfield in a record (myrec.testrec2). Run your code in the debugger to see this in action:

Conclusion

In this article, we’ve seen what Repository is, how to create a repository and modify it using the Repository application, how to create a Visual Studio Repository project that builds a repository from a schema file, how to use an existing repository in a Visual Studio project, and how to add a reference to a Repository project from other Synergy projects in Visual Studio.

This is only an introduction to the many things you can do with Repository. I’d recommend referring to the Repository User’s Guide for more information about what the Repository application itself can do. Also see the documentation for Using Synergy/DE repositories in Visual Studio. For information about using Repository from other products such as xfServerPlus, xfODBC, CodeGen, and Harmony Core, please see the documentation for those products.

I hope this information has been helpful, and that you’ll be able to use it to build better applications.