Referencing ELBs and OLBs
References enable a traditional Synergy project in Visual Studio to use libraries (ELBs and OLBs). 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. (References also enable you to use repository projects. See Using Synergy/DE repositories in Visual Studio.)
To add a library reference to a traditional Synergy project, right-click the References node for the project in Solution Explorer, and then select Add Reference from the context menu. Note the following:
- Whenever possible, reference a project for an ELB or OLB rather than a built ELB or OLB. If you reference a built ELB or OLB, there will be no IntelliSense or prototypes for the file, and you may not be able to use the "Require prototype usage (-qreqproto)" option (on the Compile page of project properties), which ensures that routines are fully validated against prototypes.
- If you reference a built ELB or OLB file (.elb or .olb) with object code (classes, methods, etc.), you must put the built ELB or OLB and its prototype file (.dbp) in the same directory. This enables Visual Studio to use the .dbp file for strong prototyping when the solution is built.
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. (When creating a library for shared code, use an ELB rather than an OLB.)
- A special type of reference (a prototype-only reference) can be used resolve a call from a library early in the build order to a library later in the build order — i.e., a circular reference. See Creating a prototype-only reference for more information, and note that prototype-only references are not supported for classes and class members.
We recommend using environment variables when referencing ELBs. Paths to ELBs are hard-coded in applications and libraries that reference them, and they are limited to 31 characters. To use an environment variable when referencing an ELB, do one of the following:
- To reference an ELB project, use an environment variable in the “Output path” field on the Build page of project properties, and then use the Project tab of the Visual Studio Reference Manager to add the reference. (See figure 1 below.) For an ELB project, “Output path” is used as the path for project references to the ELB, in addition to defining the target location for build files for the project. And if you use an environment variable in this field, that environment variable will be used for the path for project references to the ELB. (Note that an environment variable used with "Output path" cannot be defined using another environment variable. See Build page of Visual Studio project properties for more information.)
- To reference a built ELB (an .elb file), use the Synergy tab of the Visual Studio Reference Manager. For traditional Synergy projects, the Reference Manager in Visual Studio includes a Synergy tab that makes it easy to add references to ELB and OLB files. This tab lists all ELBs and OLBs in locations specified by DBLDIR, RPSLIB, and WND, as well as locations specified by environment variables set on the Common Properties and Environment Variables pages of project properties. If you use this tab, the environment variable specified for the ELB will be used as the path. See figure 2 below.
If you use a tab other than the Synergy or Project tab, or if you use the Project tab without specifying an environment variable in “Output path”, the full path to the ELB on the development machine will be hard-coded in the executable or library that references the project (if the path does not exceed 31-characters). The hard-coded path will then be used to locate the ELB on deployment machines.
Keep in mind that if you use environment variables when referencing ELBs, those environment variables must be set on deployment machines. If an environment variable for a referenced ELB is not set on a deployment machine, the Synergy runtime will look for that ELB in the current directory for the running DBR.