Synergex
 
  Synergy-e-News
 
  News and updates for Synergy/DE Developers :: November 12, 2010
 
 
 

 
IN THIS ISSUE
 

Synergy/DE 9.5 is here, offering exciting new possibilities for Synergy applications
New version delivers enhancements throughout the Synergy/DE tool set and provides seamless Synergy Language integration with Visual Studio 2010 and Microsoft's .NET Framework

Getting Started with Synergy .NET
???

Synergy/DE Tech Tip
Passing arguments by ^DESC, ^REF, and ^VAL

Quiz
Synergy/DE pros, see if you can answer this question!

Platform News
Read a selection of recent articles

Synergex Holiday Reminder
We’ll be closed December 24 and December 31
Modified Developer Support Hours
7 AM and 4 PM PST, from December 20 – January 2

 
 
 

Synergy/DE 9.5 is here, offering exciting new possibilities for Synergy applications
9.5 delivers enhancements throughout the Synergy/DE tool set, provides seamless Synergy Language integration with Visual Studio 2010 and Microsoft’s .NET Framework

Synergy/DE 9.5 was released last week and is now available to download. Synergy/DE 9.5 delivers enhancements to functionality, performance, and quality throughout the Synergy/DE tool set, including SELECT class improvements and Workbench enhancements. Whether you are developing for UNIX, OpenVMS, or Windows, version 9.5 will give your developers and your applications a step up.

Version 9.5 also launches the most exciting new feature set that Synergex has ever delivered. For the first time, you can compile, build, debug, and run your Synergy Language applications within Microsoft’s .NET Framework. Seamless Synergy Language integration with Visual Studio 2010 and the .NET Framework enables you to take full advantage of Visual Studio 2010, which includes a rich debugging experience, and noteworthy features such as IntelliSense, UI designers, and performance profiling. And you can utilize use the .NET Framework and third-party components, such as those from Infragistics and DevExpress, to extend your applications to new heights.

Does your current solution need a new presentation layer? Do you want it to integrate with C# or Visual Basic assemblies? Or how about creating .NET class libraries with your business logic for other .NET programs to access? Synergy/DE 9.5 takes you to a whole new level of possibilities.

“To have a business-oriented language available in the .NET Framework so that if you have a business task to do you can choose to do it in DBL rather than C# is a great advantage.”
Dan Desch
Harland Financial Systems

“I personally liked the Select improvements and the ability to write a DLL for native data access. … We updated a program that performed searches on a very large dataset. Before the Select class, it might take 20+ minutes. After we introduced the Select, our searches took about 20 seconds. … I definitely recommend that any Synergy user upgrade [to 9.5].”
Erik Read
Jack Henry & Associates, Inc.


View the press release about Synergy/DE 9.5

Read more about Synergy/DE 9.5

Upgrade today

Getting Started with .NET

As many of you are aware, Synergex recently released Synergy/DE 9.5, and with it, a new set of features called “Synergy .NET” became available. Using the included dblnet compiler, Synergy developers can now create libraries and applications that run natively in the .NET Framework. This means a whole new world of possibilities for Synergy solutions, which can now take advantage of .NET user interfaces (written for WinForms or WPF, for example) as well as libraries written in other languages. It even means that Synergy functionality can now be exposed to applications created or modified with other .NET languages.

With such vast potential for this exceptional new product offering, we wanted to put together an article that could help give you a jumpstart on “getting started with Synergy .NET.” Knowing that complete volumes of information could be written on the subject, I foolishly agreed to write it.

The problem? Complete volumes of information could be written on the subject. I suddenly found myself with an ocean’s worth of subject matter, a looming deadline, and no good place to start. Should I talk about what it is … and what it isn’t? Should I pick a single, specific use case for Synergy .NET and focus my attentions there — but also knowingly run the risk of making the article completely useless (or redundant) for some of our readers? Or should the article paint a picture of Synergy .NET using broad strokes, but again, risk that many of you already know the basics?

Awash in possibilities, I decided to simply begin at the beginning.

Let’s Get Started with Synergy .NET…Later

Whether you’re thinking of migrating your entire application to Synergy .NET, or focusing on porting specific, often-used functionality, or simply making some of your Synergy routines available to other .NET programs, you’re probably going to be starting at the same place: your current solution. Once you’ve decided that Synergy .NET is your destination, remember that knowing where you want to go isn’t really a step at all; it’s just the impetus that gets you out the door and on your way. The first step is in knowing how you’re going to get there, which routes are best, and which turns to avoid.

