S/ENL - The Sprezzatura Electronic Newsletter

(All the RevSoft News That's Fit To Print (And bits that probably aren't as well...))

Welcome

Welcome to this issue of SENL! We know it’ll be a slight shock getting this quote “so soon after the last issue” but we had so many requests to get the OLE article finished and so many cool things have been happening that we thought we’d get this out quickly and then sit back and review how we’re going to proceed with the journal from hereon in.

We’re not long back from conference and as has been reported this was one of the most successful conferences ever. The location was fantastic – Seattle has a wealth of things to interest people like myself who are interested in decent tasting beers – and the T-Shirt stores give Sacramento a run for its money. (Though Sacramento wins by a nose). Breakfast at Pike’s Place Market is such a cool way to start the day and the range of good food places was awesome – “awesome like a hot dog” to quote an English comedian. … “And your President's going to be going (American voice) "Can you tell me, astronaut, can you tell me what it's like?" "It's awesome, sir." "What, like a hot dog?" "Like a hundred billion hot dogs, sir." – Eddie Izzard.

The conference itself had a range of technical information ranging from the introductory through to the seriously technical. This time it seemed that people had done their homework more on the sort of presentations that they’d like to see and unlike in previous years no one was seen to walk out of a technical track complaining that the presentation was too technical.

The social side of the conference once again added extra value as people we hadn’t seen for years appeared. It’s always fun hanging with our peers and this conference was no exception. The themed party this year provided an excuse for a noisy clique of Sprezz bods and ***** bods (names changed to protect the guilty) to hang around practicing their cockney rhyming slang and out joking each other. By the end of the evening onlookers were drawn to the group like smaller planets being sucked into a black hole. We haven’t laughed so much in a long time – thanks to those who helped make the evening and all y’all know who you are J

We’ve had a number of requests to publish our proceedings publicly from people who weren’t able to attend the conference for various reasons – for these people we have some bad news and some good news!

The bad news is that it is policy that Conference Presentations aren’t released to non-attendees until some considerable time has elapsed since the show. This makes sense if you think about it. The presentations are created for the show – that’s the driving force behind their production. People take the time and trouble to attend the show to get this information. The show costs money and a great deal of time to put on and as a rule doesn’t even break even for Revelation. The less people who go the more of a loss is made. If you didn’t need to attend to get the materials then the show would make even more of a loss as more delegates stayed away. This would probably lead to cancellation of sponsorships and ultimately cancellation of the show. In turn this means that no one would prepare presentations – so everyone would lose out!

The good news is that Revelation have given us permission to document the meat of one of the most technical presentations of the conference – Carl’s presentation on using Windows Common Controls in OI 7.1+. The reason for this is that delivering “Windows Standard” software is necessary in today’s climate and people expect certain features. With Carl’s help you’ll be able to spruce up your applications in no time! So a big vote of “Thanks” to Revelation for their permission on this!

As I type we’ve just started the beta cycle for version 8.0 of the product and this truly is a landmark release for a LOT of people. One of the most significant inclusions is going to be AREV32 – a console app version of AREV but with all of the 16 bit DOS limitations removed. So if you’ve got a client who just WOULDN’T move to OpenInsight because of the work involved you can finally move them without changing them! Put simply, AREV32 uses OpenInsight’s “CTO” technology to pretend to be an AREV app running under OI. That immediately removes the 64K limit and the EMS problems! There is very little work involved in actually moving to AREV32 and more details will be made available as we get closer to the release date.  Suffice to say for now that your clients will have to buy Developer Class licenses of OI and that they’ll then be running AREV within OI. That ideally positions them for a phased transition to OpenInsight!

To celebrate the introduction of AREV32 we’ve decided to include an AREV tip to complement our OLE article – multiple feline fur removers and all that. This is a cute little trick which allows you to perform mail merges from AREV using Word for Windows… didn’t Cogent do something with WordPerfect like that all those years ago? Plus ca change plus ca la meme chose…

