Open Menu

Synergex Blog

Old Dog … New Tricks … Done!

By Steve Ives, Posted on June 3, 2015 at 3:59 pm

The old adage tells us that you can’t teach an old dog new tricks. But after the last three days, I beg to differ! It’s been an interesting few days for sure; fun, challenging, rewarding and heated are all words that come to mind when reflecting on the last few days. But at this point, three days into a four-day engagement, I think that we may just have dispelled that old adage. For one this “old dog” certainly feels like he has learned several new tricks.

So what was the gig? It was to visit a company that has an extensive application deployed on OpenVMS, and to help them to explore possible ways to extend the reach of those applications beyond the current OpenVMS platform. Not so hard I hear you say, there are any number of ways of doing that. xfServerPlus immediately comes to mind, as do xfODBC and the SQL Connection API, and even things like the HTTP API that could be used to allow the OpenVMS application to do things like interacting with web services. All true, but there was one thing that was threatening to throw a “spanner (wrench) in the works”. Did I mention that the application in question was developed in COBOL? That’s right, not a line of DBL code anywhere in sight! Oh and by the way, until about a week ago I’d never even seen a single line of COBOL code.

Now perhaps you understand the reason that challenging was one of the words I mentioned earlier. But I’m up for a challenge, as long as I think I have a fighting chance of coming up with something cool that addresses a customers needs. And in this case I did. I didn’t yet know all of the details, but I figured the odds of coming up with something were pretty good.

Why all of this confidence? Well, partly because I’m really good at what I do (can’t believe I just said that), but seriously, it was mainly because of the fact that a lot of the really cool things that we developers just take for granted these days, like the ability to write Synergy .NET code and call it from C#, or write VB.NET code and call it from Synergy .NET, have their roots in innovations that were made 30+ years ago by a company named Digital Equipment Corporation (DEC).

You see OpenVMS had this little thing called the Common Language Environment. In a nutshell this meant that the operating system provided a core environment in which programming languages could interoperate. Any language that chose to play in that ball park would be compatible with other such languages, and most languages on OpenVMS (incuding DIBOL and DBL) did just that. This meant that BASIC could call FORTRAN, FORTRAN could call C, C could call PASCAL and … well you get the idea. Any YES it means that COBOL can call DBL and DBL can call COBOL. OK, now we’re talking!

So why is this such a big deal? Well it turns out that Digital, later Compaq, and later still HP didn’t do such a great job of protecting their customers investments in their COBOL code. It’s been quite a while since there was a new release of COBOL on OpenVMS, so it’s been quite a while since OpenVMS COBOL developers had access to any new features. This means that there isn’t a way to call OpenVMS COBOL routines from .NET or Java, there isn’t a way for OpenVMS COBOL code to interact with SQL Server or Oracle, and there isn’t an HTTP API … so don’t even think about calling web services from COBOL code.

But wait a minute, COBOL can call DBL … and DBL can call COBOL … so YES, COBOL CAN do all of those things … via DBL! And that fact was essentially the basis for my visit to Toronto this week.

I’m not going to get into lots of details about exactly what we did. Suffice it to say that we were able to leverage two core Synergy/DE technologies in order to implement two main things:

  1. A generic mechanism allowing COBOL code executing on OpenVMS to interact with Windows “stuff” on the users desktop (the same desktop that their terminal emulator is running on).
  2. A generic mechanism allowing Windows “stuff” executing on the users desktop to interact with COBOL code back on the OpenVMS system.

The two core technologies have already been mentioned. Outbound from OpenVMS was achieved by COBOL calling a DBL routine that in turn used the Synergy HTTP API to communicate with a WCF REST web service that was hosted in a Windows application running in the users system tray. Inbound to OpenVMS was of course achieved with a combination of xfNetLink .NET and xfServerPlus.

So just who is the old dog? Well as I mentioned earlier I probably fall into that category at this point, as do several of the other developers that it was my privilege to work with this week. But as I set out to write this article I must admit that the main old dogs in my mind were OpenVMS and COBOL. Whatever, I think that all of the old dogs learned new tricks this week.