This article is intended to provide a roadmap that gets you started on your journey to a Synergy .NET solution — or at least out of the driveway, down the road, and pointed toward the highway. I should mention that it also assumes you’ll start small, perhaps with a few core routines from a “base library” and maybe a specific piece of functionality (a customer search or listing routine, for instance) and also that you’ll just be trying to create a DLL assembly (the .NET equivalent of an ELB or shared image) for use with future Synergy .NET applications, current .NET applications, or both.

Hence, this article will be stopping short of creating an actual UI or diving into Visual Studio; the number of possibilities, the varying needs from one company to the next, and the mechanics of working with either WPF or WinForms is beyond the scope of a single article. (We’ll get into some of these more advanced topics in a future article.)

You may also note that at no time is it suggested or required that you employ Synergy objects! You can move a regular subroutine or function to .NET just as easily as you can move a Synergy class and method.

And with that, let’s get this show on the road…

Getting Out of the Driveway

Route Summary
  1. Install Synergy/DE 9.5
  2. Select a small sample of core library routines.
  3. Prototype selected files with dblproto.
  4. Compile code using dbl, then link with dblink.
    • Do not use -qrelaxed compiler options.
    • Use -qstrict or -qcheck compiler options.
    • Address any issues.
  5. Use dlbnet to compile and build the code into a
    .NET library assembly (dll).
    • If errors, conditionally replace unsupported
      features.

If you’ve been to the Synergy/DE Resource Center and taken a look at the available downloads, you’ve probably noticed that there is no listing for “Synergy .NET.”  That’s because the term “Synergy .NET” is simply a way of describing the specific use of the Synergy Language within the .NET Framework. When you’re ready to start moving toward Synergy .NET, what you’ll be downloading (or have already downloaded) is “Synergy/DE 9.5.” Really, that’s all you need when you want to start using Synergy programs within the .NET Framework. (There’s a separate small download called Synergy Language Integration for Visual Studio, but we’ll talk about that much later.)

It’s important to remember that the heart of Synergy .NET is Synergy/DE 9.5.  In fact, as of version 9.5, you’ll find that Synergy/DE now includes two Synergy compilers: dbl and dblnet. The first compiler outputs traditional .dbo files that can then be linked, while the second compiler wraps the compiling and linking into one step, producing .NET .exe or .dll files.

The point, however, is that when you’re ready to take your Synergy app for a test drive on .NET, the best place to start is not with Visual Studio and Synergy .NET development, but with the same tried-and-trusted techniques you’ve always used.

Begin by installing Synergy/DE 9.5 and trying to compile and link your code. While this may sound like a no-brainer step that might easily be skipped (particularly if you’re already compiling under version 9), don’t be fooled!  In addition to support for “Synergy .NET,” Synergy/DE 9.5 also includes an enormous list of incremental updates to the compiler. There’s a good chance that you’re going to have compiler errors that you’ve never seen before, all of which will highlight issues that a) you didn’t know you had and b) probably caused runtime errors in a production environment. And since an error in traditional Synergy is also going to cause an error in Synergy .NET, it’s best to fix it now — before you’re already on the highway and surrounded by the more complex (and possibly unfamiliar) .NET development environment.

Shortcuts to Nowhere

This also might be a good time to warn you about using the shortcut that some version 9 compilations have taken in the past — and one that your app may still be using even now. Beware that the -qrelaxed shortcut dead-ends long before the on-ramp to the .NET freeway. Double-check your build scripts to make sure you’re not using -qrelaxed compiler options; if you are, you’ll need to rebuild without them. In fact, just to be certain you’re doing things correctly and heading in the right direction, you’ll want to set either the -qstrict or -qcheck compiler option as well.

It’s also quite possible that you’ve been using a different, but ultimately terminal, shortcut as well: avoiding prototyping your code. In fact, this “shortcut” is so extremely popular that it’s really more of a bypass. After all, not only is it still used by lots of folks running version 9 applications, it’s also used by everyone running version 8 or earlier. Unfortunately, this “Prototyping Bypass” doesn’t connect with the “.NET freeway,” and it’s possible that there will be some sort of a toll to pay before you can exit back onto the main road…

Minor Road Repair