The toolset has been extended to take advantage of the addition of Drag and Drop into the product and finally now that we’re in Beta Carl is free to catch up on other projects. And we’ve got a LOT of partially finished projects here at Sprezz Towers… one of these is showcased in Aaron’s article on our new Linear Hash Dump utility. We’re just working out new licensing packages and expect to be releasing a slew of free software into the Rev community by summer.

We’re starting to hear rumours of a UK Revelation Conference to be held in London in May. This will only be a single day and a single track apparently but it is hoped to have at least 5 presentations – at least 3 of which will be seriously technical.  So if any of our global readership are planning a London holiday this year think about May!

It would seem that not everyone is on the Revelation EMEA newsletter mailing list because at the Sprezz presentations in Seattle people kept asking about code snippets such as $USES. These compiler enhancements were the subject of a technical article in the August ’06 newsletter. As the authors of the original piece we’ve expanded it slightly for this SENL but you might want to check out the Newsletter back issues in case there’s anything else you’ve been missing! They can be found at http://www.revsoft.co.uk/devnewsletters.htm.

In closing it will doubtless come as a huge surprise to you after reading this SENL that we’ve finally gotten around to buying SnagIt for screen dumping – what a cool tool! So our apologies in advance if we’ve become a little “snap happy”.

Enjoy this SENL we truly hope that you’ll find something in it that is of value to you.

Regards
Your friends at Sprezz

[top]

Compiler Enhancements – Andrew P McAuley

The compiler is the compiler is the compiler and has been pretty much the same since the introduction of Revelation B. Sure along the way new opcodes have been added to support new system common and new at variables but it has remained pretty much the same until very recently! The release of 7.2.1 brought with it a number of compiler enhancements which serve to make life easier for the serious developer. This article documents these changes.

Precompiling
The introduction of the CTO provided the much needed excuse to enhance the compiler with precompiling technology. This is something that we’ve been asking to have included in the compiler since the year dot. Our motives are a tad obscure – reasoning it would be fun to allow people to compile in their native language for example. However the CTO provided a practical excuse for its inclusion.

 Put simply precompilation allows the developer to stipulate that a program (or programs) be run before the main compiler is run. This allows the developer to make changes to the program before it is compiled. As a simple example of what could be achieved, the developer could write a program that translated French words into their English equivalent before compiling.

A new row has been added into SYSENV called CFG_PRECOMPILER. This is a value mark delimited list of programs to call as a precompiler. Note that there is no practical limit to how many such precompilers can be called but bear in mind that once the programs are entered into CFG_PRECOMPILER they will be called for the compilation of all events and programs. 

If you’d like to be a little more selective in when and if you call your precompiler you may make use of the new PRECOMP #PRAGMA predirective. This allows you to specify that a specific program should be called as a precompiler when compiling this routine or event.

The syntax is

      #PRAGMA PRECOMP PROGRAMNAME

In all cases the precompiler should be written to accept two parameters. The first is the source code itself and the second is the name of the routine being compiled. So if you decided that you were bored of always having to declare certain functions and subroutines you could write a precompiler such as this :-

Note that the debug is there just for the purposes of this article! So now let’s write a routine to make use of this precompiler :-

And let’s compile this routine – which because of the above debug will drop us into the debugger.

A little side point to mention here that will get cheers from a number of developers – the debugger now remembers your MDI child placement preferences between sessions. So we’ll step over the next two lines and see our code inserted into the output.

And carry on – compilation completes.

So we haven’t declared Get_Property as a function ourselves – nor have we declared MSG as a subroutine. Yet let’s go to the system monitor and RUN the program and voilà! No errors:-

Displaying comments
If you wish to display comments during compilation you can use the COMMENT pragma which has the syntax:

      #PRAGMA COMMENTS Comments here along with replaceable placeholders

The replaceable place holders are:

At the moment this only works with the old editor not with the  Editor+. So revisiting the code above and adding comment pragmas then compiling we get

