Open Menu

Synergex Blog

Exposing WCF services using Synergy .NET Interop

By Steve Ives, Posted on September 2, 2011 at 11:20 am

In this post I will explain how a WCF service can be created using a Synergy .NET Interop project. In my earlier post I explained how to use xfNetLink .NET to create a WCF service, which provided an easy way to create a WCF service for developers who were already using xfNetLink .NET and xfServerPlus. Now I want to show you an alternate approach that is somewhat similar in nature, but which does not require the continued use of xfNetLink .NET and xfServerPlus in final solution. Of course this might not be what you want if your Synergy server is a non-Windows system.

This is the fourth in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF services using Synergy .NET Interop (this post)
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET

What is Synergy .NET Interop

Before we get started we better make sure you know what a Synergy .NET Interop project is. In a nutshell an Interop project is a way of creating a .NET assembly containing various classes, where the external interface of those classes is defined by a collection of Traditional Synergy xfServerPlus methods, and the Synergy records that are referenced by the parameters of those methods. The idea is that the classes exposed by the assembly created by an Interop project have the exact same external interface that would be created if those same methods were defined in a Method Catalog and exposed via xfServerPlus and xfNetLink .NET. So the primary use case for an Interop assembly is to allow developers with existing applications which use xfNetLink .NET and xfServerPlus to factor those tools out of their solution, resulting in a pure .NET application.

In the same way that GENCS has an optional –W command line switch which essentially transforms the resulting .NET assembly into a WCF service, the Synergy .NET Interop project has a project option which does the exact same thing.

So let’s get started. Here’s how to do it. Remember, an Interop project allows you to expose a Synergy .NET assembly based on one or more traditional Synergy methods and records, but there are some prerequisites:

  1. The Synergy methods must make use of the recently introduced attributes and documentation comments, so that the external interface of the method is entirely defined within the code. The Interop project does not use a Synergy Method Catalog. For more information on this you can refer to a blog post that I wrote back in 2009 called Wave Goodbye to the MDU.
  2. The records that are referenced by the parameters of the methods must be defined in a repository, but this would always have been the case if you were using xfServerPlus.
  3. Generally the data files that are accessed by your methods should be moved to the Windows server where the WCF service will be hosted, so that the files can be accessed locally. If your data files need to stay on a non-Windows server then of course you could use xfServer to access the files remotely.
  4. You’ll need to have a copy of the source code for the Synergy methods available on the Windows development system where you are using Synergy .NET.

These are the steps that you’ll need to complete in order to create a Synergy .NET Interop assembly from your existing Synergy methods and repository structure definitions:

Create an Interop Project

The first step in the process is to create a new Synergy .NET Interop Assembly project:

  • Open Visual Studio and create a new Synergy .NET Interop Project.
  • From the menu, select File > New > Project.
  • In the Installed Templates list select Synergy/DE > Interop.
  • Set the name and location of the new project as required (here I’m naming the project MyInteropAssembly and setting the location to my c:temp folder).
  • Click the OK button to create the new project.



When you create an Interop project a new source file called SynergyRoutines.dbl is automatically included in the project. This file contains various utility routines that are used by the interop project in order to expose the same interface that xfNetLink .NET does. You shouldn’t need to be concerned with this code, and shouldn’t modify it. Simply close the file.

Add Synergy Method Source Files

Having created the Interop project the next step is to add the source code for your Synergy methods to the project. Remember that the methods that you include in an Interop project are Traditional Synergy subroutines and functions that include whatever {xfMethod} and {xfParameter} attributes are required in order to completely document the external interface of the methods within the source files.

imageFor clarity when creating an Interop project I also like to include my method source files in a folder within the project, and I generally name the folder “Methods”. This is entirely optional though.

  • In solution Explorer, right-click on your Interop project and from the context menu select Add > New Folder.
  • Change the name of the folder to Methods and press enter.
  • Right-click on your new Methods folder and from the context menu select Add > Existing Item….
  • Use the resulting open file dialog to browse to the location of your Synergy method routines, select them all, and then click the Add button to add the routines to your project.

In Solution Explorer your project should now look something like the image on the right.

Before we move on let me make a couple of things clear. Firstly it is important that you know that when you add existing files to a project using Add > Existing Item, those files are COPIED into your project folders. If you prefer to leave the source files in their existing location then you can use Add > Reference Existing Item.