It’s been an action packed three days but I’m pretty pleased with what has been accomplished, and I think the customer is too. I have one more day on site tomorrow to wrap up the more mundane things like documentation (yawn) and code walkthroughs to ensure that everyone understands what was done and how all the pieces fit together. Then it’s back home on Friday before a well deserved vacation next week, on a beach, with my wife.

So what did I learn this week?

  1. I really, really, REALLY don’t like COBOL!
  2. OpenVMS was WAY ahead of its time and offered LOTS of really cool features. Actually I didn’t just learn this, I always knew it, but I wanted to recognize it in this list … and it’s MY BLOG so I can Smile.
  3. Synergy/DE is every bit as cool as I always believed; and this week I proved it to a bunch of people that had never even heard of it before.
  4. New fangled elevators are very confusing for old dogs!

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.

Taking .NET to the cleaners

By Richard Morris, Posted on November 22, 2010 at 2:23 pm

Ding dong, “Laundry service”! Now you could be mistaken for thinking that I’m staying in a rather nice hotel, being called upon by the maid for my dirty laundry. Not so, I’m afraid, I’ll be taking my dirty ‘smalls’ home with me. But for one of our customers, this is their calling card. The customer is White Knight, based near London and their business is laundry, run by Synergy.

It’s true. People and many of them are well known celebrities, have their laundry collected every Monday and returned within a few days, cleaned dried and perfectly ironed. Some ten thousand “items” pass through the machines at this site and this is a small site. Their other sites handle in excess of two hundred thousand articles every week.

To manage this workload across all sites is a suite of Synergy programs running on a Linux machine. Traditional character based systems handle all aspects of the process from collection, cleaning through to delivery of the right items to the correct customers.

But things don’t always go right. So when the customers call in and say “you’ve washed the spots off my favourite pair of shorts” it all needs to be recorded and processed. This calls for a CRM (Customer Relations Management) system. And here is where I enter the story. White Knight has invited me down to assist them to begin to write a fully functional CRM system in Synergy. They want a Microsoft Windows desktop application with all the bells and whistles with access to new and existing Synergy data and logic. Easy!

So today we hatched a plan. Graham from White Knight was fully prepared for my visit with a functional specification, data layouts and design utilising xfServerPlus. “But for a desktop application?” I asked. “Why are we not using WPF (Windows Presentation Foundation) and .NET?” Because I’m not strong with C#, I know enough to do my web site!” Graham replied. Well, given the imminent release of Synergy v9.5 and the integration of Synergy Language within Microsoft Visual Studio 2010 it would be a perfect candidate. We’ve created our Visual Studio projects and begun to define our WPF User Interface in XAML. Our existing Synergy routines are being imported into a new class library project and we are crafting Synergy classes to facilitate the communication between our application elements. For those of you at SPC 2010 you’ll recognise this as the Model-View-ViewModel pattern!

And how did we do? Well I’ll update my blog over the next few days of how well we do, writing our first Synergy for .Net application…..

Starting Services on Linux

By Steve Ives, Posted on July 24, 2010 at 3:14 pm

For a while now I’ve been wondering about what the correct way is to start boot time services such as the Synergy License Manager, xfServer and xfServerPlus on Linux systems. A few years ago I managed to “cobble something together” that seemed to work OK, but I had a suspicion that I only had part of the solution. For example, while I could make my services start at boot time, I’m not sure that they were getting stopped in a “graceful” way during system shutdown. I also wondered why my “services” didn’t show up in the graphical service management tools.

My cobbled together solution involved placing some appropriately coded scripts into the /etc/rc.d/init.d folder, then creating symbolic links to those files in the appropriate folders for the run levels that I wanted my services started in, for example /etc/rc.d/rc5.d.

This week, while working on a project on a Linux system, I decided to do some additional research and see if I couldn’t fill in the blanks and get things working properly.

