RISC DISC 1/RISC_DISC_1.iso/pd_share/apps/powerbase/Docs/ScriptFile

Text File | 1994-04-10 | 9.0 KB | 245 lines

                                Script Files
                                ============

Powerbase incorporates a SCRIPT LANGUAGE which enables you to control some
of its features from a SCRIPT FILE. Using script files you can automate jobs
which need to be done frequently. Print jobs are the most obvious example,
and most of the script commands have to do with printing, but there are
others.

Script files are plain text files (created with !Edit) and are executed by
simply dragging them onto the main Powerbase window. All the commands in a
script file must be in upper-case letters, preceded by '!', and may be
followed by a parameter string, separated from the command by a single
space. Here is a full list of the commands followed by a description of
their functions:-

        !SCRIPT POWERBASE,END,<filename>
        !COMMENT
        !SELECTION <filename>
        !PRINTOPTS <filename>
        !QUERY <search formula>
        !CSV <search formula>
        !EXPAND ON,OFF
        !DATE ON,OFF
        !UPPER ON,OFF
        !UNDERLINE ON/OFF
        !CASE ON/OFF
        !INDEX ON/OFF
        !FIRST ON/OFF
        !SHRINK ON/OFF
        !HEADINGS D,T
        !PITCH 5,10,12,17
        !TITLE <title>
        !PAGE 70,66 etc
        !LINESPACE 1,2 etc
        !LMARGIN 1,5,10 etc
        !TMARGIN 1,5,10 etc
        !SPACER <spacer string>
        !COLWIDTH 3,5,10 etc
        !FORMAT HORIZONTAL,VERTICAL,LABEL,TABLExx
        !DESTINATION WINDOW,FILE,PRINTER
        !LABEL n,h,v,l,r,ON/OFF,ON/OFF
        !DELETE <primary key>
        !INSERT (followed by fields, each, inc. 1st, on its own line)
        !IMPRESSION <'Impression' DDF string> [Not first]

!SCRIPT
=======
All script files must begin with the line !SCRIPT POWERBASE. This is how the
program distinguishes a Powerbase script from other text files. You should
make !SCRIPT END the last line of the file. Finally, the command can be used
to "chain" another script file by following it with the name of the new
file, i.e. by using the form !SCRIPT <filename>.

!COMMENT
========
Use to insert explanatory comments in a script file. The rest of the line
after the command is ignored.

!SELECTION <filename>
=====================
The parameter should be the name of a selection file in the PrintRes
directory. The command will install the selection just as though you had
dragged it from PrintRes to the Powerbase window yourself. If you issue the
command without a parameter the current selection will be cleared.

!PRINTOPTS <filename>
=====================
The parameter should be the name of a print options file in the PrintRes
directory. The options will be set just as if the the file had been dragged
from PrintRes to the Powerbase window.  Issued without a parameter causes
the default options to be set.

!QUERY <search formula>
=======================
This command is used to print a list. It gives the same result as typing the
search formula into the Match window and clicking OK. If you first issue a
!DESTINATION FILE command you can use a script containing a list of !QUERY
commands to create a batch of reports as text files in PrintJobs. !CASE and
!INDEX also affect the behaviour of this command if issued beforehand.

!CSV <search formula>
=====================
This works similarly to !QUERY but creates CSV files in PrintJobs instead of
text files. There is no need to issue a !DESTINATION FILE before use. !CASE
and !INDEX may be used as above.

!EXPAND
=======
Like many of the commands which follow, this is used to select or deselect a
button in the print options window . !EXPAND ON selects the button which
causes fields to be expanded by reference to a linked validation table.
!EXPAND OFF (or just !EXPAND by itself) deselects the button.

!DATE
=====
Turns date and time stamping ON and OFF. It works in exactly the same way as
!EXPAND.

!UPPER
======
Forces upper-case printing when followed by ON, normal upper/lower case
printing otherwise.

!UNDERLINE
==========
Turns underlining ON and OFF when output is sent to the printer. You will not
see any underlining when the report is displayed in a window by Powerbase,
but underlining will occur when the windowed output is subsequently printed.

!CASE
=====
Turns the 'Case specific' button in the Match window ON and OFF.