The second thing that you need to understand is that in the example I am using here the nature of the methods that I am using is relatively simple, and the methods don’t have external dependencies on other routines in libraries, don’t use include files, etc. If your methods do have such dependencies then you will need to decide how best to resolve those dependencies.

Set Environment Variables

It is likely that you will need to set some environment variables in order for your code to be able to compile and run. It is almost certain that you will need to at least set the environment variables that allow your repository to be located and accessed, and in the case of the code that I am using, at runtime an environment variable named DAT is used to specify the location of the data files that are accessed by the code.

Synergy .NET development projects include the ability to set environment variables in the development environment via properties of the project:

  • In Solution Explorer, right click on your project and from the context menu select Properties.
  • In the project properties dialog, to the left side, select the tab named Environment Variables.
  • Set whatever environment variables are required in order for your code to compile and run.
  • Save your changes by selecting File > Save from the menu.
  • Close the project properties dialog.

In the case of the code I am using for this example I needed to set the following environment variables:


By the way, the tools in Synergy .NET also honor the same mechanisms for setting environment variables as Traditional Synergy on the Windows platform. So if the environment variables that you need are already present in your system environment, or are provided by the synergy.ini or synuser.ini files then you won’t need to set them here.

Build an Interop Assembly

You should now be able to build your interop assembly.

  • In Solution Explorer, right-click on your project and from the context menu select Build.
  • Check the output window, you should see something like this:
------ Build started: Project: MyInteropAssembly, Configuration: Debug Any CPU ------
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========


imageIf your assembly did not build then you’ll need to resolve any errors that you may have before you proceed. The most likely cause for errors at this point will be external dependencies that are not catered for.

Check out what happened in your project. If you look in Solution Explorer you will notice that a new folder called GeneratedCode was created, and some new source files were added to the folder. These new files are at the center of how Interop projects work.

The method source files that you added to the project, in the Methods folder, were Traditional Synergy subroutines and functions. The job of an Interop project is to expose the functionality of those methods in the same way that xfNetLink .NET’s GENCS utility does, and GENCS creates .NET classes that represent the Synergy methods, and the data structures exposed by those Synergy methods.

The Interop project essentially does the same thing, except that where GENCS created C# code which uses xfNetLink .NET and xfServerPlus to call the Synergy methods, the Interop project creates Synergy .NET code which calls the Synergy methods directly.

In the code used in my example the Synergy methods that I added to the project were all part of an interface named “SynergyServer”. This was defined by the {xfMethod} attributes that were present in each of the source files that I included into the project. You will notice that the GeneratedCode folder now includes a source file named SynergyServer.dbl, and if you were to look in the source file you would see that it contains a class named SynergyServer, which in turn contains methods named GetAddressForUpdate, GetAllCustomers and so on. These methods correspond to the Synergy methods that I originally included in the project.

Additionally you will notice that the GeneratedCode folder also contains several source files which represent the record definitions which are exposed by the parameters of my methods. For each record that is exposed the interop project has created a class to represent that data structure. These classes are named Address, Address_type, Contact and so on.

However, if you were to look in the source files that have been generated into the GeneratedCode folder you might notice that these generated classes do not contain any ServiceContract, OperationContract, DataContract or DataMember attributes. In other words, the classes can’t currently be exposed via WCF.

Note: You should not make changes to any of the code in the GeneratedCode folder, because this code will be recreated each time you build the project. 

Expose a WCF Service

As I briefly discussed in an earlier post, in order for classes to be exposed via WCF it is necessary to apply various attributes to those classes:

Nature of Item Required Attribute
Class containing callable methods ServiceContract
Callable method OperationContract
Class defining a data structure DataContract
Accessible member in a data structure DataMember


In an Interop project, these attributes can be automatically added to the generated classes by enabling a project option called “Generate WCF Contracts”.

  • In Solution Explorer, right-click your project and select Properties.
  • In the project properties dialog, to the left side, select the tab named Interop.
  • Check the Generate WCF Contracts option.
  • In most cases it’s also a good idea to set the Generate out parameters property to out instead of the default value of “ref”.
  • Save your changes by selecting File > Save from the menu.
  • Close the project properties dialog.
  • In Solution Explorer, right-click on your project and from the context menu select Build.
  • Check the output window and make sure that your assembly built correctly.


Note: The default behavior of generating out parameters as ref is to maintain compatibility with what GENCS does by default, but when exposing a new WCF service to a new client application you would always want output parameters defined as type out.


Now take a look at the various source files in the GeneratedCode folder. You should notice that the ServiceContract, OperationContract, DataContract and DataMember attributes are present as required.

