I’ve written before (PDF) about the unique event model of the Synergy/DE UI Toolkit. For historical reasons, these events are often called “menu entries,” and even though they are handled in a synchronous, delayed manner you can’t have more than one such event pending at any given time. This didn’t cause too many problems back in the old days when they were almost limited to user-initiated events. But now that they’ve also become a standard means for converting asynchronous system-level events into synchronous Toolkit events, the need to generate more than one at a time has become something much more than academic.

Consider, for instance, an input field that needs to perform non-trivial processing at three points: when it is modified, when it is displayed, and when focus leaves the field. Each of these events can be hooked to a “method” routine, but if those routines need to do anything involving user interaction, then on Windows it needs to be deferred to the outer loop by means of passing an event to M_SIGNAL. Why? Because in an asychronous callback, the UI Toolkit can’t process Windows messages, so the user will not see any changes to the UI until after that event has been handled and the routine returns. Non-Windows platforms like Unix and OpenVMS don’t have that problem, but if your code is portable to Windows then you probably want to write it that way anyway.

Now, when the user types something in the field and then advances to the next field (via Tab, etc.), all three of those events will fire: first the “change” event, then the “display” event (to display the reformatted value after validation), then the “leave” event. All three associated methods will be called in that order. If each of them signals a menu entry event, then only the last one will be seen.

I’ve added a class to my Synthesis library to extend menu-entry signaling to maintain a queue of pending events. To make use of it, you replace M_SIGNAL with multi_signal. In the outer routine that consumes events, you change M_SIGNAL(…, D_REMOVE) (or testing g_select and g_entnam, after the older form), with a loop of calls to multi_remove, until it returns ^null. Each non-null return value will be a string containing an event that was signaled, in the order in which they were signaled.

To ease the transition, I’ve made multisignal somewhat compatible with M_SIGNAL. If the consuming code isn’t changed to the new paradigm, then it will still see the most recent event — whether it was passed to M_SIGNAL or multisignal.

See the test program (test_multisignal.dbl in the tests subdirectory) for an example of how to solve the scenario I related above.

With this feature, I’m putting a lid on Synthesis version 2.2.1. Any further changes will go in the next version.

Glynis Lyttle recently asked on the synergy-l mailing list about how to change the appearance of the drill buttons on Synergy/DE UI Toolkit input windows.  These are buttons that are placed to the right of an input field if it has a drill method (IDRILL_METHOD).  They’re always sized to the width of a vertical scroll bar, and contain the text “…” as show below:

Usually, these buttons are used to launch some sort of lookup function that will populate the field.  But Glynis has multiple uses for these buttons, and would like a way to indicate the distinction between launching the calendar control for a date field versus launching a new email to the address contained in an email address field.

The Synergy UI Toolkit does not provide a documented way to do this, but it can be achieved without resorting to any undocumented functionality.

The download below includes a new function named set_drill_text, which has the following syntax:

%set_drill_text(wndid, field, text) => success

where

• wndid is the ID of the input window
• field is either the name or the index of the input field whose drill button will be modified
• text is the new text for the button
• success is returned true if successful, false if not

The text of the button will be changed to the right-trimmed value of text, and the button will be resized appropriately.  The height of the button will not be changed, but its width will be set to the width of the text plus the width of two 3D edges as described by the current theme.  For example:

The function can fail for a number of reasons:

• wndid is not a valid input window ID
• field is not the name of a field in the window or a numeric value within the range of 1 to the number of fields
• the drill button for the field has not yet been created.  Either I_FRAMES or I_INPUT must have been previously called for an input set that contains the field.
• probably something else I haven’t thought of.

Note:  whenever the input set controls are recreated, the drill button text and size revert to their original form until you call this function again.  Input set controls are recreated whenever you switch the active input set for I_INPUT/I_FRAMES, or call I_INPFLD, as well as some cases of I_FLDMOD for that field.

It would be nice to be able to change the button to display an image instead of text.  Unfortunately, that’s quite a bit more involved and would require some non-Synergy/DE code (probably C or C++) to subclass the button’s WM_PAINT handler.  We’ll leave that as an exercise for another day.