Saving expanded code
If you wish to save off the final result of all of the precompilation options so that you may examine it  you may use the OUTPUT pragma. This directs OpenInsight to save the ultimate program that will be compiled into the specified file and row. The syntax is:

      #PRAGMA OUTPUT FileName RowId

And the resultant code in SYSLISTS

Ensuring comments remain in Outputted Code
By default the system removes the text of comments before submitting the program to the compiler. This makes compilation slightly faster as the compiler does not have to process comment strings. This means that your saved OUTPUT code won't contain comments. To ensure the comments remain you use the COMMENTCOLLAPSE pragma. This has a value of ON or OFF. The default setting is ON. To ensure comments remain use OFF:

      #PRAGMA COMMENTCOLLAPSE ON|OFF

So with Collapse ON (the default)

The resultant output is

And with it OFF

The resultant output is

Squeezing the last ounce of performance from a routine
When programs are compiled a linemark is inserted between each line to assist in debugging. This means that a 1,000 line program will have 1,000 linemark opcodes. If performance is critical then these may be removed using the LMCOLLAPSE pragma. This takes an ON or an OFF argument and the syntax is:

      #PRAGMA LMCOLLAPSE ON|OFF

This is especially useful when $Inserting large blocks of code. When debugging this would stop at each line of the $Insert. Using LMCOLLAPSE would allow the programmer to step over the $Insert with one keystroke. For example:

      /// Turn on linemark collapse for inserted code
      #pragma lmcollapse on
      $insert sysprocs, fserrors_100
      $insert syserrors_1000
      /// Turn off the $insert linemark collapse
      #pragma lmcollapse off

Ensuring Repository Tracking
The compiler has been enhanced to keep track of the "Uses" relationship when a subroutine or function is called. Historically this only happens when the DECLARE statement is used. Now the act of CALLing a routine ensures that it is tracked.

So if we were to look at the Entity Relationships window for the DELETEME object code we’d see that it uses several  stored procedure executables :-

If you wish to link in other entities to ensure complete deployment using the RDK or checkout you can now tell the compiler that this routine uses specific entities. For example, say your program is referenced in an external document and you want to ensure that this document is deployed with the program. You may now accomplish this using the $USES compiler predirective to ensure that this is tracked in the repository.

This has the syntax:

      $USES EntityID

where entity ID can have one of the following three forms:

For example:

      $USES @APPID*DOC*WINWORD*CONVERSIONUTILITY

Compiling this and examining the Entity Relationships gives me

Multiline Concatenation/Nested inserts
Two longstanding compiler bugs have been fixed. It is now possible to nest inserts without messing up line counts. In addition you may now have multiple lines concatenated into a single line to improve program legibility.

For example:

Which compiles as

So as you can see – quite a lot of movement on the compiler front!

[top]

Windows Common (and not-so-common) Controls and OpenInsight – Carl Pates

Out of the box OpenInsight (OI) provides developers with access to all the essential user interface controls, such as edit controls, listboxes, checkboxes and so on. For the majority of tasks this is quite sufficient, but a situation invariably arises when the standard set of control types is just not enough and a more elegant solution must be found – the user interface must be extended.

In some cases this may simply be a matter of using one of the many “new” controls supplied with 32-bit and subsequent versions of Windows (the so-called “Common Controls” such as Progress Bars and TreeView controls) while in other cases it means using a “custom control” supplied by a 3^rd party and written in another lower-level toolset such a Visual C++ or Delphi.

With the release of OI 7.2 a new method of embedding controls has been added to OI that provides access to virtually any Windows control, or in the case of OIL, any control that is supported by the MainWin runtime environment.  This is achieved by using a new OI control type – the WINCONTROL control.  Support for this feature has been significantly enhanced for OI 8.0.

WINCONTROL and the Windows ClassName
Every control in Windows is based on a predefined template called a “Window Class”.  The class has a unique name, called the ClassName, used to identify it.  When an application wishes to create a control it specifies the ClassName as part of the creation process.  The OI WINCONTROL does something similar:  It allows OpenInsight to create a control based solely on its Windows ClassName, rather than the OI-specific name which is normally used (and which is translated internally to a Windows ClassName at runtime in any case).