Host the Service

That’s it, you just used a Synergy .NET Interop project to define and create a WCF service. Of course before you can actually do anything with the service you will need to host it somewhere. One option is to host the service in an ASP.NET Web Application as described in my earlier post.

However, sometimes developers don’t want to have to setup and maintain an IIS web server simply to host a WCF service. Luckily there are other ways of hosting a WCF service that do not require IIS, and that will be the topic of the next post in this series.

Hosting WCF Services in an ASP.NET Web Application

By Steve Ives, Posted on July 1, 2011 at 3:39 pm

There are several ways that you can use Synergy/DE tools to expose WCF services, but regardless of which way you decide to create a service, the next decision you have to make is how to host it. By hosting a WCF service you expos the service and make it possible to use it from other applications. In this post I will introduce you to one way that WCF services may be hosted, via an ASP.NET web application and an IIS web server. In a later post I will show you how to host WCF services without this requirement for an IIS web server.

This is the third in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application (this post)
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET


A WCF service is simply a collection of one or more classes in an assembly, but the whole point of implementing a WCF service is to make those classes available to be used by other applications. And those applications will often be located on different networked systems from the service itself. So, in order for a WCF service to be useful, it needs to be “hosted” somewhere, and that somewhere needs to be available on a network.

There are three basic ways that WCF services can be hosted:

  1. Inside a Web application located on a Web server.
  2. Using Windows Process Activation Services (WAS). This mechanism was introduced in Windows Server 2008 and provides a mechanism for hosting WCF services without requiring a Web server.
  3. Services can be “self” hosted by some custom .NET application. For example, developers often host WCF services inside a Windows Service application.

In this post I will show you the basics of hosting a WCF service in an ASP.NET web application. In a future post I will go on to show how to self-host services.

Setting up basic hosting for a WCF service inside an ASP.NET Web application is very easy, but as Synergy .NET doesn’t have support for creating Web applications you’ll have to use another .NET language, either C# or VB.NET. However, don’t worry about that too much, because there won’t actually be any code in the Web application!

  • Start Visual Studio 2010 and create a new ASP.NET application:
    • From the menu, select File > New > Project.
    • Under Installed Templates, select Visual C# > Web > ASP.NET Empty Web Application.
    • Chose the name and location for your new Web application.
    • Click the OK button to create the new project.
  • Add a new WCF Service to the project:
    • From the menu, select Project > Add New Item.
    • Under Installed Templates, select Visual C# > Web > WCF Service.
    • Enter the name for your new service. The name will be part of the service endpoint URI that the client connects to, so pick something meaningful. For example, if your service allows orders to be placed then you might name the service something like OrderServices.svc.
    • Click the Add button to add the new service to the project.

You will notice that three files were added to the project:


In addition to the service (.svc) file that you named, you will see two C# source files. These files were added because Visual Studio provided all of the files that you would need in order to expose a new WCF service that would be manually coded in these files. But what we’re trying to do is host a WCF service that already exists in another .NET assembly.

  • Delete the two C# source files by right-clicking on each and selecting delete.

In order to expose a WCF service that exists in another assembly, the first thing we need to do is add a reference to that assembly, to make the classes it contains available within the new Web application.

  • From the menu select Project > Add Reference and then select Browse.
  • Locate and select the assembly containing your WCF service and add a reference to your project.
  • If the assembly you selected was created using xfNetLink .NET then you will also need to add a reference to the xfnlnet.dll assembly, as is usual when using xfNetLink .NET

You’ll need to know that namespace and class name of the WCF service in your assembly. If you can’t remember this that double-click on the assembly that you just referenced and then use Object Browser to drill into the assembly and figure out the names. All that remains is to “point” the service file at your WCF service class.

  • Double-click on the service (.svc) file to edit it. You should see something like this:


Edit the file as follows:

  • Change Language=”C#” to Language=”Synergy”.
  • Change Service=”…” to Service=”YourNamespace.YourWcfClass” (obviously replacing YourNamespace and YourWcfClass with the namespace and class name of your WCF service).
  • Remove the CodeBehind=”…” item … there is no code-behind, the code is all in the other assembly.
  • Save the file.

So you should now have something like this:


If your service is based on an assembly created using xfNetLink .NET then you have one final configuration step to perform. You need to tell xfNetLink .NET how to connect to xfServerPlus. You can do this by using the Synergy xfNetLink .NET Configuration Utility (look in the Windows Start Menu) to edit the new web applications Web.config file. If your xfServerPlus service is not on the same machine as your new web application then you must specify a host name or IP address, and if xfServerPlus is not using the default port (2356) then you must also specify a port number. When you’re done, the Web.config file should contain a section like this:


