Table of Content

91.592 Directed Study (Software Engineering)

Spring 2002

BDE Replay Project Report

Zhongmin Cao

May 2002

Table of Contents

1 Introduction

1.1 Purpose

1.2 Background and Objectives

1.3 Overview of project work

2 Design and approach

2.1 The replay function implementation

2.2 Test program for the replay function

2.3 Preparation work for future BDE porting

3 Testing, evaluation and results

4 References

Appendices A, B, C, D

1. Introduction

1.1 Purpose

This report is intended to summarize the work and results of the BDE project undertaken during the spring semester in 2002. It is to document the enhancement and changes made to the project, and for future reference.

1.2 Background and Objectives

BDE(Block Diagram Editor) is an existing graphic editor running in the X environment on Digital Alpha systems. This project is to add the replay function in addition to the current functionalities.

1.3 Overview of project work

The project work consists of the following several components:

1) Implement the replay functionality

2) Test the replay implementation.

3) Preparation work for the BDE application's porting to the FOX platform independent graphic user toolkits.

2 Design and Approach

2.1 The replay function implementation

The existing BDE contains two functions related to the replay process, they are pr_replay() and replay_log() in the file pr_log.c under the directory pr_util. This project revises the replay_log() to be part of the callback/event handler function of an X event, such as key press. It is extracted from pr_log.c to be separate file under bde/src directory with file name called bdeReplay.cc pr_replay() still remains in pr_log.c.

So, with the current implementation, BDE calls pr_load, to load the contents of the database from the database file using the specified view: pr_load() in pr_load.c calls load_data (), load_data() reads the initial database file, such as *DB1.dat, row by row and calls pr_add to add it to the database. But if load_data() finds line "SR" in the file, which means the file is a log file, not a database file. load_data() will return true to pr_load() right after. In any cases, pr_load() then closes the file opened. If load_data() returns 1, pr_replay() will be called by pr_load().

pr_replay() checks the hcg_log value, if it is 1, means logging is in process, reports error and exits. Otherwise set the hcg_log to 2 to allow the start of the replay process. pr_replay() sets hcg_log back to 0 at the end of it.

After the initial database is loaded and displayed, the X events will trigger the real replay process. One X event triggers the call to the replay_log() for only one time. Each time the replay_log() is called, one line of the log file is read in, parsed and necessary actions are executed accordingly. Besides, the replay process is revised to be a three-state process.

2.1.1 BDE replay state diagram

During the replay process, at any given time, it must be in one of the three replay states. The three states for the BDE replay process are: STATE0, STATE1 and STATE2.

STATE0 is the initial state, every replay starts with this state. STATE1 opens the log file, gets the first line of the log file and parse the line to get the command token, verifies that the command token is "SR", and then sets the replay state to STATE1.

In STATE1, the process first reads in one more line and parses it and gets the command token, Depends on the type of command, executes different actions. If the token is one of the SetFltCmd, SetInitCmd, SetKeyCmd, SetStrCmd, AddRowCmd and DeleteCmd, it will call clearObjects() to clear the object hierarchy by deleting the topobject, and creates a new one. , then set the HG_pkey value, call updatedisplaylist() to update the graphic object list and finally call ReDraw() to redraw the graph according to the current graph object list.If the token is StopCmd, it sets the replayState to STATE2 for final stage cleanup work. If the command is something other than these, nothing will be done within this state.

In STATE2, depending on the contents of the log file, sets the replayStatus value and then close the log file. Another task need to be performed in this state is to check weather the final database is necessary to be saved. The parameter control this action is take_endsnapshot. If it is set to be 1, save the database after the replay in a file called *DB3.dat, otherwise, nothing need to be done.

In any of the state, once it finishes the action sequence required, the replayState value is returned to the calling function, which is the callback/event handler function of an X event.

The state diagram is shown in the file zcao_BDE_Replay_STD.ppt

2.1.2 Initial database file

The initial database with name *DB1.dat contains the snapshot of the database just before the replay logging is started.

Please refer to the Appendix D for a sample initial database file mylogDB1.dat.

2.1.3 Replay log file

The replay log file *.txt starts with line "SR", which means the start of the logging, and normally ends with "SP", which means the stop of logging.