I just released version 2.0.1 of my Synthesis library for Synergy/DE, which you can download below.

As you can see from the change log, this version grew mostly from the application of my tools for analyzing code coverage to my own creations.  By fleshing out my own unit tests to nearly 100% coverage, I shook out all nine corrections listed for this version.  So you can see from my own example that achieving 100% test coverage is not merely an academic exercise.  Code always looks more solid when it’s never executed.

These tests also revealed some areas in which my code coverage analysis needed improvement.  The six enhancements listed for the CodeCoverage class all came from those observations.

In fact, this version includes only one change that did not spring from my automated navel-gazing:  the addition of the ‘x’ option to Regex.  This, of course, allows white space, line breaks, and comments within a regular expression.  My other enhancement to Regex (optimizing out unnecessary code) was a result of code coverage analysis — because otherwise I might never have determined that the code removed was not necessary.

My code coverage only suffers from one major flaw, and that is not its own:  the debugger (on which it relies for sampling) sometimes exits prematurely when stepping through code (Synergex tr#30947).  You can tell when this happens by examining the coverage report for your mainline to see where coverage stops.  Unfortunately, one of the places where it regularly happens is within U_START, so analyzing an application that uses the Synergy UI Toolkit shall be an exercise in futility until such time as that tracker shall have been resolved.

However, I would highly recommend using this utility to analyze test coverage for code that doesn’t rely on the Toolkit – as well as for Toolkit code once that debugger bug is fixed.  It’s certainly pointed out some oversights in my code.

I have a few ideas on how to enhance this further:

• Currently, the command line tools only include sampling from one executable.  I’d like to add the ability to sample multiple runs, combining their statistics.  That way, you could sample a whole test suite and see how well your code is covered by it.
• Unreachable code is currently included in the analysis.  For instance, code that’s .ifdef’d out, or an mreturn at the end of a method that always throws an exception (the mreturn being required by the compiler).  I’m thinking of creating a way to tag code as “not to be included in coverage analysis”.
• Once analyzing Toolkit code becomes possible, I can foresee sampling taking a lot longer than it needs to, because most users wouldn’t want to include the internals of Toolkit routines in the analysis.  I’d like to create a way to specify the source files that you want to include in sampling, so that the sampler could simply skip over the rest.

Anything else that you’d like to see here?

Synergy/DE developers often have a mix of applications, some of which use the Synergy/DE UI Toolkit, and others that don’t.  The UI Toolkit doesn’t always play well with others, especially when it comes to things like allocating file channels or windows – it wants to control those operations itself.  So for a generalized routine, it’s useful to know whether the UI Toolkit has been linked into the current application, and if so whether or not it has been started.

The code you can download below includes a function named “GotToolkit”:

result = %GotToolkit(start)

where

result is returned with one of the following values (defined in gottk.def):
D_NO_TOOLKIT – This application has not included the Toolkit
D_TOOLKIT_AVAILABLE – Toolkit available, but not yet started
D_TOOLKIT_STARTED – Toolkit has been started

start is an optional argument indicating whether to attempt to start Toolkit (defined in tools.def):
D_NO_START – Leave things as they are (assumed if not passed)
D_START – Start the Toolkit, but only if available
D_START_ANYWAY – Start the Toolkit, attaching to it if not available

If instructed to start the Toolkit, result is the result of that operation.  In any case, result represents the current state of affairs when the function returns.

Be sure to include gottk.def within the data division of any routine that uses %GotToolkiit – this include file not only defines the literals used in the interface, it also declares the function to have a ^val return type.

In order to make the Toolkit truly optional on Windows and *nix, you must link gottk in an ELB.  Otherwise, because of the way global data section initialization works in Synergy/DE, you’ll be forced to link in the Toolkit also – which means you could never get a D_NO_TOOLKIT return value.  You can put gottk in your own ELB, or use the one built by the enclosed example.

This function should work across all supported Synergy/DE platforms: Windows, *nix, and OpenVMS.

I’ve included some tests in testtk1.dbl, testtk2.dbl, and testtk3.dbl.  For correctly building and executing these tests, I’ve included bld.sh (a *nix shell script) and bld.bat (a Windows batch file).  The tests succeed if you get a STOP message for each program, without throwing any exceptions.

On Windows, Synergy/DE provides access to the mouse cursor via the WP_CURSOR subfunction of W_PROC. Because this API is purely imperative, managing a wait cursor properly becomes a recurring problem in non-trivial applications. Typically, it begins like this (in pseudo-code):

set wait cursor
do lengthy process
clear wait cursor

But what happens if “do lengthy process” throws an exception that’s caught outside this code? You’ll skip right over “clear wait cursor” and leave the user unable to click anything. What you’d like to do is more like this:

begin
  set wait cursor
  do lengthy process
end

… and have the cursor reset whenever and however you exit the code block.

The downloadable code below demonstrates how to do this with the new object syntax in Synergy/DE version 9. The WaitCursor class sets the wait cursor in its constructor and resets it in its destructor. So you can code it like this:

begin
  data wait, @*, new WaitCursor()
  do lengthy process
end

The data statement declares a variable that has the scope of its containing begin-end block. The variable wait is declared as an object (@*). We could have more precisely declared it as @WaitCursor, but that’s just more typing (pun intended). It’s initial value is returned by the “new” expression, creating a new WaitCursor object. This invokes its constructor, setting the wait cursor. When wait goes out of scope, the last reference to the object is lost, and the destructor is invoked and the cursor is reset — no matter how you get out of the code block. If you want to preserve the cursor instead, you can just pass a reference to the object out of the block in another variable, and clear that variable when you no longer want the wait cursor.

But what happens if you have nested operations that, agnostic of each other, each want to set a wait cursor? When the inner one finishes, it will reset the cursor to normal. That’s not what you want at all. I solved this by adding a static counter to the class, so we only reset the cursor if our count of active WaitCursor objects gets back to zero.

Of course it’s possible that other code is manipulating the cursor without using our class. That could definitely interfere with our scheme, and should be avoided if possible. One common case is the set of message box routines in the UI Toolkit (U_MESSAGE, U_MSGBOX, U_WAIT). These routines always reset the cursor to the normal pointer so the user can use the mouse to click the buttons. If you want to have the cursor go back to what it was before these routines were called, then you’ll probably need to wrap them in your own version that saves off the current cursor state, calls the original, and then restores the cursor.

Dan Desch of Harland Financial Solutions pointed out a bug in my June 2001 post on checked menu entries in Synergy/DE. Synergy/DE has no built-in function to trim leading spaces from a string, so I had used the following snippet:

        while (.not. text(1:1))

          text = text(2,^size(text))        ;Trim leading spaces

which works fine so long as text contains at least one non-space character. Most menu entries fall into that category, except for those created by the “.BLANK” script command. In that case, this code goes into an infinite loop, because the overlay move blank extends to the length of the field, so you end up with exactly what you had to begin with.

Dan’s proposed solution was to branch around this logic if the entire field was blank, but I took this opportunity to optimize this code a bit. After all, performing iterative overlay moves of the entire field by one character doesn’t really jingle my elegance bells. So I replaced it with this algorithm:

        for ptr2 from 1 thru %trimz(text) ;For trimmed length

          if (text(ptr2:1))   ;Search for non-blank                   

             exitloop

        if (ptr2 .gt. 1)

          text = text(ptr2,^size(text)) ;Trim leading spaces

Synergy/DE optimizes the “for” statement such that %trimz is only executed once to get the right-trimmed length. If the field is all blank %trimz returns 0, so we’ll just exit the loop with ptr2 set to 1.

Now no matter how many leading spaces the field contains, we will do a maximum of 1 overlay move of the data. If the field contains no leading spaces (by far the majority of cases) then we’ve only executed one iteration of the for loop and the two if’s.

Naturally, if you have a need to do this sort of thing regularly, you could write your own function using this logic, and instead of moving the data over, just return the left-trimmed portion, else return the original, like so:

        for ptr2 from 1 thru %trimz(text) ;For trimmed length

          if (text(ptr2:1))   ;Search for non-blank

            exitloop

        if (ptr2 .gt. 1)

          freturn text(ptr2,^size(text)) ;Trim leading spaces
        freturn text

You can download the corrected version at the original post.

Over on SOB, apotheon has a couple of posts and some good discussion on Fibonacci sequences in various programming languages. As a combination response to those posts, programming exercise, and lesson in the language – I decided to tackle the problem in Synergy/DE. The download below contains a testing harness and three versions of a Fibonacci number function.

The first version of the function follows the mathematical definition, and closely resembles the recursive examples given by apotheon from other languages:

.function fib ,^val, reentrant

;

; Recursive Fibonacci number function

;

    a_index ,n ;Desired index in the sequence

;

.proc

    if (a_index < 2)

      freturn a_index

    freturn %fib(a_index-1) + %fib(a_index-2)

.end

Let’s look at some of the features of the Synergy/DE language as shown here. Synergy/DE requires the “%” character to prefix a function invocation, and uses the freturn statement to return a value from a function. So the functional syntax is not entirely pure, but workable. Functions are not reentrant (for historical compatibility) unless you add the “reentrant” qualifier as shown.

The one parameter to this function (a_index) has a type declaration of “n”. That means any numeric type will be handled as passed. If you pass it an alphanumeric, the argument will be cast as ASCII decimal, so “12″ works just as well as 12. You can use static typing if preferred (for instance, “i” to indicate integer), and in version 9 your options become stronger.

COBOLics (Hi, my name is Chip, and I am a COBOLic. I’ve been COBOL-free for 24 years.) will understand the “.proc” statement. It’s the equivalent of the COBOL “PROCEDURE DIVISION”, dividing the data declarations from the procedural code.

The “^val” in the function header indicates that this function will return its value on the stack instead of using a descriptor. It’s purely an optimization. However, it does limit our Fibonacci sequence to a length of 46 on 32-bit systems. But you’re likely to lose patience before you ever get there, as the dual recursion starts to hammer performance by about number 20.

As many people have demonstrated in other languages, you can optimize this function by using an iterative algorithm instead of recursion. This is shown in fib1 in the download below, which also uses a strength of the Synergy/DE language (grouped data) to shift the last two values computed throughout the iteration. The result? You can get 5000 iterations of a sequence of length 40 in about 30 seconds (on my computer).

However, if the function is called in sequence order, we can improve performance even more by caching our previous results. See fib2 in the download for how that works. It shaves another 5 seconds off that 5000 iteration run.

Note that I used a static variable for the data cache, but I don’t access the static values directly in the routine (even though that would give it a small performance boost). Instead, I take a snapshot of the cache at the beginning and work with the values in stack memory. Then I save the final values back to the static cache. Why go to all that trouble? Because the function is reentrant, so relying on static values could lead to trouble.

BUT, I hear you cry, this function doesn’t call any other functions that could result in recursion. Why worry about it?

Ah, but on graphical environments (like Windows), events can be fired between execution of individual program statements. So if we anticipate that anyone might need to generate a new Fibonacci sequence when a window gets clicked, for example, then we need to guard against relying on the content of static and global variables for longer than one statement. Thanks to records being treated as fields in Synergy/DE, I can copy all that data in one statement.

You may notice in the test harness that Synergy/DE allows you to invoke routines dynamically via %xsubr. BTW, you can pass an alphanumeric function name to %xsubr, too. But it’s more efficient if you pass it a numeric routine address, which can be looked up via %xaddr.

The harness also makes use of %u_cmdlinopt to parse command line options using the form:

-opt [arg, ...]

The %u_cmdlinopt function is included in the Synergy/DE UI Toolkit.

Any Synergy/DE programmers care to try to optimize this further, or provide a more elegant solution?

In Synergy/DE on Windows, the colors applied to some parts of your application are determined by the Windows registry, rather than by renditions settings in Synergy/DE. This means that most of the time a user can figure out how to control a given component’s rendition by looking in Windows Control Panel or the Synergy Control Panel.

Not so for disabled fields. Windows does not provide a visual means for altering the “gray text” rendition, and it forces that rendition on all disabled fields. There is literally no way around it, short of subclassing the display for edit controls. With the default background color being a darker gray, the text of disabled fields can be difficult to read, which has caused some frustration for Synergy/DE users and developers.

All Windows colors can be programmatically manipulated via the user32.dll function “SetSysColors”. The download below demonstrates how to modify the COLOR_GRAYTEXT system color to whatever color you would like. Note, however, that after you change that color, the change takes effect for ALL applications from this point forward for the current user. So, wield this weapon with care.

Blogged about this here.

Ah, the wonderful world of colors…so many ways to define them. In the Synergy/DE world, a color palette is defined as a set of 16 foreground/background combinations (yes, this seems a little restricted, but it was designed back in the days when it made a difference that the zero-based index could be stored in 4 bits). The foreground and background colors are defined as color codes from 0 to 255, just to create more numeric confusion. These codes are platform-specific, but on Windows platforms they are each defined as an RGB (red-green-blue) triplet. You can define them, as well as the palette entries, in the synergy.ini file in the [COLORS] section. You can also change them at runtime, using the %U_WINCOLOR UI Toolkit function with the D_SETCOLOR subfunction.

Thus our bridge from Windows colors to Synergy/DE colors. Windows system colors can be retrieved as RGB triplets using the Win32 API function “GetSysColor”. The downloadable code below provides a function that will set a Synergy color (0-255) to one of the Windows system colors. The included example then shows how to assign the newly formed color to a Synergy/DE Toolkit rendition.

Hey, at least we don’t have to worry about hue, luminosity, and saturation.

News flash! Synergy/DE version 8.3 (and later) includes built-in support for Windows system colors as color values above 255.

The ActiveX list provided in Synergy/DE includes a number of published methods that take the list column number as an argument. The column number does not directly map to the number of fields and/or prompts, because prompts only get a column if the field is not a checkbox. Thus, a bit of logic is required to programmatically determine the column number for a specific field.

The download below includes a function, %get_listfldcol, to which you pass the ID of the list and either the name or the number of a Toolkit field within the associated input window. The function returns the ActiveX list column number for the “field” portion of the field (i.e., not the prompt), or zero if the field is not found in the window.

Having trouble with the event-driven programming model and Synergy/DE? Well, at least you’re not alone. Many Synergy/DE applications have evolved from old DIBOL programs that were anything but event-driven. Making the transition to the event-driven model promoted by the Synergy/DE Toolkit can be daunting. To compound the problem, the event model inherent in Microsoft Windows contains some significant paradigmatic differences that can create even more challenges for the Synergy/DE developer on that platform.

I wrote a white paper for Synergex on this topic. You can find it in the Synergex Virtual Library on their web site at http://www.synergex.com/pdf/EventModelW.pdf. This paper discusses the event-driven programming model both in abstract terms and specifically as it applies to Synergy/DE. It also draws parallels between the event models in Synergy/DE and other language platforms.

The downloadable code below was created for the Synergex SPC 2002 to demonstrate the difference between modal and non-modal applications, and to give concrete examples of how to implement the latter. It also includes some useful Windows-specific features.

Note: this example was recently updated to make use of features available in Synergy/DE version 8.3, and will no longer work with previous versions.

The Synergy/DE Toolkit does not provide much support for container/child relationships between windows, with the exception of tab set containers. However, generic containers can be very useful for presenting a unified interface made up of diverse elements, such as input windows, lists, ActiveX controls, and even tab sets. Download the code below to obtain a suite of routines to enable container/child relationships, and to deal with the issues they present. Some of these issues include tabbing order, activation, clicking between child windows, and many others. These routines also contain some good examples of using advanced Synergy/DE features such as dynamic memory, RCB dynamic routine calls, macro expansion, window events, and more.

Most of the important code and comments can be found in container.dbl. The file container.def is an include to be used by client routines. The files sample.dbl and sample.wsc comprise a sample client program. Routines are best compiled using -T to avoid passing null arguments created by macro expansions.

Note: this example was recently updated to make use of Synergy/DE version 8.3 features, and will no longer work with previous versions.

Another note: Synergy/DE version 9 plans include a much more robust version of container windows that will also be cross-platform compatible.� If you can wait for that release, you’d be far better off.

UPDATE: Synergy/DE version 9 has been released, and it includes a much more robust version (which was written by yours truly).

To do very much at all with the Windows API, you need access to window handles. Window handles are very much like Synergy window ID’s, except that they aren’t. A window handle uniquely identifies each window on the desktop, including the desktop itself and any component windows (windows within windows). Most applications in Windows contain many component windows, and a Synergy application is no exception. Besides the obvious container window and Synergy windows, every input field is represented by one or more component windows. Field prompts and display-only fields also have unique handles, as do drill buttons, hyperlinks, and standard buttons.

The downloadable code below includes routines for retrieving the window handles of Synergy windows, lists, buttons, and input field components (field controls, display-only fields, prompts, hyperlinks, and drill buttons). For complete comprehension, see the copious comments contained therein.

Note: this example was recently updated to make use of features available in Synergy/DE version 8.3, and will no longer work with previous versions.

Sometimes in a UI Toolkit input window, when the user changes the value of a field, you want to be able to automatically skip over the next field without disabling it or changing it to read-only. However, you don’t want to do that if the user left the field by clicking on a specific field or by pressing Shift-Tab to go to the previous field.

The downloadable code below demonstrates how to determine what field the user is trying to access when the current field’s change method fires. The main-line program is in tfocus.dbl, which also contains the change method and the all-inportant routine get_focus_field. Routines for obtaining window handles are in gethandle.dbl, which is also featured in another topic, Retrieving window handles of Synergy components

Note: this example was recently updated to use features available in Synergy/DE version 8.3, and will no longer work with previous versions.

While Synergy/DE gives you control over the color of Synergy windows, it does not provide access to the color of the application background area. This always defaults to the current Display/Appearance setting for “Window background”.

The best solution to this problem is to place a borderless window at pixel position 0,0 and make sure that it fills the application space. In the example you can download below, we size the window to the size of the screen. This insures that even if the user maximizes the application window, no area of the background will peek out from behind our window. The example is written specifically for Windows platforms. The same approach would work for color-enabled cell-based environments, with the Windows-specific code commented out.

The only downside to this approach is that any text displayed in the application background (via WRITES or DISPLAY to the terminal channel) will not be visible, because it is occluded by our background window. Instead, you must display it to the background window after sizing the latter appropriately. Because of this restriction, you might think that the best solution would have been to subclass the application window, as in the topic “Subclassing Synergy windows”. But as it turns out, there is no way for your subclass procedure to gain access to the text that should be displayed in the window, and the inherited Synergy method for displaying the text would overwrite the background color for the area that the text occupies.

In most legacy applications written in Synergy (or DIBOL), you will find print routines that format the printed output in code. For example, something like

pline(1,6) = custno, "XXXXXX"
pline(9,38) = cname
pline(40,52) = ccrlm, "$,$$$,$$X.XX-"
call print

What a shame. Applications that use the Synergy Repository already have data formatting rules stored there. Furthermore, you can use the Synergy Composer to visually lay out windows that arrange the data into columns. If only you could use that same technology for printing.

Well, you can. Download the code below for an example of how to use Synergy UI Toolkit windows for formatting printed output. This idea was first invented by Stuart Brierley at Interchange Group (formerly Servasure) in Nottingham, UK. First, you display a data structure into an input window, which formats all of the fields. Then you use the w_info subfunction WI_XFR to extract the text from the window for printing. A simple but powerful concept.

You may object, “But I can’t use this approach with xfServerPlus, because it doesn’t support Synergy windows.” See Using dbr.exe for xfServerPlus services for a solution to that problem.

The example is written for Windows, using the Synergy Windows Print API. You could, of course, modify that layer of the routines to use other mechanisms that would be portable to other platforms. The example is also much simplified from many real-world printing systems that I have developed or been involved in developing. Some of the features that could be added to it include: lining up columns in a proportional font, vertical pitch control, automatic font sizing, and support for footers, among others. It does support changing the font within a document, multi-line detail items, and automatic page advance when the next detail item won’t fit. One of the most interesting features it contains is the use of input field display methods to handle special fields such as report date, time, and page number.

To build the example, set the environment variable CUSTRPS to “rpsmain.ism,rpstext.ism”. Compile printwnd.wsc using Script to printwnd.ism. Compile print.dbl and printwnd.dbl using the “-X” option (presume ^val functions). Link with printwnd as the main module, including WND:tklib.elb. The example previews a report based on the included “customer” data file, with option to print.

The ActiveX list control, available in the Synergy/DE UI Toolkit on Windows platforms, allows you to create columnar lists with button-like headings. Most lists of this sort on Windows also allow you to click on one of the headings to sort the list by that column. Unfortunately, because the Synergy list API loads items on demand and does not control the order of loading, the Synergy Toolkit cannot sort the items automatically.

There is a solution, however, as the downloadable example below demonstrates. Create an event method for the left click event on the list. In that method, make sure that the click occurred on a column heading, then signal an event back to the list processing routine to indicate what column heading was clicked. In response to that, restart the list and load the items in the proper order.

The example uses a sorted temporary file, but other approaches will work as well. If all of the items will fit into an array in memory, XCALL QSORT of the array would be the best and fastest alternative. Another option would be to have alternate keys on the original ISAM file that correspond to each of the possible sort orders.

Note: A far more excellent version has been posted on the Synergy/DE Code Exchange (axlsort.zip). It was written by yours truly, natch. You must be a supported HelpDesk customer to access Code Exchange.

Mostly for performance reasons, Synergy/DE’s xfServerPlus product uses a special version of the Synergy runtime for processing remote execution requests. This runtime is dbs.exe, which has all of the user-interface features stripped out, except for limited console I/O. In most cases, dbs.exe provides lightweight support for all you need to do on an application server.

However, some features of the Synergy runtime that were developed for user interface support can be used in a non-interactive way to provide useful server-side features. One example is an approach to creating printed output that uses Synergy UI Toolkit windows to format the fields (via I_DISPLAY) and then extracts the formatted text to send it to the printer (see Using UI Toolkit windows for print formatting). Unfortunately, Synergy Windows (and therefore Toolkit windows) are not supported by dbs.exe.

Not to worry. You can create a second xfServerPlus service that uses dbr.exe (the full Synergy runtime) instead of dbs.exe. Simply create a new service with a unique port number (the Synergy Configuration Program in version 7.3 and up is the easiest way to do this), and in the environment settings for the service set XFPL_DBR=1. This instructs xfServerPlus to use dbr.exe instead of dbs.exe. Connect to this service using its unique port number, and you’re in. The terminal number (%tnmbr) for the process is still -1 (indicating a non-UI mode). If you need to distinguish this process from a dbs.exe session, set your own custom environment variable(s) in the environment settings for each xfServerPlus service.

Of course, dbr.exe has considerably more overhead, both in memory/resource usage and in startup time, so you don’t want to use it if you don’t need it. For applications that require Synergy Windows support, however, it sure beats rewriting them.

Push-buttons on Synergy/DE Toolkit windows always have the same size (70 x 23 pixels), they are always uniformly arranged along either the bottom or right side of the containing window, and there is no API for modifying the text of the button’s caption. Download the code below to see how to use the Windows API functions to override the size, position, and text of a button.

Please read the warnings in the comments at the top of the resize_button function. This function depends upon certain behaviors that are not guaranteed to be in future versions of the Toolkit. Furthermore, any resizing of the containing window may cause the Toolkit to rearrange the buttons, and you’ll have to move them again. For a more reliable way to place buttons anywhere you like, see Using Containers to Place Buttons Anywhere.

The container-child relationship (see Creating container windows) can be employed to solve many different problems in Synergy/DE applications. This example from Paul Fenton of PHF Consultancy (with a little help from yours truly) demonstrates how you can use this principle to place pushbuttons anywhere you like on the window (on Windows platforms, of course).

The sample contains a test program and a routine called “button_anywhere” that allows you to create a standard-sized button at any row/column coordinate within a window. The only limitation is that the button cannot be in the tabbing order for the window, and so also cannot be the default button. However, you can still use keyboard (Alt-letter) shortcuts, or click the button with the mouse.