That’s it, you’re done. You should now have a working WCF service!

  • To see if the service has really been hosted, right-click on the service (.svc) file and select View In Browser.

You should see the service home page, which will look something like this:


If you see this page then your service is up and running. By the way, the URI in your browsers address window is the URI that you would use to add a “Service Reference” to the service in a client application … but we’ll get on to that in a later post.

Of course, all we have actually done here is set up a web application to host a WCF service, but we’re using Visual Studio’s built in development web server (Cassini) to actually host the service. If you were doing this for real then you’d need to deploy your new web application onto a “real” IIS web server.

We’re not done with the subject of hosting WCF services; in fact we’ve only really scratched the surface. One step at a time!

In my next post in this series I will show you how to Expose a WCF services using Synergy .NET Interop.

Exposing WCF Services using xfNetLink .NET

By Steve Ives, Posted on at 1:40 pm

Following a recent enhancement to the product in Synergy 9.5.1, developers can now use xfNetLink .NET to create and expose Windows Communication Foundation (WCF) services. In this post I will describe how to do so.

This is the second in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET (this post)
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET


The basic approach is pretty easy; in fact it’s very easy. In 9.5.1 we added a new -w command line switch to the gencs utility, and when you use the new switch you wind up with a WCF service. I told you it was easy!

So, what changes when you use the gencs –w switch? Well, the first thing that changes are the procedural classes that are generated, the ones that correspond to your interfaces and methods in your method catalog, change in the following ways:

  1. Three new namespaces (System.Runtime.Serialization, System.ServiceModel and System.Collections.Generic) are imported.
  2. The class is decorated with the ServiceContract attribute. This identifies the class as providing methods which can be exposed via WCF.
  3. Methods in the class are decorated with the OperationContract attribute. This identifies the individual methods as being part of the service contract exposed by the class, making the methods callable via WCF.
  4. If any methods have collection parameters, the data type of those parameters is changed from System.Collections.ArrayList to System.Collections.Generic.List. Changing the collection data type is not strictly necessary in order to use WCF, but results in a more strongly prototyped environment which is easier to use, and offers more benefits to developers in terms of increased IntelliSense, etc.

The next thing that changes are any data classes, the ones that correspond to the repository structures that are exposed by the parameters of your methods, that are generated. These data classes change in the following ways:

  1. Two new namespaces are imported. These namespaces are System.Runtime.Serialization and System.ServiceModel.
  2. Each data class (which corresponds to one of your repository structures) that is generated is decorated with the DataContract attribute. This identifies the data class as a class which can be used in conjunction with a WCF service, and which can be serialized for transmission over the wire.
  3. Each public property (which corresponds to a field in the structure) is decorated with the DataMemeber attribute. This attribute identifies each property within the class as one which will be serialized, and as a result will be visible to client applications which use the WCF service.

By the way, if you use a Workbench “.NET Component Project” to create your xfNetLink .NET assemblies then there isn’t currently an option in the component information dialog to cause the new –w switch to be used. So, for the time being, what you can do is add the switch to the Workbench “Generate C# Classes” tool command line. To do this you would go into project properties for the component project, go to the Tools tab, select the “Generate C# Classes” tool, then add the –w at the end of the command line, like this:


We’ll be adding a new checkbox to the component information dialog in 9.5.3 later this year.

By the way, by using the gencs –w switch you make it possible to use the resulting classes as a WCF service, but you don’t have to do so … you can continue to use the classes as a regular xfNetLink .NET assembly also. Why would you want to do that? Well, I sometimes use gencs –w just to turn my collection parameters into generic lists!

I have submitted a working example to the Synergy/DE CodeExchange, contained within the zip file called Within the example, the following folders are relevant to exposing and consuming a WCF Service using xfNetLink .NET:

Folder / Project



Contains the Workbench development environment for xfServerPlus and the exposed Synergy methods. If you wish to actually execute the examples then you must follow the setup instructions in the readme.txt file.


Contains the Workbench project used to create the xfNetLink .NET client assembly with the WCF attributes.


Contains the Visual Studio 2010 solution containing an ASP.NET web application used to host the WCF service, as well as three example client applications, written in Synergy .NET, C# and VB.

