This manual describes how to run and configure the Platform for Information Applications (PIA). Developers intending to create applications should also consult the Author's Guide.
(For probelms, check the troubleshooting guide.)Topics covered include:
For information on installing the PIA and developing applications, see the PIA Document List.
You need the following software to run the PIA:
JRE 1.1.3 or higher, is
needed to use the software. Programmers wishing to modify the code will
need a Java Development Kit JDK.) Java for Solaris and
Windows can be obtained from
java.sun.com (direct links
to JRE or
JDK). Java for
Linux can be obtained from
www.blackdown.org
The PIA is known to run under Java 1.1.3 and and Java 1.2 on Solaris, Linux, and Windows. It runs on Linux under Kaffe, but there are some problems with compilation.
tar and
gunzip on unix, winzip on Windows).
The pia command is actually a start-up script which attempts
to locate the PIA's install directory, and to set up some necessary
environment variables.
PIA/bin/pia; it eventually
invokes the auxiliary script PIA/bin/pia_wrapper, which
sets up the Java environment.
PIA/bin/pia.bat
It is also possible to start the PIA directly from the Java runtime with the command:
java org.risource.pia.Pia option...
pia [option]... [property=value]... filename?
The PIA's command-line options are:
-version-d -v-verbosity number -verb number -verbosity-home directory -port number -p number -port-vport number -port specifies, or 8888. -rport number -port specifies, or 8888. -root directory $HOME/.pia on a Unix machine. -vroot directory PIA_HOME. -host name -config file _subsite.xcf; setting this to "" will prevent
the PIA from looking at configuration files. -site file The filename parameter supplied on the command
line may specify either an ordinary file, in which case it is used as the
name of the site configuration file, or a directory, in which case it is
used as the real root, and no virtual root will be used.
Parameters specified on the command line override anything specified in the PIA's top-level configuration file, which in turn overrides anything specified in the environment variables.
The PIA uses the following environment variables:
PIA_HOME
PIA_ROOT
$HOME/.pia on a Unix machine. On
Windows, the default directory is
c:\PIAUSERS\username (if a username is not
available nobody is used).
The PIA acts as a Web server. Assuming you have gotten the PIA to run in
its default configuration, you should now be able to browse to http://localhost:8888/ in order
to access the PIA's own web pages. If the default configuration is
different and you have run the PIA from a command line, it will have
printed out a line like:
Point your browser to <URL: http://blackroot.crc.ricoh.com:8888>
after initializing, and you can cut-and-paste the URL on that line into your browser and go from there.
There are some applications--such as a browser proxy and browsing-history
system--which require that your browser use the PIA as a proxy. This
enables the PIA to process any incoming and outgoing pages as you would
like. See the Proxie for more details.
The list of available applications and their descriptions can be found in the Application Guide.
If you want to use the pia as a XML-to-XML processor---reading and writing
XML files using active tags, no web ports involved---you can use the
command process [filename], which sends the converted XML
directly to the console (standard output). The command syntax is:
process [option]... input_filename
The command-line options are:
-e-h-o filename-p-t tagset-namexhtml).-s-q-v-d=== this section needs more work ===
When the PIA starts, it looks for either a configuration file or a ``root'' directory (which should contain a configuration file). The PIA will look for its top-level configuration file in the following places:
The default configuration file name is _subsite.xcf; this can be
changed with the -config command-line option or in the top-level
configuration file. Any directory may contain a configuration file with the
specified name, except that the configuration file in the root is ignored if a
separate top-level configuration file is specified.
Once a configuration file is found, all of the PIA's configuration
information is loaded from it -- where to look for active pages, which ones to
start up immeditely in the background (such as broswer-proxies), what ports,
filename-extension mappings, and tagsets to use, and so forth... even the path
of the root directory can appear there. Several sample configuration files can
be found in the directory $PIA_HOME/Config/Site/.
If you change any configuration options (for example, by editing a
_subsite.xcf file or renaming a tagset file), you should
re-start the PIA to ensure that the server knows about those changes. The
results may be very confusing otherwise.
=== this section needs LOTS more work === In particular, it needs a list of configuration options.
The PIA is maintained using the CVS version control system, and a public
CVS repository is available on RiSource.org. See www.risource.org/PIA/cvs.shtml for more information, including
how to log in to the anonymous CVS server.
CVS version control information is included in the tar file
you used for installation; once you have logged in (which you only need to
do once) all you have to do in order to update your copy of the PIA to the
latest version is:
cd $PIA_HOME cvs update -d -P
The CVS repository is updated more frequently than the tar
archive -- essentially whenever a developer feels that the portion of the
PIA they have been working on is stable enough for others to try.
You can check for known bugs by going to http://www.risource.org/PIA/
Questions, problems and comments should be directed to PIA-bugs@risource.org.