Some examples of Windows and their actual class names are:

Creating a WINCONTROL control
The process for creating a WINCONTROL control is fairly simple, although not as easy as it might be due to the fact that it is not yet supported by the OI Form Designer.   There are four simple steps:

Build a control structure or copy one from an existing control (e.g. from an ORIG_STRUCT property)

Change the control type to:

WINCONTROL.<classname>

(where <classname> is the window ClassName of the desired control)

Pass the structure to Utility( “CREATE” )

Update the Window Common area

Example: Creating a Win32 ProgressBar

$insert ps_Equates
equ PROGRESS_CLASS$ to “msctls_progress32”
* // myCtrl is a simple editline used a “placeholder”
ctrlStruct = get_Property( myCtrl, “ORIG_STRUCT” )
ctrlStruct<0,PSPOS_TYPE$> = “WINCONTROL.” : PROGRESS_CLASS$
call utility( “DESTROY”, myCtrl )
call utility( “CREATE”, ctrlStruct )
 

Using a WINCONTROL

To use a WINCONTROL control we use the Windows API SendMessage or PostMessage functions, both of which are already prototyped for us in OI.  Using either involves the following steps:

Get the target control HANDLE

Determine the message ID

Determine the message parameters

Send the message

Much of the work using a WINCONTROL involves trawling Microsoft’s documentation to find what styles and messages you need to use to interact with it.  Remember that you’re operating much “closer to the metal” when using a WINCONTROL than you are when you’re using a standard OI control so you’ll be doing some extra legwork.  One thing you’ll notice about the MS documentation is that it mostly refers to constants by their name – to find their actual value you’ll need to look in the Windows header files that are supplied with Windows Platform SDK (and which you can download freely from the Microsoft website).

For the following example we had to consult both the ProgressBar documentation on the MSDN website and the commctrl.h header file.

Example: Using the Win32 ProgressBar control to set the bar position

equ PBM_SETPOS$ to 0x0402 ; * from commctrl.h
* // myCtrl is a WINCONTROL progress bar
hwndCtrl = get_Property( myCtrl, “HANDLE” )
newPos = 50
call sendMessage( hwndCtrl, PBM_SETPOS$, newPos, 0 )

 

Wrapping a WINCONTROL
One consequence of using WINCONTROL controls is that it may begin to make your code look cluttered and complex – they certainly don’t have the clean get/set property interface offered by “normal” OI and OLE controls for example.

However, that doesn’t stop you from providing your own wrapper and here at Sprezzatura this is exactly what we’re doing.  For each WINCONTROL type that we want to use we create the following:

The properties and methods that the last three property/method routines expose are translated into the appropriate window messages in the core routine.  Deciding what property and method names map onto which windows message is something you must decide when writing the wrapper, but common sense should dictate this in most circumstances.  A good rule of thumb is that window messages that get and set persistent control data should be exposed as properties, while other window messages should probably be exposed as methods.

Example wrapper - zzx_ProgressBar()
The zzx_ProgressBar package is Sprezzatura’s wrapper around the Win32 ProgressBar control.  It allows you to create and manipulate a progress bar control via a string based interface in the manner described above.  It is composed of four routines:

zzx_ProgressBar() – the core routine

prb_Get_Property – A “get property” function to extract Progress Bar property values.  This has exactly the same interface as the normal OI Get_Property function.

prb_Set_Property – A “set property” function to update Progress Bar property values.  This has exactly the same interface as the normal OI Set_Property function.

prb_Call_Method  - A “Send Message” function to execute Progress Bar methods.  This has exactly the same interface as the normal OI Send_Message function.

As part of this SENL issue we are releasing the source code for each of these routines so you can see how a WINCONTROL can be wrapped and used from within OI.  You will also find a window called PRB_TEST that demonstrates how to use the progress bar wrapper functions.  The source code is available on request from us at info@sprezzatura.com