So, the gencs –w command line switch you make it possible to use the resulting classes to directly expose a WCF service, but there is still the matter of how to “host” the service in order to make it accessible to remote client applications, and that’s what I will begin to address in my next posting.

Building Distributed Apps with Synergy/DE and WCF

By Steve Ives, Posted on June 22, 2011 at 1:22 pm

At the recent SPC’s in Chicago and Oxford several of the sessions that I presented were focused on networking, and in particular on the various tools and technologies that are available to Synergy developers to allow them to build and deploy distributed software applications. In particular I spent quite a bit of time talking about a technology called Windows Communication Foundation.

This is the first in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF (this post)
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET

What is WCF

WCF is a part of the .NET framework that provides a powerful and flexible way to implement network communication between the various parts of a distributed software application. For many years Synergy developers have been able to build distributed applications using xfServerPlus and xfNetLink. Many have done so, and have deployed a wide variety of applications based on these technologies. When developing a new .NET client application developers would use xfNetLink .NET to gain access to their Synergy business logic and data.

This approach has served us well over the years, will continue to do so, and is still the most appropriate solution in some scenarios. But in some other scenarios using WCF might now be more appropriate, and could help developers to broaden the capabilities of their applications in several key areas, some of which are:

WAN Communication

Because the communication between xfServerPlus and xfNetLink uses a custom protocol which operates on a “non-standard” port, it may not be appropriate for use over wide area networks and the Internet. The primary problem here is that there is a high chance that this communication would be blocked by firewalls, some of which may be outside of your control. WCF supports multiple network transport protocols, the most basic of which is HTTP. This means that it is designed with the Internet in mind, and is very suitable for implementing applications which communicate over the Internet.

Multiple Endpoints

Another advantage of WCF is that the same WCF service can be exposed via multiple “endpoints”, and each of these endpoints can be configured to use different communication protocols and mechanisms. For example a single service could be exposed via one endpoint which uses HTTP and SOAP which would be suitable for a wide variety of client applications to be able to access from anywhere (including via the Internet), while at the same time being exposed by a second endpoint which uses low-level TCP/IP communications and binary messaging protocols suitable for use by applications running on the same local network as the service, at much higher performance. A single client application could even be configured to dynamically switch between these endpoints based on the current location of the user.

More Client Options

When using xfServerPlus and xfNetLink, client applications must be written in a programming language which is able to use one of the supported xfNetLink clients (COM, Java or .NET), but because WCF services can be interacted with via “standard” protocols such as HTTP and SOAP there are many more client application possibilities, because almost all development environments and programming languages are able to use these basic protocols.

Asynchronous Support

WCF also provides the ability to easily support asynchronous communication between clients and servers. When a client application calls an xfServerPlus method the client must wait for the execution of the method to complete, and for any resulting data to be returned, before performing any other processing. Using WCF it’s easy to support asynchronous method support, where the client application can call a method and then continue with other processing, later receiving an event when the remote method has completed its operation and when any resulting data is ready for use. This approach can make client applications appear to be much more dynamic and responsive.

Bi-Directional Communication

In many distributed software applications interaction between the client and the server is initiated by some event in the client application which requires some subsequent processing in the server application. But in some situations it is necessary for the server application to be able to, at will, initiate some processing in the client application. Unfortunately xfServerPlus and xfNetLink don’t really address this use case, but it can be addressed with WCF, because WCF service endpoints can be “self-hosted” within any type of .NET application. This means that as well as a client application having the ability to interact with a WCF service on some server somewhere, the client can also expose a WCF service, which the server application (or in fact any other application) could interact with.

WCF is an extensive subject area, and in this BLOG I’m not even going to attempt to teach you about the specifics of using WCF. Instead I’m simply going to try to make you aware of some of the reasons that you might want to explore the subject further, and make sure that you know about the various ways that you can get started.

There are several ways that Synergy developers can utilize WCF in their applications, and I’ll briefly describe each of these mechanisms below.

WCF via xfNetLink .NET

In xfNetLink .NET 9.5.1 a new feature was introduced which gives developers a lot of additional flexibility in the way that they build their applications, or rather the way that they communicate between the various parts of the application. This new feature is enabled through a new command line parameter to the gencs utility (-w). When you use this new option, two things change.

When you use gencs –w, the first thing that changes is that various attributes are added to the wrapper classes that are created by gencs. These attributes in turn allow those generated classes (and the assembly that they are compiled into) to be directly exposed as a WCF service. Previously, if a Synergy developer wanted to expose a WCF service which in turn exposed their Synergy business logic and data, they have to manually “wrap” their xfNetLink .NET procedural and data classes in other classes which in turn exposed a web or WCF service.