My previous solution, as I mentioned, involved placing an appropriately coded script in the /etc/rc.d/init.d folder. Turns out that part of my previous solution was correct. For the purposes of demonstration, I’ll use the Synergy License Manager as an example; my script to start, stop, restart and determine the status of License Manager looked like this:


# synlm – Start and stop Synergy License Manager


. /home/synergy/931b/setsde

case "$1" in



        echo -n "Starting Synergy License Manager"








echo -n "Stopping Synergy License Manager"


synd –q






$0 stop


$0 start






if ps ax | grep -v grep | grep -v rsynd | grep synd > /dev/null




echo "License Manager is running (pid is `pidof synd`)"




echo "License Manager is NOT running"







echo $"Usage: synlm {start|stop|restart|status}"


exit 1


exit 0

If you have ever done any work with UNIX shell scripts then this code should be pretty self explanatory. The script accepts a single parameter of start, stop, restart or status, and takes appropriate action. The script conforms to the requirements of the old UNIX System V init subsystem, and if placed in an appropriate location will be called by init as the system runlevel changes. As mentioned earlier, I had found that if I wanted the “service” to start, for example when the system went to runlevel5, I could create a symbolic link to the script in the /etc/rc.d/rc5.d folder, like this:

ln –s /etc/rc.d/init.d/synlm /etc/rc.d/rc5.d/S98synlm

Init seems to process files in a run level folder alphabetically, and the existing scripts in the folder all seemed to start with S followed by a two digit number. So I chose the S98 prefix to ensure that License Manager would be started late in the system boot sequence.

This approach seemed to work pretty well, but it was kind of a pain having to create all those symbolic links … after all, on most UNIX and LINUX systems, run levels 2, 3, 4 and 5 are all multi-user states, and probably required License Manager to be started.

Then, almost by accident, I stumbled across a command called chkconfig. Apparently this command is used to register services (or more accurately init scripts) to be executed at various run levels. PERFECT … I thought! I tried it out:

# chkconfig –-level 2345 synlm on

service synlm does not support chkconfig

Oh! … back to Google… Turns out I was something really critical in my script, and believe it or not, what I was missing was a bunch of comments! After doing a little more research I added these lines towards the top of the script:

# chkconfig: 2345 98 20

# description: Synergy/DE License Manager

# processname: synd

Low and behold, this was the missing piece of the puzzle! Comments … you gotta love UNIX! So now all I have to do to start License Manager at boot time, and stop it at system shutdown is use the chkconfig command to “register” the service.

And there’s more … With License Manager registered as a proper service, you can also use the service command to manipulate it. For example, to manually stop the service you can use the command:

# service synlm stop

And of course you can also use similar commands to start, restart, or find the status of the service. Basically, whatever operations are supported by the init script that you provide.

Oh, by the way, because License Manager is now running as a proper service it also shows up in the graphical management tools, and can be manipulated by those tools … very cool!

Of course License Manager is just one of several Synergy services that you could use this same technique with. There’s also xfServer, xfServerPlus and the SQL OpenNet server.

Challenges Facing Synergy Developers

By synergexadmin, Posted on May 19, 2010 at 4:09 pm

I was recently involved in a discussion concerning Synergy tools and technologies, and how our customers can best position themselves to take advantage of them. Somewhere along the way, I was asked for (or I volunteered – I don’t exactly remember) my opinion about the current software development landscape, and the challenges that face so many of our customers today.

I identified three areas of concern for our customer base and the future of their applications. And since you’re reading this, I assume that you are a Synergy customer, so hopefully what I had to say will strike a chord with you – either as a challenge you’ve already faced and overcome, or as an issue with which you’re currently grappling.

GUI is King

Yes, you’ve heard it a million times before, but unfortunately you’re going to keep hearing about it until you’ve updated the look and feel of your application. The continued survival of almost every solution boils down to implementing one of two main GUI choices: web technologies or Windows .NET (which means WPF, SilverLight or WinForms).

If you were reading that last part carefully, you’ll note that this discussion is not targeted solely at the *nix and OpenVMS operations; if you’re on Windows already, but are still using the same UI Toolkit displays that your app was using years ago (i.e., you’re not incorporating .NET technologies with the Synergy/DE .NET API), then you’re in the same boat as everyone else.

