Developing a traditional Synergy application
This topic includes the following sections:
Synergy DBL Integration for Visual Studio (SDI) includes support for traditional Synergy development. This means you can use Visual Studio to develop traditional Synergy libraries and executables for Windows, Linux, and OpenVMS desktop and server systems.
In Visual Studio, builds take the place of the compiling and linking required when developing outside of Visual Studio. When you build a traditional Synergy project in Visual Studio, the Synergy compiler is used automatically behind the scenes, and when you build a Visual Studio solution with traditional Synergy projects, the Synergy compiler and linker are used behind the scenes.
Note the following:
- Strong prototyping takes place automatically at build time for all Synergy projects in Visual Studio. Consequently, the SYNIMPDIR and SYNEXPDIR environment variables are ignored by the traditional Synergy build system in Visual Studio, and you cannot set the ‑qimpdir compiler option or the ‑expdir option for dblproto. These settings are reserved for internal use by the build system.
- For Linux, you can develop and build your code with Visual Studio, but because of path differences between Windows and Linux, you will not be able to run and debug your program on Windows. Instead, set the output path on the Build page of Project Designer to a network share on a Linux machine. Then when you build the project, built files will be saved to the Linux machine where you can run and debug them. Remember that Linux is case sensitive, so when you define environment variables or specify paths or filenames, make sure the case is correct.
- For OpenVMS, you can develop and build with Visual Studio on Windows, and you may also be able to run and debug your code on Windows, but you will not be able to deploy files built in Visual Studio. For full debugging and final deployable builds, you will need to move the code you developed in Visual Studio to an OpenVMS development machine. Additionally, Visual Studio projects for an OpenVMS application may need to reference the VmsCompatibility library (see Reference projects and files as necessary below).
Development steps for traditional Synergy
The following steps outline the process for creating projects for a traditional Synergy application. Most of the following steps are for Visual Studio procedures, so see Visual Studio documentation for more information.
||Set options for your Visual Studio environment. For example, you can control the behavior of the Visual Studio code editor (indentation, tab size, etc.) and the way IntelliSense works for Synergy DBL files. See Options for Synergy/DE projects for more information.
||Create a solution, and create projects for the mainline program and libraries for your application. Use the following Synergy project templates in Visual Studio to create a project for each program and library in your application, and optionally create a project for each repository used by your application. Use these templates for Windows, Linux, and OpenVMS development (e.g., use the Executable Library template for code that will become a shared library on OpenVMS). See Synergy/DE project templates for more information.
- Traditional Application (DBR). Use this to create a traditional Synergy program with a single .dbr file.
- Multiple Mainline (DBR). Use this to create a Synergy project that results in multiple traditional Synergy mainline programs — i.e., an application that is distributed as a number of DBRs that typically reference common libraries.
- Executable Library (ELB). Use this to create a collection of traditional Synergy routines that can be used in other traditional Synergy ELBs and DBRs.
- Object Library (OLB). Use this to create a traditional Synergy object library (OLB) that can be used in other traditional Synergy ELB and DBR projects.
- Synergy/DE Repository. Use this to create a repository project. Repository projects replace RPSMFIL and RPSTFIL settings and enable the build system to know when a project should be rebuilt due to a repository change (i.e., a change to a schema file). You are not required to create projects for repositories, but it is generally recommended. See Using Synergy/DE repositories in Visual Studio for more information.
For example, to create a traditional Synergy program with a single .dbr file, select File > New Project. Then select Synergy/DE from the Installed Templates area of the New Project dialog, and select “Traditional Application (DBR)” from the list of project types. You’ll then need to set a few options for the project (name, location, and so forth) in the New Project dialog.
See Synergy projects, solutions, and files for more information, and note the following:
- If no solution is open in the current instance of Visual Studio, creating a project will also create a solution to contain the project. To add the project to an existing solution, open the solution in Visual Studio before you create the project (e.g., before you select File > New Project from the menu). To start with a blank solution, do the following before you create projects for an application: select File > New Project from the Visual Studio menu, and then in the New Project dialog, select Installed > Other Project Types > Visual Studio Solutions > Blank Solution.
- When creating a library for shared code, use an ELB rather than an OLB. (An OLB project should be referenced by only one project in the solution. Referencing an OLB project from multiple projects causes the OLB code to be compiled into multiple files for the application.)
- You can build an ELB directly from an OLB. To do this, open the ELB project and add a reference to the OLB project. Then remove any source files from the ELB project and build the project.
- If your application uses files generated by gennet40, create a separate ELB or OLB project for these files, add the source files and the .inc file generated by gennet40 to this project, and reference this project from your mainline (DBR) project (see Reference projects and files as necessary below). Then set the “Concat source files (-qconcat)” option on the Compile page of Project Designer before building the project (see Set project properties, and set up build configurations below).
||Build out and configure your projects by adding code and other items, referencing other projects and files as necessary, setting environment variables, setting project properties, and setting up build configurations.
Add code and other items to your project
You can add a new or existing item, such as a code file, by right-clicking the project node in Solution Explorer and selecting one of the following from the context menu: Add > New Item, Add > Existing Item, Add > Reference Existing Item. (The Add > Existing Item command copies the file into the Visual Studio project. Add > Reference Existing Item adds a relative-path reference to the item.) Note the following:
- By default, a file with the .dbl or .dbc extension is treated as a compilable Synergy file, and a file with the .def or .rec extension is treated as a Synergy content (non-compilable) file. You can instruct Visual Studio to treat files with other extensions as compilable or non-compilable by specifying those extensions in the IntelliSense dialog box for Synergy. See IntelliSense, text editor options for more information.
- Included files (files specified in .INCLUDE statements) must be content files. See File types and build actions for more information.
- You can add a Synergy data file (e.g., a Synergy ISAM file) by using Add > Existing Item or Add > Reference Existing Item.
- SDI comes with a collection of snippets to make Synergy coding easier. For information on these snippets, open the Code Snippet Manager (Tools > Code Snippet Manager), select Synergy as the language, and expand the Snippets > Synergy branch of the Location pane. If you select a snippet node in that branch, a description of the snippet and the snippet shortcut will display in the pane.
- The RUNTIME_TARGET define is set at compile time to the runtime compatibility setting for a program. This enables you to programmatically exclude runtime features that are not available in the version targeted by the project.
Reference projects and files as necessary
References enable a project to use other libraries, repositories, and external files. (Referencing a library is equivalent to linking to a library — i.e., adding a library to a dblink command — when developing outside of Visual Studio.) You can add a reference by right-clicking the Reference node in Solution Explorer and selecting Add Reference from the context menu. Note the following:
- If the project uses a repository project, you must add a reference to the repository project. (RPSMFIL and RPSTFIL settings do not work for repository projects.) For more information, see Using Synergy/DE repositories in Visual Studio.
- To reference an ELB or OLB, reference its Visual Studio project when possible, not the ELB or OLB file. (If you reference an ELB or OLB file rather than its project, there will be no IntelliSense or prototypes for that file.) If you reference an ELB project, make sure you set the output path correctly for the ELB. See Referencing ELBs and OLBs for more information, and note that the Synergy tab of the Reference Manager dialog enables you to easily add a reference to an ELB or OLB in a location specified by an environment variable.
- Circular references (two libraries that reference each other) are not supported by Visual Studio. You can work around this by creating a prototype-only reference. See Creating a prototype-only reference for more information.
- Prototyping enables the compiler to perform full parameter checking, and it enables IntelliSense to supply parameter information correctly. To enable prototyping to work correctly for multi-project solutions, all references must be resolved. To ensure that all routines are correctly validated against prototypes, select the "Require prototype usage (‑qreqproto)" option on the Compile page of Project Designer.
- If code for OpenVMS includes DBL$ or SYS$ routines, the Visual Studio project with that code must reference the VmsCompatibility library (github.com/Synergex/VmsCompatibility) to be able to run on Windows. This library enables IntelliSense to work for those routines, it will enable the code to be compiled, and it may enable the code to run on Windows. You may also be able to do some preliminary debugging on Windows. Some routines in this library are stubs, however, so if your code includes one of these routines, you will not be able to run or debug the program on Windows.
Set environment variables
Set environment variables needed for developing and running the application. See Environment variables and Visual Studio development for information on where you can set environment variables, when they are used, and precedence for different locations.
Set project properties, and set up build configurations
Use Project Designer to configure project properties, and set up sets of build and debug settings so that your projects and solution can be built and debugged in different ways. See Common project settings below for information on commonly used project properties, or see Synergy/DE project properties for details on these settings. Note the following:
||Build the solution or an individual project by using a build or rebuild command in Visual Studio. For example, you can rebuild the entire solution by selecting Build > Rebuild Solution from the Visual Studio menu. Note the following:
- Make sure the configuration and platform settings on the Visual Studio toolbar are correct for the build. See Configurations, platforms, and profiles for more information.
- To build or rebuild (or clean) a project without affecting other projects in the solution (even referenced projects), use a Project Only menu entry — e.g., Build > Project Only > Rebuild Only Project. See SDI features for information on these menu entries.
The Visual Studio Error List (View > Error) will list any errors encountered in the build. If the Error List in Visual Studio displays a lot of errors, keep in mind that you can filter this list so that it is limited to the current project (this can be very helpful), the current document in the editor, or all documents open in the editor. You can also use the search feature for the Error List to find specific words or phrases in the list, and you can filter out errors, warnings, or messages. To clear only Synergy-related errors and warnings from the Error List, select Tools > Clear Error List from the Visual Studio menu.
- Make sure configuration, platform, and profile settings are correct for the debugging session. For a .NET Core or .NET Standard project, the active profile determines which debug settings are used. For all other project types, the active configuration/platform combination determines which debug settings are used. For all project types, the active configuration/platform combination determines which build is debugged. See Configurations, platforms, and profiles for more information.
- For a Linux application, you'll need to run the application on a Linux machine and then use remote debugging to debug the application from Visual Studio or use standard traditional Synergy debugging on the Linux machine.
- For an OpenVMS application, you may be able to do preliminary debugging using Visual Studio with files built on Windows. But for full debugging you'll need to run the application on an OpenVMS machine and then either use remote debugging to debug the application from Visual Studio, or use standard traditional Synergy debugging on the OpenVMS machine.
Common project settings
Visual Studio’s Project Designer enables you to set project-level settings (i.e., project properties), and it enables you to set environment variables. The following are some of the most commonly used features in Project Designer. See Synergy/DE project properties for more information, including information on other pages and settings that are available for Synergy projects.
The Application page enables you to configure various application-level settings for a project.
- The "Output name" field enables you to give the resulting executable or library (.exe or .elb) a different name than that of the project. (The Output name option is not available for Multiple Mainline projects. With these projects, executables are named for their source files.)
- The "Working directory" field enables you to specify the working directory for compiler commands. By default, this is the object folder (obj) for the project.
Note that if your code files have .INCLUDE statements that don’t specify a path (e.g., .INCLUDE myfile.def), you’ll need to set the "Working directory" option to the directory with the included files (e.g., the directory with myfile.def).
- For Multiple Mainline projects, the "Startup object" field determines which mainline is used as the starting point when you select a Visual Studio debug or run option — e.g., Start Debugging or Start Without Debugging. (You can also set this by right-clicking a source file in Solution Explorer and selecting “Set as Startup Object” from the context menu.)
See Application page, Project Designer (traditional Synergy) for more information.
The Build page enables you to configure build settings for a configuration/platform combination for the project.
- The Configuration and Platform settings determine which build configuration the other settings on this page apply to. See Configurations, platforms, and profiles for more information.
- The "Target Synergy runtime" setting specifies the version of the Synergy runtime that the executable or library will target. This enables you to build an assembly for systems with earlier versions of the Synergy runtime.
- The "IntelliSense language version" setting specifies the version of Synergy DBL that will be used for IntelliSense.
- The "Output path" setting enables you to specify the output folder for the project. For an ELB project, it is also used as the path for any project references made to the ELB project.
Although you can use Visual Studio to build files for Linux, you can’t run Linux applications on Windows because of path differences. So for Linux, set the output path for the project to a network share on a Linux machine. This will enable you to build the project in Visual Studio and then run and debug the program on the Linux machine.
See Build page, Project Designer for more information on Build page settings.
The Compile page enables you to set compiler options for a project. See Compile page, Project Designer (traditional Synergy) for more information.
The Debug page enables you to set debugging behavior for a profile (for a .NET Core or .NET Standard project) or a configuration/platform combination (for all other project types). See Debug page, Project Designer for more information on Debug page settings. See Configurations, platforms, and profiles for more information on configuration/platform and profile settings.
Environment Variables page
The Environment Variables page enables you to set project-specific environment variables that are used at build time. Locations specified by environment variables set here are also used to populate the Synergy tab of the Reference Manager for Visual Studio. See Environment Variables page, Project Designer.
Common Properties page
The Common Properties page enables you to set environment variables that are used at build time and that can be applied to any project in the solution. Locations specified by environment variables set here are also used to populate the Synergy tab of the Reference Manager for Visual Studio. See Common Properties page, Project Designer.