The second change when using gencs -w is that any collections which are exposed by the application API are transformed from un-typed “ArrayList” collections, to more useful and flexible “Generic List” collections. This change will require a small amount of re-coding in any existing client applications, but results in a significantly enhanced development experience.

This mechanism is likely to be of interest to developers who already have an existing solution using xfNetLink .NET and xfServerPlus, and want to take advantage of some of the additional capabilities of WCF, or to developers who wish to expose a new WCF service where the server application exposes code running on a UNIX, Linux or OpenVMS server.

WCF via Synergy .NET Interop

Another way that Synergy developers can expose WCF services is via Synergy .NET’s “Interop” project. The primary purpose of an Interop project is to allow developers with existing xfServerPlus applications to migrate their existing Synergy methods to a native .NET environment. By adding their method source code to an interop project they are able to execute those methods directly in the .NET environment, instead of using xfNetLink .NET and xfServerPlus to execute the methods with traditional Synergy on a remote server.

The Interop project works by generating Synergy .NET “wrapper classes” for your traditional Synergy methods (subroutines and functions) and data structures (records). The external interface of these wrapper classes is very similar to that of the C# wrapper classes produced by xfNetLink .NET’s gencs utility. The primary goal of the Interop project is to allow developers to migrate existing applications from a mixed .NET / traditional Synergy environment to a 100% .NET environment, with only minor changes to the code of existing client applications.

When you create an Interop project in Visual Studio, one of the options that you have (via the project properties dialogs) is to “Generate WCF contracts”, and as discussed earlier in this article, the effect of this is to add various attributes to the generated wrapper classes so that they can be directly exposed as a WCF service.

So again, for Synergy developers, this approach can provide a quick-and-easy way to expose a WCF service based on existing code. Again, this approach is likely to be primarily of interest to those who already have xfServerPlus based applications running on the Windows platform.

WCF via Synergy .NET

Both of the previous approaches were primarily focused on those who already use xfServerPlus, and both provide an easy way to get started with WCF. However in both of the previous scenarios, the external interface of your WCF service is directly defined by the interface to your underlying traditional Synergy methods (subroutines and functions), and the WCF data contracts that are exposed are defined by the repository structures exposed by the parameters of those methods. So, while the WCF capabilities provided by xfNetLink .NET and by the Synergy .NET Interop project are easy to use, you don’t get full control over the exposed interface and data. If you want that finer level of control, or if you’re just getting started with server application development and don’t have existing xfServerPlus methods, there is a better way to go.

The third way that Synergy developers can leverage WCF is by using Synergy .NET to create an all-new WCF service with native .NET code. This task was possible in 9.5.1 when Synergy .NET was first introduced, but has been made much easier through the introduction of a new “WCF Service Library” project template in 9.5.1a.

Creating a new WCF service via a WCF Service Library is the way to go for developers who want to write an all-new service application, or who don’t mind a little extra effort to re-work some existing code in order to factor out some of the “wrapper” layers involved with the previous two approaches. As a result you will have full control of the resulting WCF service, and the contracts that it exposes.

Wrapping Up – For Now

So, as you can see, Synergy/DE is now providing you will all kinds of new and exciting things that you can do in your Synergy applications, and I firmly believe that WCF is one of the most important, and powerful. In the near future I will be writing several additional BLOG posts which will explain these three ways of exposing WCF services in more detail, and I’ll also try to provide more detail about WCF generally. So for now, be thinking about how your existing distributed applications are built, and what things you might wish to improve about them. Or be thinking about that all-new distributed application that you’ve wanted to get started on. If you’re thinking of enhancing or implementing a distributed application, then using WCF is almost certainly the way to go.

ChronoTrack goes virtual!

By Richard Morris, Posted on November 20, 2009 at 11:36 pm

Did you attend SPC2009?  If you did then you’ll know all about ChronoTrack.  If you didn’t, ChronoTrack is an application that the PSG team developed to showcase the latest technologies available to Synergy developers.  It’s a UI Toolkit application that’s had a face lift!  It’s a cool, slick web site, oh, and a mobile app, and did I mention the system tray monitor and dashboard?  It uses the latest OO capabilities within Synergy and enhances the user experience by hosting .NET WinForms.  It exposes Synergy data through traditional functions via xfServerPlus/xfNetLink.NET to both a Web Service and fully functional Web site.

