Developing a traditional Synergy application in Visual Studio
This topic includes the following sections:
- Development steps for traditional Synergy
- Adding code and other items
- Referencing projects and files
- Linux development
- OpenVMS development
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. Note the following:
- With Visual Studio, builds take the place of the compiling and linking required when developing outside of Visual Studio. See Builds for more information.
- 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.
- You can develop for Linux and OpenVMS in Visual Studio, but there are restrictions. See Linux development and OpenVMS development below.
Development steps for traditional Synergy
The following steps outline the Visual Studio development process for a traditional Synergy application. Most of these steps are for Visual Studio procedures, so see Visual Studio documentation for more information.
1. | Start by setting options for your Visual Studio environment. For example, you can control the behavior of the Visual Studio code editor (indentation, tab size, etc.), the way IntelliSense works for Synergy DBL files, and which file types are automatically treated as compile or content files. See Options for Synergy/DE projects for more information. |
- Traditional Application (DBR) — for a traditional Synergy program with a single .dbr file.
- Multiple Mainline (DBR) — for a Synergy project that results in multiple traditional Synergy mainline programs.
- Executable Library (ELB) — for a collection of traditional Synergy routines that can be used in other traditional Synergy ELBs and DBRs.
- Object Library (OLB) — for a traditional Synergy object library (OLB) that can be used with other ELB and DBR projects.
- Synergy/DE Repository — for a repository project, which replaces RPSMFIL and RPSTFIL settings and enables the build system to know when a project should be rebuilt due to repository schema file changes. See also Using Synergy/DE repositories in Visual Studio.
For example, to create a program with a single .dbr file, select File > New Project in Visual Studio. Then select the "Traditional Application (DBR)" template. (You can use the New Project dialog's search field to find this.) 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. To start with a blank solution, do the following before you create projects for the application: select File > New > Project from the Visual Studio menu, and then select the Blank Solution template. You can use the search feature in the New Project dialog to find this template.
- 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 create an ELB that builds directly from an OLB. See Executable Library (ELB).
- If your application uses files generated by gennet40, create a separate ELB or OLB project for these files, and in step 2 below add the source files and the .inc file generated by gennet40 to this project. (Add the source files as compile files, and add the .inc file as a content file.) Then in step 3 below, add a reference to this project in the mainline (DBR) project, and set the "Concat source files (-qconcat)" option on the Compile page of project properties.
- For Linux and OpenVMS development, use the project templates listed above. See Linux development and OpenVMS development.
Note the following:
- For Multiple Mainline projects, the "Startup object" field on the Application page of project properties determines which mainline is used as the starting point when you select a Visual Studio debug or run option. You can also set this by right-clicking a source file in Visual Studio's Solution Explorer and selecting "Set as Startup Object" from the context menu.
- The "Target Synergy runtime" setting on the Build page of project properties specifies the version of the Synergy runtime that the executable or library will target, enabling you to build an assembly for systems with earlier versions of the Synergy runtime.
- 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.
- You can control the link order for referenced items for a traditional Synergy program by setting priority levels for these items. See Setting link priority for traditional Synergy in Visual Studio.
The Visual Studio Error List (View > Error) lists any errors encountered in the build. You can filter this list so that it is limited to the current project (which 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.
5. | Create unit tests by using the “Traditional Unit Test” project template. See Unit testing for traditional Synergy. |
6. | Debug the project or solution. To debug a project or solution, it must be built in Debug mode. See Debugging traditional Synergy with Visual Studio for more information, and note the following: |
- Make sure configuration, platform, and profile settings are correct for the debugging session. The active configuration/platform combination determines which debug settings are used and which build is debugged. See Configurations, platforms, and profiles.
- For information on debugging applications for Linux and OpenVMS, see Linux development and OpenVMS development below.
Adding code and other items
You can add a new or existing item (a code file, a text file, etc.) by right-clicking the project node in Visual Studio's Solution Explorer and selecting one of the following from the context menu: Add > New Item, Add > Existing Item, or 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:
- For information on items you can add with Add > New Item, see Synergy/DE item templates.
- You can add a Synergy data file (e.g., a Synergy ISAM file) by using Add > Existing Item or Add > Reference Existing Item.
- 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 page of Visual Studio 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.
- 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). See Application page of Visual Studio project properties (traditional Synergy) for more information.
- 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 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.
Referencing projects and files
References enable a project to use other projects (libraries and 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 Visual Studio's Solution Explorer and selecting Add Reference from the context menu. Note the following:
- For a project to use 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.
- For information on referencing ELBs and OLBs, see Referencing ELBs and OLBs.
- 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.
- 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 properties.
Linux development
For Linux, there are two Visual Studio development paths:
- Develop, build, run, and debug your application using Visual Studio on Windows. You can then copy the compiled application or library to Linux machines (e.g., via a post-build event on the Build Events page). This may not be possible due to path differences between Windows and Linux.
- Develop with Visual Studio, but keep a parallel copy of the source files on a Linux machine (e.g., keep a version-control repository with the same files on the Linux machine). Then build, run, and debug the code on the Linux machine. As you find issues, fix them in Visual Studio, and then update the files on the Linux machine.
In either case, use the same project templates you would use for Windows (see step 2 above). And be sure to use the linux32 or linux64 platform target (see Adding a Linux or OpenVMS platform for traditional Synergy). These platform targets cause Visual Studio to compile the projects as if they were compiled on a Linux system — e.g., code marked with OS_UNIX is included.
Keep in mind that Linux is case sensitive, so when you define environment variables or specify paths or filenames, make sure the case is correct.
To debug 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. See Debugging traditional Synergy with Visual Studio for more information.
OpenVMS development
For OpenVMS, you can develop and build with Visual Studio in 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 final deployable builds, you will need to move the code you developed in Visual Studio to an OpenVMS development machine.
- Use the same project templates you would use for Windows (see step 2 above). Projects created with the "Traditional Application (DBR)" and "Multiple Mainline (DBR)" templates will create .dbr files that will correspond to the .EXE files you will build on the OpenVMS machine from the source files. For code that will become a shared library on OpenVMS, use the "Executable Library (ELB)" project template.
- Use the vms platform target and add solution and project platform configurations as described in Adding a Linux or OpenVMS platform for traditional Synergy. The vms platform target causes Visual Studio to compile the project as if it were compiled on an OpenVMS system — e.g., code marked with OS_VMS is included.
- You may be able to do preliminary debugging using Visual Studio with files built and run on Windows. However, 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. See Debugging traditional Synergy with Visual Studio for more information.
- 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.