Please refer to the Appendix E for a sample replay log file mylog.txt.

2.2 Test program for the replay function

The purpose of the test program bdr.cc (block diagram replay) is for testing the correctness of the replay_log() function in the bdeReplay.cc file under bde/src directory.

In order to isolate other factors that may prevent the function from running properly, bdr.cc keeps only the minimum components required for a replay, thus the test program creates a window with a drawing area (canvas) only. There is no menu bar and left navigation bar present in the display window.

To start the program, enter

# bdr logDB1.txt log.dat

The first command line argument logDB1.txt is the initial database file, which represents the initial state before the replay. The second argument log.dat is the log file containing "SR" line in it. So supply the proper DB file and the log file accordingly to the command line.

After the program is started, the initial database file is loaded and displayed in the canvas. To start the replay, select the window created by bdr.cc and press the key "s" on the keyboard, each key press triggers one step of replay, press "s" continuously to step through the replay process until it reach the end of the log file log.dat.

To support the build of the bdr executable without interfering the normal bde build process, BDR is defined in the configure.h file under bde directory. Besides, Imakefile in bde/src directory is modified to allow the build of bdr other than bde. The partial modified bde/src/Imakefile is attached below:

#ifdef BDR

OBJS = bendpt.o bendptops.o bdr.o bdeReplay.o buttonevent.o \

captionops.o cursor.o dialog.o display.o draw.o edit.o fileio.o \

font.o fprint.o graphobject.o graphops.o handler.o help.o hlink.o \

infodialog.o infomessage.o init.o initClasses.o leftmenu.o leftmenu_cb.o \

linkops.o menubar.o menubar_cb.o msgBox.o nodeops.o select.o \

smselect.o strdup.o text.o textops.o

SRCS = bdr.cc bdeReplay.cc bendpt.cc bendptops.cc buttonevent.cc \

captionops.cc cursor.cc dialog.cc display.cc draw.cc edit.cc fileio.cc \

font.cc fprint.cc graphobject.cc graphops.cc handler.cc help.cc hlink.cc \

infodialog.cc infomessage.cc init.cc initClasses.cc leftmenu.cc leftmenu_cb.cc \

linkops.cc menubar.cc menubar_cb.cc msgBox.cc nodeops.cc select.cc \

smselect.cc strdup.cc text.cc textops.cc

ComplexCplusplusProgramTarget(bdr)

#else

OBJS = bendpt.o bendptops.o bde.o bdeReplay.o buttonevent.o \

captionops.o cursor.o dialog.o display.o draw.o edit.o fileio.o \

font.o fprint.o graphobject.o graphops.o handler.o help.o hlink.o \

infodialog.o infomessage.o init.o initClasses.o leftmenu.o leftmenu_cb.o \

linkops.o menubar.o menubar_cb.o msgBox.o nodeops.o select.o \

smselect.o strdup.o text.o textops.o

SRCS = bde.cc bdeReplay.cc bendpt.cc bendptops.cc buttonevent.cc \

captionops.cc cursor.cc dialog.cc display.cc draw.cc edit.cc fileio.cc \

font.cc fprint.cc graphobject.cc graphops.cc handler.cc help.cc hlink.cc \

infodialog.cc infomessage.cc init.cc initClasses.cc leftmenu.cc leftmenu_cb.cc \

linkops.cc menubar.cc menubar_cb.cc msgBox.cc nodeops.cc select.cc \

smselect.cc strdup.cc text.cc textops.cc

ComplexCplusplusProgramTarget(bde)

#endif

So there is one switch to control the build target. To build regular bde, nothing extra is necessary to be done. If choose to build bdr, add a line #define BDR to the file configure.h and then do a make. The executable for the bdr test program is bdr in the bde/src directory.

The source code for bdr.cc is shown on the next page.

/*********************************************************/

/* File : bdr.cc */

/* Description : Test program for BDE replay function */

/* Created by : 02s592 */

/* Routines : keypressHandler() */

/* Usage: %bdr filename1 filename2 */

/* filename1: the *DB1.dat database file */

/* filename2: the log file */

/*********************************************************/

#include "prototype.h"

#include "94sbde_schema.h"

#include "bde.h"

#include "graph.h"

#include "defs.h"

#include "loaddefaults.h"