One customer, who attended SPC2009, was so impressed with the new capabilities of Synergy that ChronoTrack demonstrated they wanted to present it to their team!  So, I set the recorder going and recorded a ten minute overview video.  And what was the customer’s response?  “Perfect, I’ll be presenting this at next week’s steering committee!”

Fancy a peek?  Take your virtual tour of the ChronoTrack Windows application at

There’ll be more videos available soon – just working on topics.  If you have any requests, please let me know by commenting against this blog.

And remember, ChronoTrack is available on CodeExchange, so if you want to see the code-behind, log in to the Synergy resource centre, click the CodeExchange link and search for ChronoTrack.



Wave Goodbye to the MDU

By Steve Ives, Posted on November 12, 2009 at 5:41 pm

If you have ever developed with xfServerPlus and xfNetLink then, like me, you may have a “love-hate” relationship with the Method Definition Utility (MDU). You love it because it is an enabling technology … it is one step in the process of extending your Synergy applications with all types of cool client applications. But at the same time you hate it … because it’s an inconvenience to have to remember to run up the utility and update the method catalog each time you want to add a new method, or change the interface of an existing one. Today, using the MDU is a “necessary evil”. It has served us well over the years, but things are about to get a whole lot better.

Synergy/DE 9 introduced many new features to the language, and some of these new features could make entering information into the MDU kind of redundant. For example, rather than declaring a routine like this:

function get_product, ^val
  arg1 ,a ;Product code (passed in, a10)
  arg2 ,a ;Product record (returned, product record)

Synergy 9 allows us to define the routine like this:

function get_product, boolean
  required in productCode ,a10
  required out productRecord ,sProduct


As you can see, we can now specify much more information about the external interface of a routine actually in the source code … and this additional information is the same as the information that we specify when defining the routine in the MDU. But in 9.1 the picture wasn’t complete. There is still information that xfServerPlus (and tools like GENXML and GENCS) require from the method catalog, for which there is no language syntax to allow that information to be expressed in the actual code. For example, at a minimum we need to specify the name of the “interface” that the routine (method) will belong to, and the name of the library in which the routine in located.

Enter Synergy/DE 9.3, and an array of new features. One of those features is the introduction of support for “attributes”. Attributes are a mechanism which allows a programmer to “decorate” source code with additional information, or metadata, which provides information about the code. The metadata can then be used by compilers, or other tools that may process the source code in order to extract information, or take some other action.

We’re likely to see many and varied uses for attributes in Synergy/DE for .NET, but for now, as well as adding support for attributes in the language, 9.3 introduces the first use of attributes for Synergy/DE xfServerPlus developers. Attributes can be used to provide all of the remaining information needed to automatically populate the method catalog!

Here’s the same function that we looked at earlier, but with an attribute added:

function get_product, boolean
  required in productCode ,a10
  required out productRecord ,sProduct

By the way, this is a simple example. There are many properties that can be specified in the xfMethod attribute, and there is also an xfParameter attribute which allows you to provide information about the routines parameters.

It’s also possible to specify “documentation comments” within source code, and these comments can be used to populate the method, parameter and return value description fields in the method catalog. A routine with documentation comments would look something like this:

;;;<summary>Retrieves a product record.</summary>
;;;<returns>Returns true for success or false for failure.</returns>
;;;<param name="productCode">SKU of product to retrieve</param>
;;;<param name="productRecord">Returned product record</param>
function get_product, boolean
  required in productCode ,a10
  required out productRecord ,sProduct

Once you have “decorated” your code with attributes and doc comments, it is possible that you may never have to interact with the MDU ever again! But wait a minute … how does all this work?

Well, there is a new utility called dbl2xml, and this utility reads all of the information that is now contained in your source code and it creates an XML file containing just that information. You can then load that XML file into the method catalog using a command-line invocation of the MDU program. Of course you’ll probably automate these steps in the script that you already use to build your methods. The additional steps you’ll need will look something like this:

dbl2xml -out XFPL_SMCPATH:smc.xml SRC:AllMyMethods.dbl
dbr DBLDIR:mdu -i XFPL_SMCPATH:smc.xml

There is one “gotcha” with this new approach, and that is that you have to use the dbl2xml utility one time and process ALL of the code for all of the routines that are to be included in your method catalog. They don’t all have to be in the same source file, but the dbl2xml utility needs to process them all at once so that it can create the entire method catalog in a single pass. But that shouldn’t be a problem.

