Rainier Software - RainierFun FAQ

The RainierFun OLE server DLLs are runtime components which expose methods (functions) to any controlling application. In the COOL:Gen example, the installation of the OLE server add-on simply means that the developer has access to a new set of functions to use in action diagrams. When using other development tools such as Visual C++ or Visual Basic the methods of an OLE server can be directy accessed in code.

How easy are the components to install on the developer workstation?

A setup program is included. The installation normally takes less than one minute.

How does a COOL:Gen developer access the functions from within Action Diagrams?

Before accessing any of the functions, the relevant DLL must be loaded into memory, and a pointer to it obtained. This is done with a work set attribute of type guiobject, and a call to the COOL:Gen CreateObject function. For example:

SET local ole guiobject TO CreateObject("rnWinFun.WinFun")

This guiobject pointer may be passed around from exports to imports and from procedure to procedure if desired.

Having obtained the pointer, all the methods now become available. To invoke one of the functions you would create a statement that looked something like this:

SET local ole return_code TO local ole guiobject .rnPreventWindowResize(local ole handle)

[In this example, local ole handle is a parameter to the function which would normally have been obtained with a call to the COOL:Gen GetHandle function or an earlier call to one of the WinFun functions rnFindWindowByName or rnFindWindowByClass.]

I don't use Advantage Gen/COOL:Gen. Can I use these components?

Yes. Although they have been designed specifically to meet the needs of COOL:Gen application developers, all the components are fully OLE-compliant and can be called from any OLE controller (VB, VBA, VC++, PowerBuilder, Delphi, etc...).

If you are interested in Word and/or Excel integration you should use WordController instead of WordFun and ExcelController instead of ExcelFun as these are more suitable for non COOL:Gen users. Note that WordController and ExcelController will NOT work with COOL:Gen.

WordController and ExcelController are distributed through ComponentSource.

I want to build Web-browser interfaces, not GUI windows. Can I use these components?

Yes. OLE servers like these can be loaded and manipulated from within Web pages. This can be done in a variety of ways, using VBScript, JavaScript etc. Here's a simple example using VBScript.

<HTML>
<HEAD><TITLE>ExcelFun via the Web</TITLE>
<SCRIPT LANGUAGE="VBScript">

</SCRIPT>
</HEAD>
<BODY>
<H3>ExcelFun via the Web</H3><HR>
<FORM><INPUT NAME="Button1" TYPE="BUTTON" VALUE="Click Here"></FORM>
</BODY>
</HTML>

How are the components deployed?

An OLE server DLL is deployed just like any OCX Ole Control. The DLL must be deployed to all user workstations with the application client procedures. The easiest way to do this is with the supplied setup program which can be run from a network drive. Another option is to include the DLL and its support files in an application's setup program created with, for example, InstallShield or Visual Basic.

As with any OCX, the OLE server DLL must be registered on the target workstation. This is done by the setup program, or can be done manually using the REGSVR32 program which comes with Visual C++.

It is also necessary to register some of the COOL:Gen supplied files on target workstations in order for OLE server functionality to work. See the Troubleshooting section for more information.

What's in the downloadable trial versions?

The trial versions are fully functional and behave exactly as the commercial versions, except that they display occasional reminder messages that this is an evaluation version. These messages are displayed approximately one function call in every 10. We can also supply timed DLLs which only start to display these messages after a specific date, if required.

Where can I see examples of the components in use?

Download the demonstration Composer or COOL:Gen model from this site. It has examples of real procedures with working code using many functions from each of the components.

Why do I need to use WordFun and ExcelFun when I can drive these programs natively from COOL:Gen?

There are several important reasons:

Full error handling is possible. If you INVOKE Word and Excel methods directly in COOL:Gen action diagrams you cannot trap errors and have to proceed through your logic on the assumption that everything is working. This often leads to a cascade of errors and unpleasant message boxes which you cannot suppress. With WordFun and ExcelFun you can suppress these message boxes and test after each function call whether it was successful or not. See also 'How are errors handled?'.

Multiple versions of Word and Excel are supported transparently. There are version-to-version differences in the native code you need to use to perform the same operation. WordFun and ExcelFun shield the developer from these and offer functions which will work on target workstations with different versions of Office (from 4.2 onwards). Also, you do not want to have to revisit your program code to support the next version of Office when it comes out. You simply deploy the updated DLLs - no re-compiling or re-linking required. So if your users work with a mix of Office versions you do not need to worry.

The WordFun and Excel functions tend to be much higher level and simpler to use than the native Word and Excel properties and methods. Complex operations are reduced to a handful of simple function calls and the developer does not need to understand the complexities of the Excel and Word object models.