#define WIDGET

#include "widget.h"

extern char *GetBDEViewDefsFile( void );

extern char *GetBDEDatFileList(char * );

extern void initClasses();

extern "C" int replay_log(void);

extern void updatedisplaylist(struct HG *cHG);

extern Widget canvas;

extern Screen *rootscreen;

extern Display *display;

extern struct HG *HGcurr;

extern int endOfReplay;

void keypressHandler(Widget w, XtPointer input,

XEvent *event, Boolean *continue_dispatch);

void canvascallback(Widget w, caddr_t *client_data,

XmDrawingAreaCallbackStruct *cb);

Widget toplevel;

Select selected;

XtAppContext app_context;

int stepCount = 0, replayState = 0, dcount =0;

char *infile;

int main(int argc, char **argv)

{

unsigned long color;

infile = argv[1];

extern char* logfile;

logfile=argv[2];

endOfReplay=0;

toplevel = XtAppInitialize(&app_context, "ReplayTest",

NULL, 0, &argc, argv,NULL,NULL,0);

Arg args[4];

int n=0;

XtSetArg(args[n], XmNwidth, 830); n++;

XtSetArg(args[n], XmNheight, 430); n++;

color = WhitePixel(XtDisplay(toplevel),DefaultScreen( XtDisplay(toplevel)));

XtSetArg(args[n], XmNbackground,color ); n++;

color = BlackPixel(XtDisplay(toplevel),DefaultScreen( XtDisplay(toplevel)));

XtSetArg(args[n], XmNforeground,color ); n++;

canvas = XtCreateManagedWidget( "canvas",

xmDrawingAreaWidgetClass, toplevel, args, n);

XtAddCallback(canvas, XmNexposeCallback,canvascallback, NULL);

XtAddEventHandler(canvas, KeyPressMask, FALSE, keypressHandler, NULL);

initClasses();

XtRealizeWidget(toplevel);

XtAppMainLoop(app_context);

}

void canvascallback(Widget w, caddr_t *client_data,

XmDrawingAreaCallbackStruct *cb)

