/usr/proj3/case/95f523/bde2ht3/base/doc/BDE2HT3_User_Manual_121895.txt
Table of Contents
1.0 Introduction
1.1 Flow Diagram
1.2 Link Flows
1.3 Execution Path
1.4 Execution Process
2.0 Code Requirements
2.1 ps2gif
2.2 bde2ht3
3.0 ps2gif
4.0 bde2ht3
4.1. Begin at the Beginning
4.2. File Naming Conventions
4.3. 'C' Modules Used to Create the HTML Files
5.0 Future Expansion
5.1 Having BDE save gif as well as PS
5.2 Generate HTML files on the fly using CGI-scripts
6.0 bde2ht3 Testing
6.1 Testing ps2gif
6.2 Testing gif, imagemaps, HTML
6.3 Testing bde2ht3 from user's own public_HTML directory
6.4 Schools example Instructions
7.0 Conclusion
8.0 Diagrams
bde2ht3 - Data Flow Diagram
bde2ht3 - bde2ht3 Sub-Data Flow Diagram
bde2ht3 - ps2gif Sub-Data Flow Diagram
bde2ht3 - HTML Document Flow Diagram
bde2ht3 - Flow Chart Diagram
9.0 Test Example - Schools
path: /usr/proj3/case/95f523/bde2ht3/test/...
Schools.dat
School Department diagram postscript image
Person diagram postscript image
Student diagram postscript image
School_menu.HTML
School_HG000001.HTML
School_HG000001.map
School_HG000001_HN000001.HTML
Bde2ht3 Documentation
1.0 Introduction (Manning)
Bde2ht3 is a BDE output browser that uses the World Wide Web's HTML programming environment. BDE users can now traverse their output files from their favorite Web browser such as Mosaic or Netscape. If ported to a PC, BDE output would be easily moved from one machine to another. This is an exciting way to explore BDE output files.
Our program utilizes some existing BDE code to help read in the data files. We take advantage of pr_load to read in data files and extract different pieces of the output, whether nodes or attributes. Bde2ht3 will then create the necessary HTML files to browse through the data. We also uses ps2gif to translate the BDE output Postscript files to a gif file required by HTML. A future group may wish to consider having BDE save in gif format so that this step would not be necessary. This idea will be discussed in more detail.
Our program needs a minimum of two files from the user as inputs. These files are fname.dat and fnameHG0000n.ps. Fname.dat is the BDE data file provided by BDE. The fnameHG0000n.ps file is the postscript representation of the output picture file from BDE for each diagram.
We tested our program against both Netscape and Mosaic. Many other browsers should have no difficulty in reading our HTML code as we adhere to HTML version 2.0.
Note: computer science machines used for this project:
"jupiter" - alpha machine running osf/1
"neptune" - VAX machine running Ultrix
1.1 Flow Diagram (Gee)
(Refer to diagram bde2ht3_DataFlowDiagram.ps)
This diagram shows an overview of the program and its three parts. The first and most important section is the actual BDE program. No modifications were necessary to BDE. When the user runs BDE, the necessary output files are created, including the file.dat and the corresponding fileHG#.ps images. Then we send the file.dat to bde2ht3 the main application to create the various HTML document files and the image maps, one for each image. The main application, bde2ht3, currently runs on "jupiter" and requires the use to be located within the subdirectory tree of public_HTML of the users home directory in order to use the CGI script for image maps. Then we send the various fileHG#.ps images to ps2gif which converts to postscript images to black and white gif images. This conversion application currently runs on "neptune" and requires to use of some system calls to various conversion scripts.
(Refer to diagram bde2ht3_bde2ht3SubDataFlowDiagram.ps)
The main application which creates the HTML documents is composed of several modules: bdemenu, HG2html, HG2imgmap, HN2html, and CG2html. Each module is responsible for creating the unique set of HTML documents or image maps for this BDE data file. We utilize pr_load within bde2ht3_main to effectively read in file.dat thus providing a means to parse data file to retrieve the required information needed for each module of bde2ht3, such as the HG, HN, and CG records. This part of the application runs on "jupiter" since functions used in pr_load would not successfully compile on "neptune". If bde2ht3 could be compiled on "neptune" then one could include ps2gif in the main application thus requiring only one application to be executed.
(Refer to diagram bde2ht3_ps2gifSubDataFlowDiagram.ps)
The second part of this application is ps2gif which is an image converter that takes a postscript file and converts it to a gif image. It should be noted that ps2gif is currently not executed by bde2ht3 because ps2gif required to be run on the computer science machine "neptune" which has /usr/bin/X11/pnmrotate and /usr/bin/X11/ppmtogif executable files. This converter creates and then destroys two intermediate files, fileHG#.ppm and fileHG#.ppm2, which are used for buffer swapping.
1.2 Link Flows (Gee)
(Refer to diagram bde2ht3_HTMLDocumentFlowDiagram.ps)
This diagram shows the various pages produced by bde2ht3 and how they link together for browsing. The file_name.HTML is the starting HTML document. It has a list of linked diagrams that one can view and one can jump to the indicated file_HG#.HTML. This is the HTML document that holds the gif image, fileHG#.gif, with a corresponding imagemap, file_HG#.map. This allows the user the ability to click on nodes in the diagram to jump to the HTML document describing the node, file_HG#_HN#.HTML, and file_HG#_CG#.HTML, or to link to another diagram file_HG#.HTML. The latest addition to bde2ht3 is the ability to have links between diagrams within on BDE file.dat. This is accomplished by changing the BDE data schema at the HN record level to rename the FSid to Hglink which is an 9 width character string that hold the identifier or primary key of the HG record to link to. If no link is wanted, then we use the HG000000 record which is a non-existent record (any other string would be fine here) just as long as one changes to test condition within module_HG2imgmap which determines the various jumps a node will have. Also, any node that is a link to another diagram will have its image map properties fixed so that the upper portion of the node is the link to the next diagram where as the lower portion links to the attribute page. Currently, these links to other HG diagrams is accomplished by manually editing the file.dat and changing the FS# in the HN definition rows to HG# which now represent the inter diagram links.
1.3 Execution Path (Gee)
(Refer to diagram bde2ht3_FlowChartDiagram.ps)
The flow chart diagram shows the execution path of the application. We create the HTML documents, images and image maps from the BDE output data files and postscript files. First, we use ps2gif to convert the postscript images to gif images. This is necessary when using pictures in HTML documents. There could be more than one postscript images corresponding to the various HG records indicating the different diagrams. Second, bde2ht3 is executed on file.dat, the data file generated by BDE. Pr_load is used to create a virtual database for the data file which allows efficient parsing of the record types. Then, bde2menu is executed which creates the initial HTML document. This HTML lists the HG diagrams for the data file. HG2imgmap is executed next. This creates an image map for each HG diagram that connects locations the image map to HTML documents. HG2html is executed fourth. HG2html creates the HTML document which displays the gif image with it's corresponding image map. HN2html is executed next which creates the HTML documents that represent each node of the diagram accessed by the image map. Finally, CG2html is run which creates the HTML documents that represent each caption graph of the diagram. Upon completion, there are several HTML document files and a number of gif image files with corresponding image map files that are all automatically linked by the bde2ht3 as they are created.
1.4 Execution Process (Gee)
It is a current requirement to run bde2ht3 within the subdirectory tree of ones $Home/public_html directory because we are currently using the Computer Science World Wide Web Server which will only look towards the user's $Home directory which is required when using the CGI script imagemap which allows the use of clickable maps.
After creating the file.dat and its corresponding postscript images, one can run the two parts of the application.
First on "neptune" execute
/usr/proj3/case/95f523/bde2ht3/base/ps2gif/ps2gif fileHG#.ps
for each postscript image which will produce the file fileHG#.gif. ps2gif converts one image at a time, so ps2gif will have to be run for each diagram within the file.dat, the HGs.
Next on "jupiter" execute
/usr/proj3/case/95f523/bde2ht3/base/executables/bde2ht3 file.dat
which will producer the various HTML documents and the image maps
corresponding to the converted postscript images that are now
gif images. Once all the files have been created, one can then
execute their local Web browser and either open the file
~$User/.../file_menu.html or open the URL http://www.cs.uml.edu/~$User/.../file_menu.html
which will open the various HTML documents for viewing.
2.0 Code Requirements
Currently, there are some requirements that both parts of this project have. One is the use of ps2gif on "neptune" and the other is the use of bde2ht3 on "jupiter", both of these systems are on the Computer Science network.
2.1 Ps2gif Requirements (Manning)
Ps2gif calls three programs in order to complete it's conversion. These are Ghostscript, pnmrotate and ppmtogif. Ps2gif also uses ps2ppm.ps as an input file for Ghostscript. All of these programs are available on neptune, so ps2gif must be run locally on neptune. If, in the future, all of these programs are compiled on other systems, this restriction could be removed.
This restriction will make it a bit more difficult to port bde2ht3 to other systems. A future modification may be to implement ps2gif from within BDE, thus removing these requirements. This is discussed in the Future Expansions section of our documentation.
2.2 bde2ht3 Requirements (Gee)
As with ps2gif, the main application bde2ht3 is also system restricted due to the use of pr_load code, which compiles fine on "jupiter", but causes compile time errors when calling its functions on "neptune". The source of these errors are unknown given that these function take predefined arguments and thus cannot be easily fixed or altered. Due to this restriction, we are using "jupiter" as the compiler system for bde2ht3. If ps2gif's dependencies could be removed, these image conversions could easily be implemented directly from bde2ht3.
3.0 ps2gif (Manning)
BDE currently supports two forms of output: the data file and the Postscript file. BDE data files, files with the name file.dat, contain though. BDE also supports saving a picture as a Postscript file. This is very useful for printing, but does not afford viewing with a Web browser. HTML prefers that files be saved in the gif format. Our project requires a converter to translate Postscript to gif. Ps2gif is the converter.
Ps2gif relies on a few other programs to do its work. Ghostscript will translate the file to ppm format using an input file, ps2ppm.ps. Once the file is in ppm format, we can run ppmtogif to finish our conversion. BDE prints in landscape mode. This causes the picture to be rotated by 90 degrees clockwise. Ps2gif uses pnmrotate to rotate the ppm file 90 degrees counterclockwise to correct this problem. We also found that the gif file is not the exact same size as the original BDE file, so images are off by a small amount. We correct for this using the sizes provided by the second line of the ppm file.
Relying on other programs causes extra dependencies to arise in our code. Ps2gif is now more difficult to port to other systems as the other programs must be there as well. Hopefully, a future group will add gif functionality to BDE to alleviate this dependency.
4.0 Detail Description of bde2ht3 Implementation Flow
bde2ht3 is the main conversion application that read in a BDE output data file and produces several HTML documents and image maps for the corresponding diagrams, the HG records, within the data file.
4.1. Begin at the Beginning (Rupal)
bde2ht3 consists of gif files, imagemap files and several HTML files. All the gif, imagemap, and HTML files produced have unique meaning. Once you understand the file naming convention, understanding bde2ht3 becomes easy. So, let us begin at the beginning. The naming conversion is simple, and it works as the following explains. One of the inputs to the bde2ht3 project is <file>.dat file, a dat file produced by BDE. This dat file contains information on the HG, CG, GX, HN, and HA records of the diagram drawn using BDE. There can be multiple subgraphs in a single .dat file (HG records), and these multiple graphs can have multiple captions (CG records) and caption text (GX records). Also, each graph contains several nodes (HN records), and each node has several attributes (HA records). The same .dat file consists of several other records, such as HL and HI records; however, these records are not kept track of in bde2ht3 because their information is not utilized in bde2ht3 project. Given this much information, bde2ht3 file naming convention is explained below.
4.2. File Naming Convention (Rupal)
bde2ht3 project begins at a file called <file>_menu.HTML,
where <file> is the same name as <file>.dat. So for
example, if the input .dat file to bde2ht3 was course.dat, the
HTML file would be called course_menu.HTML. <file>_menu.HTML
is the very first file viewed with a WWW browser. This file has
a list of HG records found in the <file>.dat file. All the
HG records are listed as hyperlinks in the HTML file. The HG listing
is called "HG00000N -- <file>", where N ranges
from 0 to some N number of HG
records found in the <file>.dat file. Each HG record has
two files associated with it, a gif file and an imagemap file.
The gifs and imagemaps are called by their corresponding HG record,
i.e., a .gif and imagemap files corresponding to HG000001 would
be <file>_HG000001.gif and <file>_HG000001.map respectively.
Therefore, for HG000001 to HG00000N, we will have <file>_HG000001.gif
to <file>_HG00000N.gif and <file>_HG000001.map to
<file>_HG00000N.map gif and imagemap files.
A <file>_HG00000N.gif file contains in it a picture of the diagram that <file>.dat file corresponds to. As explained in Section 3.0, the gif file is produced using ps2gif tool. The <file>_HG00000N.map file is used to define an imagemap on the <file>_HG00000N.gif file. The imagemap is for every HN record seen in the .gif file. There exists corresponding HTML files for all the HN records. When an HN record is clicked, this HTML file is retrieved. The HTML files corresponding to HN records are called, <file>_HG000001_HN00000N where N is 0 to some N number of nodes. There are N such HTML files, for HG000001 to HG00000N records. <file>_HG000001_HN00000N contains information on the attributes (HA records) corresponding to HN00000N node.
The next section describes the 'C' code written to retrieve the
HG, CG, GX, HN, and HA records from <file>.dat file, and
explains the code written to produce the various HTML files.
4.3. 'C' Modules Used to Create the HTML Files (Rupal)
bde2ht3 is written in 'C' language. All the necessary information, such as the HG, CG, GX, HN, and HA records from <file>.dat file are retrieved using pr_load utilities of BDE. The main module of bde2ht3 is called bde2ht3_main.c. The different routines invoked in the bde2ht3_main.c are described below in the sequence of their invocation:
5.0 Future Expansions
To allow for further development and enhancements to the bde2html
converter, bde2html is implemented so that it is scaleable and
manageable, using a module approach both in functions and sections.
During the design of our project, we found a few ways to expand
upon it in future class projects.
5.1 Having BDE save gif format (Manning)
Requiring both a BDE data and Postscript files seems to be duplicating one's effort. The data file contains enough information to create a Postscript file, so pstogif shouldn't be necessary. It would be interesting to create the gif format required by HTML directly from BDE. If our program was bundled into BDE, it would be possible, with effort, to create a new save option, "Save-as-HTML". Then, the HTML code would be created directly from BDE without requiring execution of a second program.
If the HTML code was created from within BDE, some more functionality
could be put into the HTML. In our version, we create the necessary
gif files from the Postscript output. The Postscript output has
the attribute names displayed in it. This means that the attribute
names are already displayed in the HTML. When an entity is selected,
the attributes are displayed again, although larger. If our code
was to be inserted into BDE, the attributes could be hidden when
the entire object is first displayed. This would give more meaning
to selecting entities.
6.0 bde2ht3 Testing (Rupal)
The core of the bde2ht3 work is now complete. To ensure that bde2ht3
works correctly, and to follow the clean-room approach, bde2ht3
project is now in its testing stage. The following tests have
been completed and a summary of the findings are listed below.
6.1 Testing ps2gif (Rupal)
ps2gif testing: ps2gif now runs using sh instead of perl.
- ps2gif was tested with BDE generated ps file bdetest.ps
- tested ps2gif on neptune, jupiter, arcturus and tern using the
command:
% ./ps2gif bdetest
- Results: ps2gif works successfully on neptune, i.e., (neptune)
a ppm file is created successfully with gs via pstoppm.ps.
This ppm file is then fed into pnmrotate command with an input
angle of 90 degrees counter clockwise. pnmrotate created a .gif
file with the desired rotation.
ps2gif also outputted a file called bdetest.tmp This file contains
two numbers which correspond to the height and width of the .gif
file.
(jupiter) ps2gif did not produce any error in execution. However, the bdetest.tmp and bdetest.gif files that were produced on jupiter were of 0 bytes in length.
(tern) Again, ps2gif did not work correctly, and gave sh errors upon execution. sh reported that it cannot find ppmtogif and pnmrotate executables on tern.
(arcturus) reported the same problem as tern.
- I tried getting a copy of pnmrotate and ppmtogif files from
neptune and downloading them on jupiter.
- I then tried to run ps2gif giving it the path of ../95f523.../base/test
for pnmrotate and ppmtogif files.
- ps2gif still doesn't seem to work.
- So it looks to me that pnmrotate and ppmtogif are platform specific
executables.
- So, ps2gif only works on neptune as to date.
6.2 Testing gif, imagemaps, HTML (Rupal)
To test bde2ht3, ran bde2ht3 with the command:
% bde2ht3 course.dat
If bde2ht3 is not supplied with a BDE .dat file, it gives an error message prompting the user to input a .dat file. This is nice. Though I think that it'd be better if the message was a Usage:: message instead of an error message!
I brought up the "main" HTML file up on Mosaic. The
file I brought up in Mosaic was called:
course_HG000001.HTML. Which is the correct name for the HTML file.
course_HG000001.HTML has an HREF that goes to course.gif file. course.gif that was displayed was not the course.gif that should be obtained from course.gif. But this is not a major issue. ps2gif will be used to obtain the correct course.gif file.
The image maps worked correctly displaying appropriate HA records for the HN records being clicked upon. However, the gif (x,y) coordinates of the HN records are a bit off from the (x,y) coordinates of the course.dat file. This needs to be fixed. We need to figure out the right scale factor between the (x,y) coordinates of the gif that ps2gif generates and the (x,y) coordinates that BDE ps file gives.
We are planning to use the height and width returned via ps2gif (and stored in bdetest.tmp in earlier test) to map this scale factor.
If the HN records are clicked somewhere in the middle, right HA
records are displayed.
6.3 Testing bde2ht3 from user's own public_HTML directory
(Rupal)
Testing is in progress.
The results of this test plus the fixes of problems found in the
earlier tests will be made available on Monday 12/18 during the
final presentation of bde2ht3.
6.4 Schools example Instructions (Gee)
(Instructions: /usr/proj3/case/95f523/bde2ht3/base/test/Doc_Schools.txt)
Example for bde2ht3:
Executables used:
/usr/proj3/case/95f523/bde2ht3/base/executables/bde2ht3* (on "jupiter")
/usr/proj3/case/95f523/bde2ht3/base/ps2gif/ps2gif* (on "neptune")
BDE files used:
/usr/proj3/case/95f523/bde2ht3/base/test/Schools.dat
/usr/proj3/case/95f523/bde2ht3/base/test/SchoolsHG000001.ps
/usr/proj3/case/95f523/bde2ht3/base/test/SchoolsHG000002.ps
/usr/proj3/case/95f523/bde2ht3/base/test/SchoolsHG000003.ps
Procedure:
Create a subdirectory under your $Home/public_html/... used here as $Directory (but does not include public_html) and copy the 4 BDE files listed above to this new directory.
For each postscript image run ps2gif to create gif images,
/usr/proj3/case/95f523/bde2ht3/base/ps2gif/ps2gif SchoolsHG000001
/usr/proj3/case/95f523/bde2ht3/base/ps2gif/ps2gif SchoolsHG000002
/usr/proj3/case/95f523/bde2ht3/base/ps2gif/ps2gif SchoolsHG000003
(be sure NOT to include the .ps file extension)
For the BDE data file run bde2ht3 to create the various HTML documents,
/usr/proj3/case/95f523/bde2ht3/base/executables/bde2ht3 Schools.dat
Now run your World Wide Web browser and open, http://www.cs.uml.edu/~$Home/$Directory/Schools_menu.html
See example HTML document code in 9.0 below.
7.0 Conclusion (Manning)
Our project provides a graphical user interface that traverses
BDE output files. HTML is rapidly becoming a standard for browsing
files and provides the capability of following links to related
files and pictures. BDE's current output is only Postscript files
which do not span multiple pages. HTML also has the capability
of being interactive which will help to make BDE more manageable.
8.0 Diagrams
Diagrams will be found in the directory cited above.
9.0 SchoolDB Test Case
Please refer to the path bde2ht3/base/test cited above, or to
the path supported by Dr. Lechner adjacent to his 91.523 Software
Engineering Course Syllabus below:
Addendum by RJLechner 95/12/22
------------------------------
I copied the bde2ht3 final report from
/usr/proj3/case/95f523/bde2ht3/base/doc/BDE2HT3_User_Manual_121895.txt
to ~lechner/public_html/bde2ht3/95fbde2ht3.txt
and added this addendum. I also copied
the bde2ht3/base/test files to directory
~lechner/public_html/bde2ht3/SchoolDBTest
as a test case that is accessible from any Mosaic or Netscape browser..
Mr. Amberish Nagarkatti converted this document to html format
in Oct 1996.
TBD: Add hyperlinks from this doc to the .ps figures
from PowerPoint and from bde - RJL 96/10/22.