PPPPPPP v.vv

Getting Started

Installation

When you install RL_PRES it installs a number of files into the directory you specify. These files include:

rl_pres.dll - The PReS user hook module. The installer also copies this into the PReS utilities directory so that it is always available to PReS.
examples\rl_pres.pdi - The RL_PRES INCLUDE file. Copy this to wherever you keep your PReS include files. It will need to be INCLUDEd by any PReS scripts that want to use the RL_PRES module.
examples\*.* - Example files (see below).

Running the example

An example is supplied which demonstrates using the RL_PRES module to generate a document with a graph on each page.

The example consists of the following files which can be found in the example sub-directory of the directory RL_PRES was installed into:

BrokerHeadFooter.trf: resource
Chartbook.trf: resource
GlobalWatch.trf: resource
sigrtb.eps: resource
example.dta: sample data
examplechart.py: example python chart code
example.pds: example PReS script
rl_pres.pdi: The RL_PRES include file used by the example and any other scripts that need to access RL_PRES.

The example is designed to be run in the \PReS directory and it is assumed that you will also be storing the rl_pres.pdi include file in this directory and storing your Python chart files in \PreS\reuse\charts. You can arrange the files differently if you want but if you do you will need to modify the references to the files in the example.pds script.

To run the example:

Copy example.pds, example.dta, BrokerHeadFooter.trf, Chartbook.trf, GlobalWatch.trf, sigrtb.eps to the \PReS directory
Copy examplechart.py to the \PReS\reuse\charts directory
Copy rl_pres.pdi to the \PReS directory
Run the PReS script example.pds on the data file example.dta

The example should generate a document with a bar chart on each page. Each bar chart is plotted from the eight values at the end of each record in example.dta.

The code in example.pds illustrates the main features of our approach.

The script INCLUDEs rl_pres.pdi so that it has access to the Diagra functions
In the START section we call DiagraInitialise and DiagraSetPath to initialise Diagra and tell it where to look for chart files.
At the end of the processing section (in routine Process) we call our chart generation code in routine ProcessChart.
The code in ProcessChart calls various Diagra routines to create the chart, read in the data values, put them in to a list, and set the chart to use the list of values for its data. We then save the chart as an EPS file and use LOADGRAPHIC to put the EPS into the document.
The graphics files are generated in \Pres\rl_tmp (set by the global variable gaTempFileTemplate) and we delete them at the end of the run in the FinishedProcessing section.

Please look at the comments in example.pds and rl_pres.pdi for further details.

Technical Details

rl_pres.dll

The RL_PRES interface dll contains the PReS interface hook entry point
UserInstruction

which is declared


__declspec(dllexport) int UserInstruction(HWND hWnd, HINSTANCE hInst,
        double FAR *options, char FAR *s0, char FAR *s1);

The first two arguments are not used by our code, but the hook has the following user values/arguments.

options double array of length 5

options[0]   on input this holds the required action
             0.0 = simple string with '\n's only
             1.0 = simple string with '\r\n's to be converted to '\n'
             on output this holds the error value
             0           No error
             Non-zero    An error was detected, use the value of s1 to 
                         find out more.
options[1]   ilen ie the actual length of input string
options[2]   olen the available length of the output string
options[3]   set by rl_pres.dll to 0
options[4]   set by rl_pres.dll to the length of the output string

s0           the input buffer length at least ilen
s1           the output buffer length at least olen. This string will
             be used to return at most olen bytes fro stdout/stderr
             The actual length used will be returned in options[4]

trl_pres.exe/python.exe

We provide an example of calling the interface from C as both a test of correctness and as a useful test script. The program can be run as

trl_pres.exe aaa.py

and this should result in some output being printed on the command terminal. An accompanying exe file is python.exe which effectively duplicates a normal python command, but tries as far as possible to use only the code in the installed PPPPPPP v.vv installation directory.