src/test/README

		   STEP Class Library Example Suite
			Last Update:  2/27/98

These programs are intended as a set of examples for programming with
the STEP Class Library (SCL) -- e.g. instantiating entities,
manipulating data, using the dictionary classes, etc.  This file
describes what these programs are and how to get them running (if
configure fails to build them). The configure installation script
should have correctly built:

- the SCL code for the data/example/example.exp EXPRESS schema. It
should have installed it using the <arch>/bin/mkProbe script with the
-i option. This is the schema and corresponding SCL Schema Class
Library that is used by these SCL applications.

- the executables for these SCL applications under the corresponding
directories in <arch>/testbuild/.

If configure did not have success you will need to build the example
schema with the mkProbe script using the -i option. This process is
detailed in the top-level README.scl that comes with this releaes. You
will also need to build these SCL applications under <arch>/testbuild/. 
This process is detailed below under 'Building and running the test
programs if configure fails to build them'.

Other Software
~~~~~~~~~~~~~~

You will need some other software to use this package to its fullest.
First, you will need the STEP Class Library release (which includes
this directory.)  Secondly, to make full use of the scl2html program,
you will need an HTML browser such as Netscape.  Oh, and most
importantly of all, you need a C++ compiler that can build C++ 2.0
source.

The Programs
~~~~~~~~~~~~

p21read

	The simplest example program.  It reads a Part 21 file and
writes it out.  Errors found in the file are reported to standard
error (using the underlying fedex parser).  This program's primary
usefulness is to illustrate the components necessary to build an
application which uses the SCL.


tstatic

	A simple instantiation test.  This creates some static
instances of entities from the 'example' schema, puts some data in them,
and prints them out.  This also uses a simple iterator class to pass
over an array of pointers to STEPentities.  The entities are printed
in STEP Exchange file format.


treg

	This test uses the dictionary classes of the SCL, the
Registry, to instantiate an object of each entity type, and give them
some data by analyzing the attribute types via the registry (and not
knowing what objects we have).  Also, all instances are kept track of
with an instance manager, which, among other things, allows us to keep
an organized STEP file of the data without explicitly maintaining it.
The resulting objects are output in STEP Exchange File format both to
the screen and to an optional file.

NOTE:

The output file that treg produces will not necessarily be a valid
STEP Exchange file.  While treg happily produces values for most
entity attributes, it will leave attributes of type SELECT, AGGREGATE,
or ENTITY blank.  Since in many cases, these attributes will not be
optional, a subsequent STEPread of the file will flag errors with the
data.  The illustrative character of treg, however, is satisfied as
is.


tio

	Some simple tricks with STEPfiles and the instance manager.  A
given STEP Exchange file is read in, its objects are instantiated, and
the resulting instances are printed out.  The same file is read again,
and a duplicate set of objects is appended to the ones already read.
Finally, the resulting list of instances is written to the screen and
an optional output file in STEP Exchange file format.  As noted above,
tio may choke on some STEP files produced by treg... this is not tio's
fault, but treg's.  A sample STEP exchange files (testfile.step) is
included.


scl2html

	This program, when linked to a 'compiled' schema, will use the
Registry information to create a suite of HTML documents describing
the structure of the schema.  A 'page' is created for each entity,
describing its attributes, inheritance ancestry, and subtypes,
complete with hypertext links tying the pages together.  While perhaps
not the most useful application as it is (the exp2html utility
produces more complete output, and doesn't require compiling the
schema and the program linked to it), it is plausible that forms and
such could be added to create a Web-accessible Data Probe.  As it
stands, it demonstrates several methods for accessing the registry
information in a schema-independant manner.

scl2html requires a Web browser or live-hypertext HTML editor to be of
any use beyond reading the HTML result files.

treg, tio, and scl2html are schema-independant; while they link to
'example''s class library by default, they can be rebuilt to access
the class library of any schema.  See below for details.  tstatic
requires 'example''s class library to run.


Building and running the test programs if configure fails to build them
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before building the tests, you will need to have built the header
files and class library for the 'example' schema included with this
release (data/example/example.exp) (this will only be necessary if
configure failed to build it correctly). It should be built with the
mkProbe script using the -i option.  See the top-level README.scl for
complete instructions.

Next, you'll need to look at the file <arch>/testbuild/schema-loc,
which is included by all the test program Makefiles.  This file
defines the locations of the example schema library and the
appropriate make_rules file. If the library for the example schema
was built using the mkProbe script with the -i option then the macros
in schema-loc defining the schema location should be correct. If not,
you will need to change the schema related macros; if you do this, keep
things defined in terms of $(SCHEMA_NAME), otherwise, you will create
problems for the other Makefiles.

To build all the programs, just type 'make' in the <arch>/testbuild/
directory. To build individual tests, just type 'make' in their
directory under <arch>/testbuild/.

The script <arch>/testbuild/runtests executes all the test programs,
except for scl2html.  For best results, execute as follows (this is in
csh):

	% runtests >&! tests.out

To run scl2html, it is recommended that you create an empty directory and
run it from there, as it creates several .html files as its output:

	% cd scl2html
	% mkdir tmp
	% cd tmp
	% ../scl2html

This can save you a lot of cleanup work if you change scl2html to use
a more complex schema than 'example'.


Using Alternate Schemas
~~~~~~~~~~~~~~~~~~~~~~~

All the programs except for tstatic can be built to use any schema
class library; tstatic _must_ use 'example'.  Building any of the
programs to use an alternate schema is very easy to do.

First, as with 'example', build your Schema Class Library.  If you are
again using mkProbe with the -i option, <arch>/testbuild/schema-loc
need not be altered. (Or you may edit the SCHEMA_NAME macro in
schema-loc to specify the name of the schema you just built as
reflected in the directory and library name for the schema.)

Then, in the directory of the program you want to build, type:

	% make SCHEMA_NAME=<new_schema_name>
	or if you already edited the SCHEMA_NAME macro
	% make

where <new_schema_name> is the name of the schema, e.g., 'example.'

Any of the other schema-loc variables can be set this way (at least
using GNU make), so if you want to keep your schema class libraries
somewhere else you can specify the locations along with the
SCHEMA_NAME on the command line (this is all one line):

	% make SCHEMA_NAME=my_schema SCHEMA_DIR=~rms/schemas/my_schema
	    SCHEMA_LIB_DIR=~rms/probes/my_schema


Other Source Files in this Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

needFunc.{h|cc}

	The needFunc source code is needed to create SCL applications
that do not link with the Data Probe libraries.  It is installed in
the <arch>/lib/ directory during installation of the SCL software.


Known Problems
~~~~~~~~~~~~~~

If you are using Gnu g++ version 2.5.8 with this program you might
encounter a problem. If you run make depend on the various makefiles of
the separate applications makedepend may insert a dependency for the
nonexistent file _IO_config.h ( this particular dependency was
generated by makedepend when it encountered the libio.h file of the
g++ package. )  This may be caused by makedepend being unable to
follow C++ preprocessor conditionals in header files.

Another version of makedepend (unfortunately the exact version number
is unknown though maybe it's newer) seems to have fixed the problem at
NIST.  It is up to the individual user to find the makedepend version
that will work well with this package if makedepend is used at all
(it's not necessary).


More information
~~~~~~~~~~~~~~~~
See the top level README file of this release for more information on
the software.


Acknowledgments 
~~~~~~~~~~~~~~~
These examples were developed by Ian Soboroff, a student formerly
employed at NIST.