Arguments about the efficiency of character-based data entry are still valid, but they’re becoming less and less relevant (or realistic) – particularly if you’re using the speed of data entry as an excuse to allow the rest of your application to wallow. While you may have several “workhorse” data entry screens, chances are they make up a very small percentage of your overall application. Information displays, reports, “look-ups” or maintenance utilities have no reason to be tied down to a cell-based presentation.

GUI’s are simply too pervasive and too familiar to ignore, and purely cell-based software solutions cannot hope to compete for much longer. Even the most enthusiastic supporters of your application, the ones who can see beyond the green screen or the pseudo-Windows of Toolkit to the power of your application, will readily agree that it’s becoming more and more difficult to convince new hires (or prospective customers) of the superiority of your Synergy solution.

And I’m not just talking to the Synergy shops that develop vertical applications which are then distributed and sold; Synergy “end users,” the shops that have an in-house, custom-built Synergy solution, need to take note as well. Serious scrutiny of your Synergy application is coming with the next management or executive-level turnover.

Perception is Reality

We’ve all heard the term before, but I think it would be better stated as “People act on perception as if it is reality.”

One of the most common (mis)perceptions in today’s society is “newer is better.” It’s beat it into to us at every turn and in every advertisement, from New and Improved Acme glass cleaner to Next Best Thing flat panel televisions. And unfortunately, a cell-based UI isn’t doing you any favors in this department. Cell-based apps are generally looked at as “old,” “outdated,” “legacy,” or simply (my favorite) “DOS.” It’s this perception that gives rise to a host of other concerns and questions. Interoperability. Reliability. Power.

But perhaps the most dangerous questions are the ones that aren’t asked. If the users of your application generally see it as a throwback to a bygone era, then it’s possible – nay, likely – that it never even occurs to them to ask the right questions. Can it communicate with Brand X’s software? Can it display graphs that give a visual indication of the state of your sales? Does it offer a web service? Does it support ad hoc reporting? These questions are the sales points from competing software vendors, and rest assured that management has heard the pitches – whether it be the CEO at your customer’s company, or the management team of your own.

Remember: Your UI is the gateway to the power of your application. If it looks like something that was distributed on a 5 ¼” floppy, then it’s time to seriously rethink the front end of your application.
Now is the Time to Act

The current recession has made life difficult for almost everyone. Sales are down, money is tight, and thoughts of corporate expansion have been put on hold.

For the past two years or so, companies simply don’t have the money to invest in a brand new software solution, whether it be an ERP package to replace your in-house software, or a glossy, glitzy, Windows-and-SQL-based solution from your competitor. If you’re wise, you’ll look at this period as a reprieve from increasingly heavy competition, and as an opportunity to throw development efforts into high gear.

Use the time to ensure that your software has every last competitive edge when the wheels of the economy start moving again. Take advantage of the lull in sales and expansion, and incorporate the latest and greatest that Synergy has to offer. Put a GUI on your application – even if it needs to be one screen at a time. Use the Synergy.NET API to enhance the look and feel of the most commonly-used screens of your Toolkit application. Make the small investment in Synergy SQL Connect, and set up a data warehouse that can be used by SQL Reporting Services, or open up the data in your system to other commonly-used software by utilizing Synergy xfODBC. Create a web portal, add a web service or two, and take advantage of the APIs and web services of other software solutions to enhance your own.

In Conclusion…

I want it known for the record that I’m a huge fan of Unix/Linux, and absolutely love OpenVMS, so understand that I’m not advocating a switch to the Windows OS. Remember that you can still take advantage of the reliability and stability of both *nix and VMS backend systems, and just bolt on a Windows GUI client wherever appropriate. Heck, chances are that your users are already using Windows boxes running VT emulator software anyways, so there’s probably no hardware investment that need concern you.