Finding out more
As you’ve probably guessed by now this is not a small topic.  However it is covered extensively on the MSDN website should you wish to find out more, specifically in the Win32 User Interface section on Windowing:

                http://msdn2.microsoft.com/en-us/library/ms632586.aspx

And more specifically in the sections on Classes, Window Procedures, and Messages:

                http://msdn2.microsoft.com/en-us/library/ms632596.aspx

                http://msdn2.microsoft.com/en-us/library/ms632593.aspx

                http://msdn2.microsoft.com/en-us/library/ms632590.aspx

If you download the Windows Platform SDK you will have access to the core Windows header files.  Probably the most useful ones in respect of OI and WINCONTROL programming are:

Mail Merging From Advanced Revelation – Andrew P McAuley

At a client site recently we were faced with creating a complex document to replace an existing report for legislative purposes. Needless to say the idea of cutting lots of PCL didn’t appeal and having had so much success with using OLE within OpenInsight my thoughts naturally turned to using Word for Windows as my reporting vehicle of choice. What would be required could be split into four discrete areas :-

Creating the data file to merge from
This is actually very straightforward. The easiest format for mail merging is simply a tab delimited text file, where the first line is the headings to merge and the second and subsequent lines are the data to merge. This can be created by hand using NOTEPAD.EXE for proof of concept.

To create this we simple enter Name, press tab, Address1 press tab, Address2 press tab etc.

Creating the merge document
Again this is straightforward – simply create a standard mail merge document using as the data source the mail merge data file created above.

We’ll use the Mail Merge Wizard provided with Word and whiz through the first three steps :-

And save the Merge as c:\AREVM.DOC.

Closing the document and then reopening it shows us a slight problem. The following Dialog appears

This is undesirable because it will block our automated merge process later – so we need to prevent this dialog from appearing. . .

This can be done using REGEDIT to add the value SQLSEcurityCheck to the appropriate version of Office- this should be set to 0 :-

Record the actual merge macro
This macro needs to do the following actions :-

Simply recording the macro was nearly enough but the last couple of lines highlighted also needed to be added to close the document and quit Word. Stating the obvious you can’t record a Macro which involves closing Word as then the Macro is killed!

Sub AREVMERG()

'
' AREVMERG Macro
'
' Macro recorded 06/03/2007 by Andrew McAuley
'
    ChangeFileOpenDirectory "C:\"
    Documents.Open FileName:="""AREVM.doc""", _
        ConfirmConversions:=False, ReadOnly:=False, AddToRecentFiles:=False, _
        PasswordDocument:="", PasswordTemplate:="", Revert:=False, _
        WritePasswordDocument:="", WritePasswordTemplate:="", Format:= _
        wdOpenFormatAuto, XMLTransform:=""
    With ActiveDocument.MailMerge
        .Destination = wdSendToPrinter
        .SuppressBlankLines = True
        With .DataSource
            .FirstRecord = wdDefaultFirstRecord
            .LastRecord = wdDefaultLastRecord
        End With
        .Execute Pause:=False
    End With
    ActiveDocument.Close _
    SaveChanges:=wdDoNotSaveChanges
    Application.Quit
End Sub

Drive the production of the Merge from AREV
This requires a knowledge of command line options for Word for Windows and knowledge of a new command called START that spawns a new command prompt. Our AREV command then becomes

PCExecute "CMD /C START /MIN WINWORD /MMERGE"

Now all we have to do is update the merge data file from AREV and run the line above. Magically our mail merge will start to spew out of the printer without the user even being aware that Word has been invoked!

Celebrity Interview - Bryan Shumsky  - Revelation R&D, Senior Developer

Who are you?
I'm Bryan Shumsky (though I imagine you knew that already :-)) Perhaps here you're looking for a mini-CV?  I've worked in the multivalue market since 1986, first as a database administrator, and then as a software developer.  Most recently, I worked for Via Systems as the Director of Engineering.

Who do you work for?
I'm a Revelation Software employee, and report directly to Mike Ruane.