{

if (dcount ==0) {

hcg_initialized = 0;

pr_init( GetBDEViewDefsFile(), GetBDEDatFileList(infile) );

pr_load("94sbdeview",infile);

if (HGcurr == NULL) {

printf("HGcurr is NULL \n");

}

else {

updatedisplaylist(HGcurr);

ReDraw();

}

dcount =1;

}

void keypressHandler(Widget w, XtPointer input,

XEvent *event, Boolean *continue_dispatch)

{

KeySym keysym_return;

Modifiers mod;

if(event->type == KeyPress)

{

XtTranslateKeycode(display, event->xkey.keycode,

event-> xkey.state, &mod, &keysym_return);

if ((strcmp(XKeysymToString(keysym_return),"s")==0) & (endOfReplay==0))

{

printf("\n====== replay step %d, replayState %d\n",

++stepCount, replayState);

replayState = replay_log();

}

A sample output from a run of bdr can be found in the section 3.

2.3 Preparation work for future BDE porting.

Because the current BDE's graphic user interface is implemented by calling X/Motif routines, this makes the application heavily rely on the X/Motif environment to run, with the increasing amount of the Microsoft Windows user base, no support for Microsoft Windows environment becomes an issue. Other than providing an Windows version as a solution to address this problem, porting the BDE application to be on top of an independent graphic user interface platform allowing both the X/Motif and Microsoft Windows users access the BDE application is also a good option.

The benefit of the second solution brings us is that only a single version of the software is necessary to be maintained, so lets future application enhancement work easier. The disadvantage of this is we will need to rely on the 3rd party's support on the future new platforms or releases.

The independent graphic user interface that has been chosen for BDE porting work is the FOX Toolkit. FOX Toolkit offers a collection of Controls and capabilities such as drag and drop, selection, as well as OpenGL widgets for 3D graphical manipulation. The most attractive feature to the BDE project is its wide range of platform support, which is claimed as platform independent. FOX Toolkit now runs on operating systems ranging from Linux, FreeBSD, SGI IRIX, HP-UX, IBM AIX, SUN Solaris, DEC/Compaq Tru64 UNIX, to MS-Window operating systems like Windows 9x, Windows NT, Windows ME and Windows 2000.

The porting preparation work has been started as part of the project. As an assistant for decision making on how to do the porting, a better overall knowledge on the Xlib and Motif routines called by BDE is necessary. The program a.cc and b.cc are for this purpose.

a.cc and b.cc extract the Xlib and Motif calls from the all BDE source code together with the calling parameters, and then sorted them for better analysis. a.cc's output lists the calls in the filename order, while b.cc's lists the results in routine name order. Both results give out the number of occurrence and the line numbers.

The output for the two programs is listed below. The source code can be found in Appendix D and E.

Partial results of sorted by File: for text.cc

The first column shows the line number of the occurrence in the file, the second column shows the routine called, the third column is the complete call presented in the file.

text.cc:

---------------------

184 XmSelectionBoxGetChild: str = XmTextGetString(XmSelectionBoxGetChild( graphCaptionDialog,

XmDIALOG_TEXT ));

186 XtUnmanageChild: XtUnmanageChild(graphCaptionDialog);

203 XmSelectionBoxGetChild: str = XmTextGetString(XmSelectionBoxGetChild( textDialog,

XmDIALOG_TEXT ));

206 XtUnmanageChild: XtUnmanageChild(textDialog);

211 XDrawString: XDrawString(XtDisplay(canvas),XtWindow(canvas),xorGC,

data->cur_x,data->cur_y,

data->cur_val,strlen(data->cur_val));

216 XDrawString: XDrawString(XtDisplay(canvas),XtWindow(canvas),copyGC,

data->x,data->y,data->str,strlen(data->str));

233 XmSelectionBoxGetChild: str = XmTextGetString(XmSelectionBoxGetChild( textDialog,

XmDIALOG_TEXT ));

237 XtUnmanageChild: XtUnmanageChild(textDialog);

265 XtUnmanageChild: XtUnmanageChild(textDialog);

310 XLoadQueryFont: font = XLoadQueryFont(XtDisplay(canvas), fontname);

312 XLoadQueryFont: font = XLoadQueryFont(XtDisplay(canvas),"Fixed") ;

313 XSetFont: XSetFont(XtDisplay(canvas), gc, font->fid);

324 XLoadQueryFont: font = XLoadQueryFont(XtDisplay(canvas), fontname);

Partial results of sorted by routines: for routine XCreateGC

The first column shows the file name, the numbers in the parenthesis show the line number in the file, and the third column is the complete call presented in the file.

XCreateGC:

---------------------

initClasses.cpp(154): copyGC = XCreateGC(display, rootscreen->root,

(GCForeground | GCBackground | GCLineWidth | GCFont),

&values);

initClasses.cpp(158): segmentGC = XCreateGC(display, rootscreen->root,

(GCForeground | GCBackground | GCLineWidth | GCFont),

&values); // 96subde: fjara, ianandak

initClasses.cpp(172): xorGC = XCreateGC(display, rootscreen->root,

(GCFunction | GCForeground | GCBackground |

GCPlaneMask),

&values);

initClasses.cpp(185): highlightGC = XCreateGC(display, rootscreen -> root,

(GCFunction | GCForeground | GCLineWidth |

GCBackground | GCLineStyle | GCPlaneMask),

&values);

3 Testing, evaluation and results

The following tests were performed in order to check to what extent the replay function works.

3.1 BDE

The executable bde.exe in /usr/proj3/case/gen/ver_12/sjaganat/Test/bde/executables/alpha was run with key press events to start the replay. The result was the same as what was expected. The output from the replay is shown below:

% /nfs/saturn/proj3/case/gen/ver_12/sjaganat/Test/bde/executables/alpha/bde.exe mylog.txt

Using GENV12

Replay file : mylog.txt | Click Options -> Start Replay to start replay

GD defaults file not specified. Using BDE defaults

SCnode 0x11 17

dostate: selected.getstate = 0x11 = 17

Using default viewdefs: ../lib/bdetest.viewdefs

Warning: unknown table /* found in scanned datafile ../lib/fonts.dat, ignored.

Warning: unknown table found in scanned datafile ../lib/fonts.dat, ignored.

Warning: unknown table () found in datafile, ignored.

Replay Ready : 1Token=SR, Command = 6

Found SR