And there are plenty of methods available to leverage your core systems and routines if you’re one of the many Synergy shops currently running a “green screen” solution. Investigate xfODBC, SQL Connect, xfServer and xfServerPlus. Install and play around with the (free) Synergy Data Provider for .NET, and get yourself acquainted with Windows- or web-based technologies, programming languages and development environments. Start cleaning up your code and separate that business logic from the UI components – it may not be as hard as you think.

A little research and a small investment in time will go a long way toward illuminating the path of a better, more robust and more marketable software solution.

Do you agree? Disagree? Have a story that’s relevant, or want to share your own challenges and solutions to the GUI problems or perceptions you’ve faced? Let us know about them, and let’s get the discussion started.

Testing Times

By Richard Morris, Posted on November 30, 2009 at 11:35 pm

Today, I am a Net Ninja!  Well that’s what my freebie t-shirt, procured from TechEd, says I am :).

To be honest I’m not sure what a Net Ninja is, but my understanding of a “Ninja” is a warrior, a fighter.  Someone who battles against adversity is pursuit of perfection.  Well, I feel a little like that at the moment.  Battle scared and bruised.  Not in the physical sense you understand.  I’ve been on beta testing duties, which brings both frustration and joy in equal amounts.

We currently have two products out in beta test at the moment.  The 9.3 beta contains some really cool new features, including encryption and a new “select” class.  The data encryption allows you to store your data in your SDBMS/RMS files in a form that can’t be read, even if you unload (or for you VMS guys – edit!) your files.  You can also encrypt your data between client and server for both xfServer and xfServerPlus.  The latter two ensure that any data you are transferring between server and client is “un-sniff-able!” 

Encryption is becoming more and more important in today’s world, and the ability to simply “switch on” encryption within your client/server Synergy applications is a really powerful capability.  I was stung earlier this year by identity theft.  I’d ordered a product off a web site, secure from the outside world because I ensured it was all done over HTTPS!  Suddenly I noticed credit card transactions that I didn’t know about – first port of call, my wife!  She knew nothing of the transactions and after some investigations I figured the only way my information could have been got at was from within the company – their employees!  Version 9.3 offers you the ability to encrypt your data at field, record, routine (xfServerPlus) or file level.  It’s extremely flexible.  When 9.3 is released ChronoTrack has been updated to provide examples of using encryption, and we’ll post it onto code exchange at the same time.

The “select” class is a cool and mega efficient, especially over xfServer, way of selecting data from a file that matches your selection criteria – your where clause!  I think Tod is preparing a blog about this as we speak :).

The other area of testing I’ve been doing is with our beta version of Synergy for .NET (not sure of the official title yet :)).  It was released last month.  This is really where the pain and ecstasy belong.  It’s such a cool product.  Being able to build applications in Visual Studio and have all the code in Synergy is very reassuring.  And my testing bed?  You guessed it, ChronoTrack!  It’s taken a lot of effort (the pain) to get to a point where ChronoTrack will build and run (the ecstasy) in the .NET framework, but we got there last week!  Our development team has worked tirelessly to build a product that’s going to allow our users to take full advantage of the .NET environment.  And what, I hear you ask, are the changes to the existing Synergy Code?  Well, to be honest, if the code didn’t interact with the UI then I changed no code.  I had to comment out a few references to statements (line INIT) that are not quite supported yet, but other than that the code remains the same.  It really is an endorsement of Synergy that we can build code that could have been written twenty years ago and run it in the latest and greatest environments without change.

If you want to beta test either version 9.3 or our .NET products then please sign-up and sharpen your blade.  It can be tuff, but the rewards are worth it.  And you do get ROI – you’ll have coded all your routines to support encryption and the select class before we even release the product, meaning you will be ready to take full advantage when the product is official!

If you are interested in seeing ChronoTrack running under Synergy for .NET then please let me know.  I may even produce a video about it!

I’m not sure I have made the grade as a “Ninja”, but my testing duties are complete.  I’m out and about visiting customers in the UK and Ireland this week with Nigel David.  If we encounter anything note worthy then I’ll keep you posted.

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.


Subscribe to the RSS Feed!

Recent Posts Categories Tag Cloud Archives