Let’s assume that your initial compilations have returned a few errors, and that dblproto pointed out a few problems as well … perhaps even more than a few. You may get a sudden urge to find the nearest shortcut and go around the issues, or to simply turn around and head home. You must resist this urge!

The fact is that most of the errors you encounter will involve only minor fixes, and solving one will actually solve many others; one simple tweak may remove 10, 20, even 30 or more errors from your initial list. Also, keep in mind that many of these “code potholes” being pointed out by the new compiler and prototyping will result in runtime errors — and are likely already doing so in your current application!

Conditional On-Ramp Ahead

You’ve taken care of everything, and your code is now compiling and prototyping cleanly under version 9.5. You’ve made it to the on-ramp, and it’s time to see what .NET thinks of things.

At this point, you may be tempted to jerk the wheel and move directly into the fastest acceleration lane. It’s really a decision you’ll have to make on your own, but you should weigh the amount of baggage you’ve got in the trunk (or the boot, if you prefer) before gunning the engine.

If your selection of source code is pretty small, or you’re sure that it isn’t using Synergy-supplied libraries such as tklib.elb (UI Toolkit) or synxml.elb (XML API), you can probably merge pretty easily. However, knowing what awaits you ahead is always a good idea, and there’s a step you can take here that can assure you of fewer problems later — even if it takes a few extra minutes now. At the very least, you’ll learn a skill that you can use for quick checks of code later on.

You can try using the dblnet compiler on your code before you ever launch Visual Studio. After all, it’s the same compiler that Visual Studio will use when you select “Build Solution” from its build menu. However, whereas Visual Studio will populate the arguments for the command automatically, you’ll have to do it manually from a command prompt for it to work. But knowing what Visual Studio is doing when it builds your application is a good thing, so let’s take a look at the command and how you’d use it to build a .NET library assembly (DLL) from your code.

If you wanted to create an assembly called myLib.dll, which contains the functions and subroutines located in the source files myRoutines1.dbl and myRoutines2.dbl and at least one of the routines used UI Toolkit functionality, you’d type the following at the command line:

dblnet -ref=Synergex.SynergyDE.tklib.dll -target=dll -out=myLib myRoutines1.dbl myRoutines2.dbl

The result of this command will either be a file named myLib.dll, which can then be included in any .NET project (Synergy or otherwise), or a list of .NET-specific warnings or errors.

If you’ve received some errors, it’s simply because your code includes something that’s not supported in the .NET environment. The best thing to do is to analyze the offending line(s) of code and decide whether it’s a) necessary to the .NET solution, b) replaceable with code that functions in both .NET and traditional Synergy, or c) something that needs to be conditionally compiled with an alternative .NET-only format.

For example, pretend your code issues a dll_call command. This is something that will compile cleanly under traditional Synergy but will cause an error with the dblnet compiler. You do a little digging in the Synergy Language Reference Manual and find that DLL_CALL has a .NET-only counterpart called DLL_NETCALL. At this point, you can simply conditionally compile your code for use in either environment by using the DBLNET compiler directive:

.ifdef DBLNET
    dll_netcall(etc…)
.else
    dll_call(etc…)
.endc

Merging Onto the .NET Freeway

Once you’ve taken the necessary steps outlined above, you’re truly ready to start building speed with your application’s migration to .NET.  You’ve at least learned the routes you’ll need to take for any remaining subroutines and functions. And while the UI development and transition of mainline routines will be slightly different, many of the same paths will still be used.

I’ll be following up in the coming weeks with “Part II” of this article, which will focus on setting up and using Visual Studio with your Synergy code. However, if you’re just dying to dive in early, then it’s at this point that you’ll want to make sure you’ve first installed Visual Studio 2010, and then downloaded and installed Synergy Language Integration. Launching Visual Studio will now show you a new set of project templates for Synergy/DE. (Note that if you haven’t defined your Synergy environment settings at the system level, you’ll want to launch Visual Studio from the Visual Studio Command Prompt. Make sure you’ve SET the environment variables you’ll need, preferably with a batch file, and then type DEVENV at the prompt.) You might begin by creating a new Class Library project and then referencing the source code you used in your “.NET try-out.” Or create a console application project, reference the library assembly you’ve already created, and see how it works…

Until next time, safe driving!

Synergy/DE Tech Tip
Passing arguments by ^DESC, ^REF, and ^VAL