!INDEX
======
Turns the 'Use index' button in the Match window ON and OFF.

!FIRST
======
Followed by ON this causes any header information, such as date-stamp or
title, to appear on the first page only of a report. When OFF the header is
printed on every page.

!SHRINK
=======
Followed by ON this removes surplus "white space" between the columns of
reports in Vertical format.

!HEADINGS D
===========
Causes descriptors to be used as field identifiers in a report. !HEADINGS T,
or without any parameter, causes tags to be used.

!PITCH <cpi>
============
The parameter should be 5, 10, 12 or 17, representing double-width, pica,
elite and condensed respectively.

!TITLE
======
Followed by a text string causes the string to be used as a title on
subsequently printed reports.

!PAGE <lines>
=============
Use to set the page length for reports. 70 is correct for A4, 66 for
American letter.

!LINESPACE <n>
==============
Sets the line-spacing to n lines. The default is 1, i.e. no blank lines
between lines of report.

!LMARGIN <n>
============
Sets the left margin to n character spaces

!TMARGIN <n>
============
Sets the top margin to n lines

!SPACER <string>
================
Specifies the string to be used to separate columns of printed data in
reports using 'Horizontal' or 'Table' format.

!COLWIDTH <n>
=============
Sets the width of the blank columns used in 'Table' format to n spaces.

!FORMAT
=======
Follow this command with HORIZONTAL, VERTICAL, LABEL or TABLE. In the last
case the number of columns required must be appended as a second parameter,
e.g. TABLE 8.  If any other parameter is used, or !FORMAT is issued by
itself, the HORIZONTAL format is used.

!DESTINATION
============
Should be followed with WINDOW or FILE or PRINTER. The first causes reports
to be displayed in a window, from which they may be subsequently saved. FILE
causes output to be sent to a text file specified by the user. PRINTER
causes output to go directly to the printer without being previously
displayed or saved.

!LABEL
======
This is used to define a label specification to use with the LABEL format.
It requires 7 parameters, separated by commas:

    (1) The number of labels across the page (1,2 or 3)
    (2) The horizontal label pitch (i.e. left edge to left edge) in inches.
        This is only meaningful when (1) is 2 or 3.
    (3) The vertical label pitch in inches.
    (4) The number of lines to be printed on each label.
    (5) The line which is to be replaced, if blank, by the last field in
        the selection. If nothing is entered here (2 commas together) then
        no substitution is performed.
    (6) If ON is entered the the primary key will appear on the label (in
        brackets) as an identifier.
    (7) If ON is entered blank fields will be skipped when printing.

!DELETE <key>
=============
This provides a way of deleting records from the database. The parameter
must be the primary key of the record. The benefits of this command may not
be at all obvious. Suppose you have a text file giving details of records
which must be deleted from the database. If such a job is going to occur at
all often it could be worthwhile to write a customised program to read the
text file and generate the primary key of each record, then output the
results as a Powerbase script file. The whole batch of records can then be
deleted by simply dragging the script into Powerbase. Not worthwhile for ten
records, perhaps, but could be for a hundred. Note that all 6 subfiles will
be searched for the records to be deleted.

!INSERT
=======
This is the counterpart of !DELETE and is useful in similar circumstances.
In this case the command must occupy a line by itself and be followed by the
record to insert, one field to a line. It is the user's responsibility to
ensure that the lines are not too long for the database fields into which
they are placed and that the number of lines following each !INSERT is the
same as the number of fields in the record. Don't forget to leave blank
lines for empty fields!

!IMPRESSION
===========
Used in conjunction with !QUERY to generate a report in text-file format,
this allows you to insert 'Impression' formatting commands at the start of
the text-file. A script may, for example, execute a series of !QUERY
commands and the resulting files are to be all selected together and dragged
into an 'Impression' document. To make each file go into a new frame you
need to make each begin with {nextframe}. This can be achieved by placing
the script command !IMPRESSION {nextframe} before the first !QUERY. You do
not, however, want {nextframe} to begin the first file created, or the
'Impression' document will have a blank frame on its first page. To suppress
the effect on the first file use the form: !IMPRESSION {nextframe} Not
first. There must be a space between the '}' and the 'N', but the 'Not
first' string isn't case sensitive.