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. (For information on limitations to Linux and OpenVMS development, see Development steps for traditional Synergy below.)
1. Using Visual Studio and SDI to develop traditional Synergy executables and libraries.
Note the following:
- In Visual Studio, builds take the place of compiling and linking. When you build a traditional Synergy project or solution in Visual Studio, Visual Studio automatically uses the Synergy compiler and linker behind the scenes.
- 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 can’t set the ‑qimpdir compiler option or the ‑expdir option for dblproto. These are reserved for internal use by the build system.
- If you use gennet40 to generate Synergy classes, add the primary output file (the generated .dbl file with the INCLUDE statements) to an ELB or OLB project that your mainline project will reference.
For information on moving existing traditional Synergy code into Visual Studio, see the document Migrating Traditional Synergy Projects to Visual Studio in the Resource Center on the Synergex website.
Development steps for traditional Synergy
The following steps outline the process for creating a new traditional Synergy application from Synergy project templates. Note the following:
- 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, build the program, and then run and debug it on the Linux machine. Also 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 will not be able to deploy files built in Visual Studio, but you can develop and build with Visual Studio on Windows, and you may also be able to run and debug your code on Windows. For full debugging and final deployable builds, you will need to move the code to an OpenVMS development machine. Projects for OpenVMS programs and libraries may also need to reference the VmsCompatibility library (see step 4 below).
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 and the way IntelliSense works for Synergy DBL files. See Options for Synergy/DE Projects.
||In Visual Studio, use the following project templates to create a project for each program and library in your application. (You can combine multiple mainlines into a single project by using the Multiple Mainline project template.)
- Traditional Application (DBR). Use this to create a traditional Synergy program with a single .dbr file. Projects created with this template can reference Synergy ELB, OLB, and repository projects.
- 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 several common libraries. Projects created with this template can reference Synergy ELB, OLB, and repository projects.
- Executable Library (ELB). Use this to create a collection of traditional Synergy routines that can be used in other traditional Synergy ELBs and DBRs. You can also use this project type to build an ELB directly from an OLB. Projects created with this template can reference other Synergy ELB, OLB, and repository projects.
- 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. Projects created with this template can reference source files and Synergy/DE Repository projects and can be used to directly build an ELB.
For example, to create a traditional Synergy program with a single .dbr file, select File > New Project, select Synergy/DE from the Installed Templates area of the New Project dialog, and then select “Traditional Application (DBR)” from the list of project types. You’ll need to set a few options for the project (name, location, and so forth) in the New Project dialog; then click OK. See Synergy/DE Project Templates for more information on these templates, and note that you can also create a project for repositories used by your program (see Using Synergy/DE repositories in Visual Studio).
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).
||Add code and other items to your projects. For example, you can add a new code file by right-clicking the project node in Solution Explorer and selecting Add > New Item from the context menu. 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. For more information, see IntelliSense, Text Editor Options.
- You can add an ISAM file by selecting Add > Existing Item or Add > Reference Existing Item from the context menu that opens when you right-click the project node in Solution Explorer. 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.
- 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.
||Add references to other projects or files as necessary. References enable a project to use other libraries, and you can use references for repositories. Referencing a library is equivalent to linking to a library (i.e., equivalent to 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:
To reference an ELB, reference its Visual Studio project when possible, not just the ELB file. (If you reference an ELB file rather than its project, there will be no IntelliSense or prototypes for that ELB.) If you reference an ELB project, make sure you set the output path correctly for the ELB.
See Referencing ELBs and OLBs and Is IntelliSense available for my Synergy file? for more information.
- For information on adding dependencies or references to Synergy/DE repositories, see Using Synergy/DE repositories in Visual Studio.
- If code for OpenVMS includes DBL$ or SYS$ routines, the Visual Studio project with that code must reference the VmsCompatibility library 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.
- Prototyping enables the compiler to perform full parameter checking, and it enables IntelliSense to supply parameter information correctly. To enable prototyping to work correctly in multi-project solutions, all references must be resolved. And to ensure that all routines are correctly validated against prototypes, select the "Require prototype usage (‑qreqproto)" option on the Compile page of Project Designer.
Note that prototype-only references are required to resolve calls from libraries early in the build order to higher-level libraries (libraries later in the build order)—i.e., circular references. However, these references are not supported for classes and class members. See Creating a prototype-only reference for more information.
||Set environment variables needed for developing or running the application. Environment variables can be set in the environment, synergy.ini, synuser.ini, the Environment Variables page of Project Designer, and the Common Properties page of Project Designer. See Environment variables and Visual Studio development.
For example, if the project is for Linux or OpenVMS development, select linux32, linux64, or vms as the "Platform target" on the Build page of project Designer. For information on adding a platform configuration for one of these platforms rather than setting the "Platform target" option directly (e.g., to build for both Windows and OpenVMS), see Adding a platform configuration below.
||Build a project or the entire solution by using a Build or Rebuild option in Visual Studio. For example, you can rebuild the entire solution by selecting Build > Rebuild Solution from the Visual Studio menu.
||Debug the project or solution. To debug a project or solution, it must be built in Debug mode.
- 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 with files built on Windows, but for full debugging you'll need to run the application on an OpenVMS machine and then 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.
Adding a platform configuration
If you have an existing project you want to port to Linux or OpenVMS, you can use the Visual Studio Configuration Manager to create a configuration that targets Linux or OpenVMS.
||Open Configuration Manager (e.g., select Build > Configuration Manager from the Visual Studio menu) and select New from the “Active solution platform” drop-down list.
||In the New Solution Platform window, select linux32, linux64, or vms as the platform (see figure 2 below) and select x64 or x86 for the "Copy settings from" option.
2. Selecting a platform for a new configuration.
||Make sure the “Create new project platforms” option is selected, and click OK. Then, in the “Project contexts…” table, select the new platform for each project in your solution (see figure 3).
3. Selecting the new configuration for a project.
When you set the "Copy settings from" option to linux32, linux64, or vms, the platform target (an option on the Build page of Project Designer) is automatically set to a Linux or OpenVMS target.
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. Other pages and settings are available for Synergy projects. See Synergy/DE Project Properties for more information.
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, where 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 project.
- The Configuration and Platform settings determine which build configuration the other settings on this page apply to.
- The "Target Synergy runtime" setting specifies the version of the Synergy runtime that the executable or library will target, which enables you to build an assembly or 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.
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 project. See Debug Page, Project Designer for more information.
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 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 used to populate the Synergy tab of the Reference Manager for Visual Studio. See Common Properties Page, Project Designer.