Traditional Synergy enables you to pass arguments to subroutines and functions in three ways: by descriptor (BYREF or ^DESCR), by reference (^REF), and by value (^VAL). Arguments to Synergy Language routines are normally passed by descriptor, which is the default. ^REF and ^VAL arguments are used primarily when passing arguments to non–Synergy Language routines. When using ^REF or ^VAL to pass arguments to Synergy Language routines, the argument must be declared as ^REF or ^VAL in the receiving routine.
 
Synergy .NET (included in Synergy/DE 9.5) enables you to pass arguments to subroutines and functions in two ways: by descriptor (BYREF) and by value (BYVAL or ^VAL). Arguments to Synergy .NET routines are normally passed by value, which is the default. As Synergy types in .NET are objects, passing these types BYVAL still allows the contents of the type (not the descriptor itself) to be modified. OUT and INOUT arguments of .NET types default to BYREF.
 
The primary difference between these three ways of passing arguments lies in how the value of the argument is treated if it is updated by the routine. When an argument is passed by descriptor (BYREF/^DESCR), if the variable associated with the parameter in the receiving routine is modified, upon returning from the routine, the value of the argument in the calling routine is also updated. A ^REF argument is treated the same way. However, when an argument is passed as BYVAL/^VAL, the value is changed only locally­—not in the calling routine. In other words, passing a reference type BYVAL/^VAL allows members of the caller’s type to be changed, but the reference to the type cannot be changed. Passing a reference type BYREF/^DESCR allows both the reference and the members of the caller’s type to be modified.
 
The following example illustrates this difference. The value of the ^REF argument is updated in the calling routine, whereas the value of the ^VAL argument is updated only locally (i.e., within the subroutine).

main 
 
record
  ttchn    ,i4    ,1
  var1     ,i4
  var2     ,i4
 
proc
  var1 = 10        ;var1 and var2 are both 10 to start with
  var2 = 10
 
  xcall mysub(^ref(var1), ^val(var2)) ;pass var1 by reference
                                      ;pass var2 by value
  open(ttchn, o, "tt:")
  writes(ttchn, "^ref is " + %string(var1) + " ^val is " + %string(var2))
  close ttchn
endmain
 
subroutine mysub
  ^ref(arg1)  ,i4   ;declare arg1 as ^ref in routine
  ^val(arg2)  ,i    ;declare arg2 as ^val in routine
 
proc
  arg1=arg1 + 20    ;we add 20 to both arg1 and arg2
  arg2=arg2 + 20
  xreturn
endsubroutine
The output from this program is
  ^ref is 30 ^val is 10

[Top]

Quiz
Synergy/DE pros, see if you can answer this question!

What is the output of the following program? See if you can figure it out without running it.

main
proc
    open(1,o,"TT:")
    writes(1,unmangle
  &  ("ccbiagagebaaakefahepejchfjbnaealfiaoehcfdbaafnebfafnbbejaaepbhaaaabo",
  &  "what does it say?"))
end

function unmangle
in req text, a
in req key, a
record
    index, int
    kindex, int
    new, string
proc
    new = ''
    kindex = 1
    for index from 1 thru ^size(text) by 2
      begin
        data h, a2
        data h2, a2
        h2 = hex(decml(text(index:1)) - 97, 1)
        h(1:1) = h2(2:1)
        h2 = hex(decml(text(index+1:1)) - 97, 1)
        h(2:1) = h2(2:1)
        new = new + char(^x(h) .bxor. ^i(key(kindex:1)))
        incr kindex
        if (kindex > ^size(key))
          kindex = 1
      end
    freturn new
end

Which answer is correct?

a. "My hovercraft's quite full of eels"
b. "what does it say?what does it say?"
c. "Upgrade to Synergy/DE 9.5.1 today!"
d. "Any questions, ask Richard Morris."


Click here for the answer and explanation.

Platform News

Windows OpenVMS Unix

Synergex Holiday Reminder

We will be closed on December 24 for the Christmas holiday, as well as December 31 for the New Year’s holiday. If you anticipate needing our assistance on any of these days, please contact us at synergy@synergex.com to make arrangements.


Modified Developer Support Hours

Synergy/DE Developer Support will be available between the hours of 7 AM and 4 PM PST, from December 20 – January 2 (with the exception of holiday closures mentioned above). If you anticipate needing our assistance outside of these hours, please contact us at synergy@synergex.com to make arrangements.