What is your role in the RevSoft community?
I'm involved in the development and maintenance of the base OpenInsight product, as well as the networking products.  I've had a lot to do with CTO (the Character to OpenInsight green-screen interface), and AREV32, in addition to a whole set of tools that interact with them (OECGI2, OI4WEB, etc.)

How long have you been involved with RevSoft?
I've been working for RevSoft for the last 18 months.  Before that, I'd done some development work in AREV (!) as an application developer many, many years ago.

Which products do you use?
OpenInsight 8.0 and AREV32 primarily, though I'm rather unfamiliar with many of the GUI parts of the product (as I'm a relative newcomer from the 'traditional' multivalue field) but I’m also using Java, Visual Studio .NET, and older Visual Studio products for C, C++, and Visual Basic development. (Quite the polyglot – Ed).

What do you most like about RevSoft products?
Their openness and flexibility.  It makes it possible to do all kinds of things that neither the original developers, nor us, planned for in advance.

What do you most dislike about RevSoft products?
I don't think there's anything in particular - if there was, I'd just go and change it :-)

If you HAD to use another database what would it be and why?
Well, now, why would I HAVE to? :-)

What are your favourite 3 books and why?
I'm an avid reader (mostly humour, science and science fiction), so it's very hard to just pick three.  However, my 'gut reaction' would be:

What are your favourite 3 CDs/Albums and why?

What are your three favourite films and why?
Well, here I'm going to cheat, and assume by 'films' you also meant to include 'DVDs', as the wife and I don't get to go to the cinema that much any more.  And if we're going to stretch the definition a bit, I'll include:

What event in history would you most like to have been present at?
That's a tough one. When one thinks of 'historical events', they're either (a) not really a single, discrete moment in time, but rather a _series_ of events, or (b) they're usually not so much fun for the participants (though, then again, maybe that's just my American history talking...) How far back can I go?  Maybe the moment when life first started on Earth in some brackish pond...

And finally Your motto/witty aphorism
I guess my unspoken motto would be: Always decide where you're having lunch before you do any other business for the day.  (One must have ones priorities, after all...)

ZZ_IDE_DUMP – A New Utility – Aaron Kaplan

When we decided to talk about Linear Hash structures at the recent user conference in Seattle, we realised that OpenInsight doesn't ship with a DUMP window. Those of you who came to OpenInsight from Advanced Revelation will remember this utility. It was especially useful when GFEs needed to be fixed but it was also useful at other times – not least for understanding what was actually going on at the physical level of the linear hash file. Just for old time’s sake here’s what it looked like!

In addition DUMP in AREV doesn’t understand the new Universal Driver file formats and so it can’t be used against this new structure. So for these two reasons - the lack of UD support and the lack of ANYTHING in OpenInsight we thought we’d best write our own version of the dump!

Naturally our starting point was the old AREV dump – after all if it ain’t broke why fix it? But we also wanted to take a bit more advantage of the Windows User Interface which provides more usable screen real estate. So as you can see in the following screen shot we have more space for the native file name. We can afford to put commas between our thousands and we can display the primary % and threshold % as decimals which the old dump had no room for. The other minor alteration to the header display is that we’ve added a spin control to allow the incrementing and decrementing of the size lock. The AREV DUMP used Reverse Video to good effect to show the header section of the frame and to highlight the individual row ids. We’ve extended this concept and used colours instead. As you can see the header section is in yellow, the row length is in blue, the key length is in cyan and the key is in green. Naturally these colours are user configurable as we’ll see later.

The AREV DUMP routine permitted changing to a limited HEX mode. This was useful in itself but didn’t allow an overview of the entire frame in hex

This is where the Windows Interface makes things so much easier.  Instead of showing a small section of the file in Hex we provide a second tab that allows the entire frame to be examined in hex. This makes the header structures much easier to understand.

As you'd expect, we have options to fix GFEs and compress the overflow – although to ensure that we keep your data safe we use Revelation’s own routines to actually perform the work.

Naturally we’ve also allowed for the ab