SPECT Reference Guide

Nathan Stratton Treadway, Ray Ontko & Co. ( nathant@ontko.com)

$Revision: 1.7 $ $Date: 2000-05-08 16:54:06-05 $

This document describes in detail the operation of Ray Ontko & Company's SPECT tool (version 1.alpha1) for Brio.Portal. For an introduction to installing and using SPECT, please see the SPECT Getting Started instructions.

1. GENERAL

SPECT (Simple Portal-Enhancing Configuration Tool) is a simple-to-use utility for batch-loading reports and configuration information into Brio.Portal (ReportMart). It reads a control file and performs the processing it specifies. This control file is a text file in the format described below.

The program is written in Java and uses the ONE/API provided by SQRIBE. It is intended to be more robust than ONE/Script (in terms of error handling and speed), without requiring the user to know any Java. However, the source code is freely availabe so that sites wishing to customize the program can do so.

The program has been tested against ReportMart 1.5.x and Brio.Portal v6.x. (Note that there are some bugs in Portal v6.0; you should upgrade to at least v6.0.2.) There are separate branches of SPECT for v1.5.x and v6.x; the two versions are basically the same except for support of ONE/API features not available in the older versions of the API.

The program is released under the GNU General Public License. (See the "Licenses" section of the GNU web site or the COPYING.TXT file included with the SPECT distribution for more information.)

The following general points apply to all aspects of SPECT's operation:

Messages sent to the log file start with "ERROR:" or "WARNING:" and contain line number in the control file where the error occurred (or the line number where the action keyword was found when the action itself fails).
Control-file lines that cause errors should be written to a "BAD" file, if specified. (Control-file lines processed but not written to the "BAD" file are written to a "GOOD" file, if specified.)
Certain keywords allowed for an object do not apply for all actions. By default, a warning message will be generated if keywords specified in the control file are being ignored (but processing on that action will continue). This behavior is configurable by the SETCONFIG command.

2. CONTROL FILE SYNTAX

The control files are ordinary text files. White space is ignored (except between double quotes.) Comments start with a "#" character and continue to the end of the line.

There are two basic units in a control file, actions and configurations. An action statement looks like this:

  <ACTION> <OBJECT_TYPE> object_name <KEYWORD>=value <KEYWORD>=value ... ;

There can be any number of keyword-value pairs following the object type. The statement can be broken onto multiple lines of the control file, as required. Actions, object_types, and keywords are not case sensitive. Object_names and values should be enclosed in double-quotes if they contain white space.

Configuration statements look like:

  SETCONFIG <KEYWORD>=value <KEYWORD>=value ... ;

Again, there can be any number of keyword-value pairs, the word "setconfig" and the keywords are not case sensitive, and the values should be enclosed in double-quotes if they contain white space.

For example:

setconfig log-file=rm_loader.log when-preexists=error;

create user test1 description="test user" password=Portal
            group=test_group permissions=755;

setconfig when-preexists=warning;
create report "Sample Report" description = "This is the sample."
       filespec=/tmp/sample.spf mime-type=application/x-spf
       category="/Miscellanous_Merchandise/Samples" 
       OWNER=test1 GROUP = test_group;

3. SETCONFIG

Here are the configuration settings recognized. Each setting takes effect as soon as the SETCONFIG command is processed, and stays in effect until a new setting is specified in another SETCONFIG command.

Many of the settings can take a value of IGNORE, WARNING, or ERROR. These values behave similiary for all settings, as described here:

IGNORE -- don't print any error; write record to GOOD file if active.
WARNING -- print a WARNING message; write record to GOOD file.
ERROR -- print an ERROR message; write record to BAD file.

Other settings take a file specification. Normally, this is simply the name, possibly with a path, of the file to use. The file is overwritten if it already exists. If the filename starts with the characters ">>", then new lines are appended to the end of the file (if it already exists). If the filename is "-", then standard output is used. Finally, if the filename is "*", then output for the given setting is turned off.

WHEN-PREEXISTS

Controls what happens when the object specified in a CREATE action already exists. (This does not apply to JOB or FILE objects; see WHEN-MULTIPLE-PREEXISTS.) DEFAULT: WARNING.