How are errors handled?

All the RainierFun components handle errors using a similar mechanism. Each time a function is called, information is written to a.ERR file (eg RNWINFUN.ERR). This information includes the return code and any error text and is written whether the function succeeded or failed.

The error information can be returned to the COOL:Gen action diagram with functions included in the components (e.g. rnGetLastErrorNumber and rnGetLastErrorText). Most functions return negative values in error situations so after a call to a function you may include logic like this:

IF local ole return_code IS LESS THAN 0

SET local ole return_text TO local ole guiobject .rnGetLastErrorText

... (error display and/or handling)

This means that you can trap errors, display your own message boxes if you wish and take any other appropriate action. This is not generally possible when driving OLE servers natively with COOL:Gen.

With which versions of Advantage Gen/COOL:Gen can you use these components?

You can use them with any version of COOL:Gen up to at least COOL:Gen 6.0. You must be targetting 32-bit Windows 95/98 or NT 4.0 for your client procedures.

With which versions of Microsoft Office can you use these components?

WordFun, ExcelFun and MailFun interact with Microsoft Office on the desktop. Click here for details of Office version compatibilty for all Rainier products.

Do I need any COOL:Gen PTFs?

With COOL:Gen 4.x, however, you MUST install PTF TSN4108. If you don't you will receive a message 'Unable to find method or property....' at runtime. No PTFs are required if using COOL:Gen 5.x or 6.x. Also, there was a problem with COOL:Gen 4.1a GUI Runtime PTFs RTN4109 through RTN4115 which caused some functions to fail. If you have installed any of these PTFs you must also install PTF RTN4116, which fixed the error. For more information on this click here.

WinFun Specific

What are handles and how are they used?

Handles are numbers which identify objects used by the operating system. Windows, controls and menu items all have handles. Many of the WinFun functions require you to pass a handle as a parameter to identify the object on which you want to operate.

Handles are usually obtained using one of the following functions: rnFindWindowByName, rnFindWindowByClass, rnGetButtonHandle, rnGetMainMenuHandle or rnGetSubMenuHandle. Or if you are using COOL:Gen and the object you want to operate on is a window or control in the current procedure, you can use the COOL:Gen built in function GetHandle. Other application development tools also offer handles as window and control properties.

How do you use WinFun to control the COOL:Gen Client Manager?

There is a section describing how to do this in the WinFun User documentation RNWINFUN.DOC. Essentially you need to launch the Client Manager minimized with the rnShell function then hide it with rnHideWindow (you cannot launch the Client Manager hidden). When the application terminates, you close the Client Manager invisibly with rnCloseWindow.

How can I add right-click pop-up menus to my COOL:Gen windows and controls?

Use the rnPopupMenuAuto or rnPopupMenuCustom functions in the 'Right Mouse Button Down' event of the window or control. rnPopupMenuAuto lets you drop down a submenu which is an exact copy of one of the top level menus on your window. rnPopupMenuCustom lets you define a menu exactly according to your requirements, but you need to specify in the parameters you supply exactly what menu items you want to appear on the popup. A menu created this way is not related to any existing menu you may have on your window.

How can I implement dynamic menus in COOL:Gen?

WinFun offers several functions to manipulate menu items. Each menu and submenu has its own handle. These can be obtained with rnGetMainMenuHandle and rnGetSubMenuHandle. Once you have the handle of a menu or submenu you can operate on its menu items.

You can change the caption (and mnemonic) of a menu item and you can delete a menu item. However you cannot add a menu item as it not possible to associate a newly added item with event logic in your action diagram. So if you want to offer a different set of menu options for a different set of users you must create your window with as many items on it as you there are options in total, and associate them with event logic in the normal way. For each user you must decide which items are valid and delete those which are invalid using rnDeleteMenuItem, normally in the window Open event.

You can change the caption and meaning of a specific menu item with rnSetMenuCaption. If you do this you will probably want to have an IF statement in the event logic for that item which performs different logic, depending on the caption of the menu item.

How can I prevent the User from resizing or moving a window?

Use the rnPreventWindowMove or rnPreventWindowResize functions in the window's Open event.

How can I click a button or menu item on another application (or my own application)?

You need to get the handle of the button or menu item first and then use one of the functions rnButtonClick or rnMenuItemClick. To get the handle of the item you need to first get the handle of the window and then use one or more of rnGetButtonHandle, rnGetMainMenuHandle, rnGetSubMenuHandle or rnGetRelatedWindow.

