Banded Report Writer Revealed – Unpacking CFG_OIBRW

The OpenInsight Banded Report Writer (BRW) is the proverbial phoenix of reporting tools for our beloved development environment. Many fondly recall the Report Designer, a fairly robust reporting tool that shipped with the 16-bit version of OpenInsight. It was our first taste of a true WYSIWYG reporting tool…and it was banded. Regrettably, the source code went MIA prior to Revelation Software’s transfer to WinWin Solutions, Inc. This left us with a tool that still worked, but it could not be supported nor updated to work properly with the 32-bit version of OpenInsight. The next version of this tool was released in OpenInsight v8.0. It was an ambitious project, if only because it attempted to build upon one of Revelation’s prime directives at the time: build tools within the toolset itself. The final result bore much resemblance to the capable Report Builder (an R/LIST interface, written in BASIC+). As such, it showed some promise. Alas, this tool never succeeded, despite efforts to address various problems through OpenInsight v9.21.

With OpenInsight v9.3, a brand-new Banded Report Writer tool was unveiled. No longer constrained by a self-imposed requirement of building all core tools with BASIC+, Revelation Software invested a lot of effort to integrate a modern, popular, and supported third-party reporting tool from ComponentOne – the same company whose products form the foundation of OIPI classic and OIPI.Net. This provided Revelation Software, developers, and end users a wealth of exciting opportunities and features…material which will certainly occupy future blog articles.

This article will be the first of many in a series dedicated to providing comprehensive technical information as well as tips and techniques that will get the best performance and features out of the Banded Report Writer. Some articles will be primarily focused on documentation. Therefore, we decided it would serve the Revelation community better if this information was published on our wiki site. This will continue our mission to provide our partners and colleagues one of the most useful places to visit to get the most out of OpenInsight. By the time you have read this article, we will have created a new section under the Revelation Resources categories, aptly named Banded Report Writer Revealed.

Our first missive will explore the intricacies of the SYSENV configuration record: CFG_OIBRW. Like many OpenInsight tools, the BRW relies heavily upon a configuration record to determine how certain aspects should behave. Most of this involves how the BRW communicates to the engine. While common configuration setups have been well publicized, we thought there would be value in delving deep and documenting as much as possible. Therefore, with some guidance from Bryan Shumsky, we present the following information.

First, let’s get something out of the way. There are two BRW related configuration records in SYSENV: CFG_BRW and CFG_OIBRW. The former is used by the retired BRW tool and is now deprecated. The second is what the new BRW uses, but it might not be present in your copy of OpenInsight. This is because the BRW will operate using default behavior if this configuration record is missing. More on this later.

As is common with other configuration records, CFG_OIBRW can be named to be applicable to all applications and users, or limited to a specific application and a specific user. Multiple CFG_OIBRW records can exist in this way, where the more specific configuration will always take precedence over the more generic configurations:

Default Configuration

Each attribute setting within the configuration record will have its own way of resolving default behavior (see the Settings section below for more information), but if no applicable CFG_OIBRW configuration record can be found, then helper routines like RTI_BRW_GenerateReport will assume the following settings:

<1> .
<3> *
<4> 0
<5> 0
<6> RTI_BRW_FILTER

Attributes 2, 7, 8, and 9 will be empty.

Settings

The configuration settings for CFG_OIBRW are varied and can cause unexpected behavior if not set up properly. This can be anything from the wrong database tables being used to OpenInsight crashes. Therefore, while the below information is provided for thoroughness, see the following Recommended Configurations section for examples that will work rather well.

Recommended Configurations

As noted above, not all configurations work equally well. Some will cause OpenInsight to crash or leaving various processes hanging in the Task Manager. There are three basic options to consider, each one has advantages and disadvantages:

• Direct Connect to In-Process Engine – The advantage of this configuration is that it allows the BRW to have access to dynamically attached tables. It is also faster since it doesn’t have to connect to another engine or launch one. The disadvantage of this configuration are the memory leaks which have been reported above. It does not fully support the syntax for multiple reports with a single RTI_BRW_GenerateReport command. Generally speaking, these leaks only manifest when OpenInsight is closed and often only when the Banded Report Designer has been used.
   
  Use this configuration for the quickest implementation setup of the Banded Report Writer:

  <1> .
  <2> 
  <3> *
  <4> 0
  <5> 0
  <6> RTI_BRW_FILTER
  <7> 
  <8> 
  <9>

• Direct Connect to a New Engine – The advantage of this configuration is that it is a relatively stable way to launch BRW reports. It also fully supports the syntax for multiple report usage with a single RTI_BRW_GenerateReport command. The disadvantage of this configuration is the lack of access to dynamically attached tables. It also requires an additional user license for the new engine that is launched, although the startup/shutdown flags can be configured to close the engine and release the user license when the report is finished.
   
  Use this configuration for the most balanced setup of the Banded Report Writer:

  <1> .
  <2> 
  <3> 
  <4> 65
  <5> 1
  <6> RTI_BRW_FILTER
  <7> 
  <8> 
  <9>

• EngineServer Connection – The advantage of this configuration is that it allows the BRW to offload reports to an EngineServer. This is probably the most stable configuration since all engine management is handled by the EngineServer. This also allows engines used to handling BRW requests to exist on a separate machine. The disadvantages of this configuration is the lack of access to dynamically attached tables. Additional user licenses are also needed, but these can be managed in smaller pools because of the queuing capability of the EngineServer.
   
  Use this configuration for the strongest engine management or for special circumstances setups of the Banded Report Writer.

  <1> <URL> (e.g., 10.0.0.15, 127.0.0.1, or localhost)
  <2> <PortNo> (e.g., 8088 or 8089)
  <3> 
  <4> 
  <5> 
  <6> RTI_BRW_FILTER
  <7> 
  <8> 
  <9>

For future reference, the above technical material can be reviewed from our recently added CFG_OIBRW Configuration wiki article. We hope this information will serve you well.