If you’ve ever done xfServerPlus development then I’m sure you’ll agree with me that this is a very nice new feature in Synergy/DE 9.3 … and it’s just one of many.

By the way 9.3 has been in beta for a while now. So if you want to check out the new features early, then why not help us to validate the release? Head on over to, log in to the Resource Center, and download the beta today.

It’s a good time to clean up your old Synergy DBMS data

By William Hawkins, Posted on November 11, 2009 at 4:27 pm

Synergy/DE is a pretty forgiving environment when it comes to dealing with fields containing unexpected data. For example, you can have a d field that is either all spaces, all numbers, or some combination, and Synergy/DE will treat the spaces as zeros. (For those of you old enough to remember DBL version 2, back then you could even increment a decimal field that was all spaces, resulting in a field that was all spaces except for the last character which was a !, and DBL would still see the decimal field as a numeric 1. When that occurred, it made for some interesting debugging!)

Now that the world of Synergy/DE for .NET is imminent (a beta version is available for those who are interested), the issue of data interoperability and ensuring that C#/ VB.NET/Framework-language-of-choice can work with Synergy data is also moving to the forefront. For those of you who have been using xfODBC and/or SQL Connection, some of these issues may be familiar, but a lot of developers will foray into this arena for the first time with Synergy/DE for .NET. This is especially true for those of you using xfNetLink .NET edition and looking to bypass the xfNetLink layer and use your code directly from Synergy/DE for .NET. (xfNetLink shelters you from these issues, as it can coerce inappropriate data into a usable native form.)

Synergy/DE basically has three “native” data types: integer, alpha, and decimal. Here are some of the issues that you’ll need to think about for each:

· Synergy integer fields (not to be confused with System.Integer fields) – No issue here; you really cannot store inappropriate data in a Synergy integer field. All you really need to watch for is storing an integer field that is all spaces. Of course, this is still a valid integer; it’s just not the zero value that you may have expected.

· Synergy alpha fields – Non-printable characters (outside the 7-bit characters space thru tilde) really need to be processed as a byte array and not thought of as a string (or alpha) field. But for most situations, alpha fields are relatively problem-free.

· Synergy decimal fields – Here’s your main problem area. I think of Synergy decimals as a special form of Synergy alphas that only contain numeric data and that you can perform math functions on. So, you need to ensure that decimal fields only contain the characters 0 thru 9, with the last character optionally being p thru y (to deal with trailing over-punch data). It’s not uncommon for decimal fields to be all spaces or to have spaces inside the field instead of zeros. It really depends on your code and the last time that you wrote the data to the file. It’s not all that uncommon to have data that’s over 10 years old and hasn’t ever been updated.

Another common issue is that Synergy/DE allows a d8 date to have a value of 00000000. In most other languages, this is an invalid date. If you don’t have a date, other languages use null, not zero, to indicate this. When you move your d8 date field to a datetime field in .NET, you’ll need some conditional logic to cope with this. Your code may also deal with a date field that contains a value such as 20090230, and it will just ignore the fact that this a bad date and display 02/30/2009 (U.S. format) or 30/02/2009 (rest of the world). Try to do this in other languages and you could be in for an unpleasant surprise.

Hopefully, most of the reasons for having inappropriate data in your Synergy DBMS files have been addressed over time. However, you may still have residual data out there that is technically “bad” but is hidden due to the forgiving nature of Synergy/DE. In our experience, adding logic to the intermediate layer to check and fix the data as it’s being pushed to non-Synergy/DE systems can add significant overhead to the application. It’s much more efficient to fix the data (hopefully as a one-off exercise) and modify your application to stop adding bad data to the Synergy DBMS database. For example, commands such as the INIT statement can help ensure that decimals and integers contain correctly initialized data. There are probably a few of you out there who have cleared a Synergy record and then realized that an ISAM key contained a number that got stored as a space and not a zero, so that the key contained records that were “out of order.”

To help, we have added a utility to CodeExchange (fixdata.dbl) that will allow you to apply a Synergy Repository structure definition to a Synergy DBMS file, forcing fields to contain valid characters and (for example) date fields to contain valid dates. We will be extending the utility to include other features, such as validation logic based on Synergy Repository definitions, so that it will be able to detect when a field contains an “out of range” value. If you already expose or plan on exposing your data to .NET, xfODBC, or SQL Connection, I encourage you to download and run this utility. If you have any comments or suggestions on this utility, please email me at


Subscribe to the RSS Feed!

Recent Posts Categories Tag Cloud Archives