Setting Up a Virtual Frame Buffer to Support Oracle Reports Server

Article originally published by John Christian as a Sun BigAdmin Tech Tip)

Introduction

As the name implies, Oracle Reports Server is used to generate pretty reports. In some environments, these reports are delivered on an as-needed basis using X-connections to X-Servers. In other environments, these reports are run on automated batch schedules.

The funny thing is, Oracle Reports Server insists on connecting to an X-Server to function, even if it's running in batch mode. A common workaround is for the DBA to start an X-Term session on the server console and have Oracle Reports Server connect to it. Problems predictably arise when a sys admin comes along and "cleans up" the CDE, logs out, and so on, and the X-Term session is killed. Besides, what do you do if the server is headless and not running a local X-display at all? Route the display to another server or workstation that is running an X-Server? Obviously, these workarounds lead quickly down the path of "kludgedom".

Xvfb (in combination with twm) provides a more elegant solution of a more civilized age. The primary use of the X virtual frame buffer was intended to be server display testing. The X community has found many novel uses for Xvfb, including testing software clients against unusual color depths and screen configurations, doing batch processing with Xvfb as a background rendering engine, load testing, as an aid to porting the X server to a new platform, and providing an unobtrusive way to run applications that don't really need an X server but insist on having one anyway ... like an Oracle Reports Server!

To provide Oracle Reports Server with the X-display it desires, you can configure the Oracle Reports Server startup script to launch the Xvfb daemon to provide a virtual display device (frame buffer), and twm to provide a window-management framework.

Demonstration

Xvfb and twm are bundled with the default X installation on the Solaris Operating System. Below are the steps to try out Xvfb manually for functional verification. Some of the examples assume you have a CDE running on the host. While using Xvfb is not necessary, having an existing X-Session running makes the examples easier to follow.

First verify that Xvfb is available on your system. The default installation directory is /usr/openwin/bin.

$ ls /usr/openwin/bin | grep Xvfb
-rwxr-xr-x 1 root bin 290 Jul 10 2003 Xvfb

Let's have some fun with Xvfb.

$
$ PATH=$PATH:/usr/openwin/bin;export PATH
$
$ DISPLAY=:0.0;export DISPLAY
$ xclock

At this point, the xclock pops up on the local host console screen. (Press Ctrl-C to kill xclock.)

Now start the X virtual frame buffer:

$ Xvfb :5 -screen 0 1600x1200x32 &
6897
$ Warning: There is no XDISPLAY information for display 5.
Server is using XDISPLAY information for display 0.

Don't worry about the warning now; you eliminate it in the final configuration.

Reset the DISPLAY environment variable to point to the virtual frame buffer:

$ DISPLAY=:5.0;export DISPLAY
$ xclock

xclock runs with no errors. Although you can't see the clock, the lack of errors indicates that the clock has connected to the virtual frame buffer and is working.

What About twm?

The twm process provides a window-management framework for X applications that require it. Most applications -- xclock for example -- do not expect a windows-management framework to be present and function fine without it. Some applications -- Oracle Reports Server, for example -- expect a window manager to be present and do not function properly without it. The twm process is a part of the final solution.

Why Use :5?

Why would you use :5 for the virtual display setting? If a host has a video card and monitor installed running CDE (or another desktop GUI), chances are, display :0 is already in use. If a secondary video card (with monitor) is attached (very rare these days), it will use the :1 display. The :5 setting was arbitrarily chosen as a value that was high enough to be quite unlikely to conflict with existing display variables.

Final Configuration Using Xvfb and twm: OWconfig File Changes

Remember those warning messages you saw earlier when testing Xvfb? While not fatal, they should be cleaned up. To set up the :5 virtual display properly, edit an additional entry into the /usr/openwin/server/etc/OWconfig file, as shown in bold below.

# X Display
class="XDISPLAY" name="0"
coreKeyboard="IKBD" corePointer="IMOUSE"
dev0="/dev/fb";


# Virtual X Display for Oracle Reports Server
class="XDISPLAY" name="5"
coreKeyboard="NKBD" corePointer="NMOUSE"
dev1="vfb";


# CG6 display adapter
class="XSCREEN" name="SUNWcg6"
ddxHandler="ddxSUNWcg6.so.1" ddxInitFunc="sunCG6Init";


Oracle Reports Server Startup/Shutdown Script Excerpts

In order to ensure the virtual frame buffer is available for user after a reboot, include lines similar to the following example in the "start" portion of your Oracle Reports Server run control script.

#
# Provide a virtual frame buffer for the Reports Server to connect to
#
# Using display number 5 should safely avoid the common displays 0 and 1
echo "Starting Xvfb..."
/usr/openwin/bin/Xvfb :5 -screen 0 1600x1200x32 &
echo "Starting twm..."
/usr/openwin/bin/twm -display :5 -v &
echo "Setting DISPLAY to :5.0"
DISPLAY=:5.0; export DISPLAY

To ensure that the virtual frame buffer is not running unnecessarily if Oracle Reports Server is stopped, include lines similar to the following example in the "stop" portion of your Oracle Reports Server run control script.


# Clean up Xvfb (virtual frame buffer)
#
echo "Stopping Xvfb..."
/usr/bin/kill `ps -ef | grep Xsun | grep :5 | awk '{print $2}'` > /dev/null 2>&1



Process Verification

The Xvfb command actually results in a process running under a slightly different name. After Xvfb and twm are launched, you should see the following entries in the process table (ps details snipped):

/usr/openwin/bin/Xsun :5 +nkeyboard +nmouse -dev vfb -screen 0 1600x1200x32

/usr/openwin/bin/twm -display :5 -v

Enjoy!