Can't you do some of the WinFun functions natively with COOL:Gen?

It is true that there are cases where you can achieve the same thing with a WinFun function or a COOL:Gen function. For example you can set the position and size of a window either way. However WinFun functions can operate on any window on the desktop, as well as all those in your COOL:Gen application. The COOL:Gen functions can normally only be applied to the window of the procedure in which the call to the function is made.

Every single WinFun function has been included because it was required by somebody, somewhere.

Troubleshooting

Why might the OLE server not load correctly on a deployed installation?

The server DLL may not have been installed correctly. Try re-registering with REGSVR32.EXE or, better, re-run the setup program.

If the application being deployed is a COOL:Gen application the most common problem to occur during deployment is that the COOL:Gen clients themselves which call the RainierFun component functions are not registered. You MUST run the .REG files generated by COOL:Gen on the target workstation during deployment. If this is not done the Rainier component DLLs will not load - the CreateObject statement will not return a valid pointer to the DLL and subsequent function calls will not do anything.

In addition you must register the WROAF.REG (for the Composer/COOL:Gen typelibraries) and either WRU540N.DLL (Composer 4) or WRU410N.DLL (COOL:Gen 4.1) or WRU500N.DLL (COOL:Gen 5.0) for OLE server functionality to work.

[Note that this does not cover the complete list of files that need to be deployed - only the ones most commonly forgotten]

I'm getting 'Unable to find method or property....' at runtime

If you are using COOL:Gen this is likely to be due to the fact that you have not applied COOL:Gen PTF TSN4108 which is mandatory to use these functions. COOL:Gen 4.1 introduced a bug with the implementation of dot-notation action diagram syntax. You need to apply the PTF, open up the affected action diagrams, save the model and regenerate.

You may also get this message if you are trying to call a method from the wrong library. If you have established your guiobject reference to one library (with the CreateObject function), and have inadvertently selected a method from another library via the action diagram OLE Object Browser.

Some functions are not working correctly after applying a COOL:Gen PTF

There was a problem with COOL:Gen GUI Runtime PTFs RTN4109 through RTN4115 which caused some functions to fail. If you have installed any of these PTFs you must also install PTF RTN4116, which fixed the error. For more information on this click here.

My COOL:Gen application or Word or Excel is still running in Task Manager after it has been closed

Suppose your COOL:Gen application starts by executing Gen windowed load module MENU.EXE. You launch the menu, do some operations and then close the application. All seems ok until you try to close the machine down you receive a message telling you that the application is still running. When you look in Task Manager you see that the MENU.EXE process is still running, even though there are no windows associated with it. This is known as a 'ghost process'.

This problem can be fixed by making sure that whenever you declare a GuiObject variable for use with an OLE server or OCX you always clear it before exiting the procedure. You do this with statements like "SET myworkview guiobject TO NOTHING". You would normally put these statements in window Close events.

You may also find that instances of Word or Excel remain in the task manager after they have been closed. If your application launches Word or Excel and then this instance is closed by the user it's process will not be terminated until your application releases its reference. This will not normally happen until your application closes and is normal behaviour. However, WordFun and ExcelFun will recognise that an instance still exists in subsequent calls and reuse it, so they will not create multiple instances unnecessarily (unless you specifically choose to do this). The problem arises if you have COOL:Gen ghost processes - you may also get Word or Excel ghost processes because the Gen load module which has not yet released its reference to the Office application is still running. In all cases the answer is to SET guiobject TO NOTHING.

My COOL:Gen application GPFs when a window is closed

As with the 'ghost process' problem (above), GPFs (General Protection Faults, or memory allocation errors) when closing a window can often (but unfortunately not always) be solved by ensuring that all guiobject variables are SET ... TO NOTHING in your window Close event. This should be done for all OCX and OLE server guiobjects.

If you are experiencing GPFs at other times than at window close, you may be suffering from a known COOL:Gen memory leak problem. In Gen versions up to 5.1 every time you use a dot in an action diagram statement you leak 400 bytes of memory. If you use many dot statements in loops to manage complex controls like TreeViews or ListViews then you may experience this problem. There are ways to minimise the impact - contact us if you would like more information. This is almost never relevant to the use of the Rainier OLE servers which generally require the use of few 'dot' statements.

Overflow error in WinFun function rnGetDiskTotalSpace or rnGetDiskFreeSpace

The error code -6 (Overflow) when executing these functions on large disk drives is due to a bug which was fixed in version 1.1.0

GPF in WinFun function rnGetCurrentCommandLine

Fixed in version 1.0.52