home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-387-Vol-3of3.iso
/
p
/
pb920430.zip
/
PBSELDOC.TXT
< prev
next >
Wrap
Text File
|
1992-04-28
|
55KB
|
1,748 lines
____________________ PB Select Equations. ____________________ PB Select Equations. ____________________ PB Select Equations.
Contents. Contents. Contents.
Contents.............................................1
1 Introduction.........................................2
2 What Are Select Equations?............................2
3 Writing Select Equations - Part 1.....................3
The Equation Syntax..................................4
Example Select Equation Creation.....................6
4 Writing Select Equations - Part 2.....................8
The Equation Syntax..................................8
Constant Substitution................................9
5 Reading Select Equations..............................12
6 Reference Section.....................................13
Equation Syntax Summary..............................13
Parser Directives....................................15
PFH Item Values......................................17
Parser Error Messages................................18
PB Default Select Equations..........................19
Example Select Equations.............................20
Address for problems and comments....................21
1 Introduction. 1 Introduction. 1 Introduction.
The Pacsat Broadcast Protocol (PBP) defines what a Pacsat File
Header (PFH) is and how it is used to handle messages aboard a
Pacsat File Server. The PFH contains information fields written
mostly by the sender of the message. The PFH is used by receiving
stations to generate a directory of server files, from which the
appropriate files can be downloaded. The contents of the PFH is
clearly important in getting a message from its source to its
destination.
Most users of a Pacsat server use the most widespread
implementation of the PBP, the program PB, written by G0K8KA. The
program allows users to receive a directory from the server,
showing which files are currently stored, and then to request a
file from the directory. The server deals with each user's request
in turn, sending the actual file contents. The broadcast nature of
sending data in this way means that users will automatically
collect messages of general interest (if they wish), but a message
must be requested by its intended recipient to ensure its
reception.
The increasing number of files carried by servers and the
increasing level of automation of groundstations demands that files
should be reliably selected and also requested as efficiently as
possible. The select equation mechanism is designed to improve
both the efficiency and the automation of message selection and
hence transfer.
2 What Are Select Equations? 2 What Are Select Equations? 2 What Are Select Equations?
(In describing what select equations are, the next paragraph
briefly reviews what the PFH is for.)
The PFH is the Pacsat File Header, a block of data at the beginning
of every file kept on the server. It contains items of information
about the file such as its name, length, data checksums and so on,
which are used by the server and other routing computers to ensure
correct handling of the file. Other items contain information such
as the callsigns of the sender and intended recipient, the subject
of the file and keywords describing its contents. Those items are
used to ensure that users of the server can see that the file is
intended for them or that it may be interesting to them.
Select equations are used to search through the directory for files
which the user could be interested in. An 'equation' is simply a
list of tests which a PFH must pass before its file is selected. A
select equation specifies which PFH items to test and what they
should be. Select equations can be used to filter the directory
display or to automatically mark files for downloading.
To filter the directory display, each PFH in the directory is
compared with the equation and those that match can be displayed.
The download equations test each PFH and automatically select files
2
to download, leaving the user free to 'browse' though the directory
manually.
The program PB already uses select equations in the directory view
screen where the user can select a subset of files to see by
choosing a function key. Each key is associated with a different
subset of files described by a select equation, but these equations
are built into the program.
PB has now been extended to allow users to create their own
equations.
3
3 Writing Select Equations - Part 1. 3 Writing Select Equations - Part 1. 3 Writing Select Equations - Part 1.
A select equation can be as simple or as complex as required. To
get an idea of what the equations can look like, see the examples
below. For a concise list of features see the reference guide. This
section explains how select equations are written and includes a
syntax definition, explanations of what each term means and lists
of all terms and symbols recognised.
Select equations are kept in a file called the equation file which
is read by PB when it starts up. It is an ASCII text file and can
be created using any text editor. The equation file can contain up
to fifteen equations: twelve are associated with the function keys
and the other three are called download equations because they
control the automatic download selections. Not all equations need
be defined and it is possible to begin experimenting with only one
equation in the file. The file may contain comments on lines which
begin with a ';' as in the PB configuration file.
Each equation may all be on one line or spread over several lines
and may be indented or separated by any number of spaces, tabs,
newlines, etc. Any layout which does not change the meaning of any
part of the equation is acceptable to the equation parser. Its
layout should make it as readable as possible, just as in (most)
programming languages.
Some Example Select Equations.
( F1 (destination = foobar) )
( F2 (destination = ALL) and (title = image) )
( F3
(
(destination = ALL)
or
(destination = mycall)
)
and (file_type != 1)
and (file_type != 2)
)
4
The Equation Syntax. The Equation Syntax. The Equation Syntax.
All equations are surrounded by brackets: an open bracket to start
and a close bracket to finish. Between the brackets there must be
the equation 'name' and the equation itself.
This rule is written formally like this:
'(' NAME EQUATION ')'
Here NAME should be replaced by one of the 15 possible equation
names and EQUATION should be replaced by a list of tests. The
brackets should be used as shown but without the quote marks.
The equation name should be chosen from:
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 auto priority never
The twelve function key names are for the equations which filter
the directory display. The remaining three are to define a set of
equations which control the automatic downloading of files. PB
will check every incoming PFH if it matches these equations and act
accordingly. If the PFH matches one of the equations 'priority' or
'auto', the file will be marked for automatic downloading. If the
PFH matches the equation 'never', it will never be downloaded or
'grabbed'.
One important feature to note is the order in which an incoming PFH
is tested with each equation. The PFH begins with the default
download status 'grab'. First the 'never' equation is tested
followed by the 'priority' and 'auto' equations. If a PFH were to
match both the 'never' and the 'auto' equations, for example, it
would still be downloaded. This is so that the 'never' equation may
be coarse and exclude many files which are then selectively
included by the 'auto' equation.
The syntax for EQUATION can in turn be described formally like
this:
TEST { COMBINATION TEST }
Here TEST should be replaced by a single test clause and
COMBINATION should be replaced by one of the combination operators
which combine the result of two tests. The curly brackets indicate
that what they enclose can be repeated any number of times,
including zero.
5
The syntax definition above means that it is possible to have just
one test, but as soon as more tests are used, they should be joined
together with combination operators.
The combination operators are:
and & && or | ||
There are actually only two types: the 'and' type and the 'or' type
- the other symbols grouped with them are alternatives, supplied to
allow users to write equations which are either concise or
readable. There are alternatives for other symbols recognised by
the select equation parser, intended to make writing select
equations easier.
Now we come to the syntax of the TEST clause itself:
'(' PFH_ITEM COMPARISON CONSTANT ')'
Here PFH_ITEM should be replaced by the name of the PFH item which
is being tested, COMPARISON should be replaced by one of the
comparison operators and finally CONSTANT should be replaced with
the actual value that the PFH item is to be compared with.
The COMPARISON operators are:
Symbol Meaning
= equals
== equals
!= not equal
<> not equal
> greater than
< less than
>= greater or equal
<= less than or equal
6
The PFH_ITEM name can be chosen from the following list:
PFH ITEM Type Description
file_number number server internal file
number
file_name string server internal file name
file_ext string server internal file
extension
file_size number file length in bytes
create_time time time when file first
created
last_modified_time time time file last modified,
e.g. SEU
seu_flag number flag set if SEU detected
file_type number code describing file
type*
source string callsign of sending
station
ax25_uploader string callsign of uplink
station
upload_time time time when file uploaded
download_count number number of acknowledged
downloads
expire_time time time when file is deleted
from server
precedence number arbitrary message urgency
classifier
compression_type number code describing
compression type*
bbs_message_type charac coded char. used by BBS
ter operators
bulletin_id_number string unique name used by BBS
operators
title string arbitrary message title
keywords string words describing message
contents
file_description string extended description of
file type
compression_description string extended description of
compression
user_file_name string original filename used by
sender
*These items have several agreed values which are listed in
the reference guide.
There is a fuller description of each item and what it is used for
in the PBP documentation, but in practice the select equations must
test those PFH items actually used by sending stations.
The final term left to be defined is CONSTANT. The constant can be
a string, a character, a time or a number. The type should match
that of the PFH item being tested, as indicated in the list above.
A constant is any sequence of characters excluding space, tab and
newline and also excluding any characters from any of the operators
and the brackets. If a string constant must include any of the
7
forbidden characters it should be enclosed in double quotes. Here
are some examples of valid constants:
foo BAR Fly2High 42 10% *PB* "frog(s)" "Seeing*s?"
All constants are basically string constants, except that character
constants should be just one character long. Number constants
should contain numeric characters, although the constant may be a
hexadecimal number if it begins with '0x' (zero x). String
constants may also contain the wildcard characters '?' and '*'. The
wildcard '?' will match any single character and the wildcard '*'
will match any number of any character. Time constants should also
be numbers and may be hex numbers.
The term CONSTANT is described in more detail in the section
Writing Select Equations (2). The extended description also covers
special time symbols which represent time numbers and other
facilities for creating time values.
Example Select Equation Creation. Example Select Equation Creation. Example Select Equation Creation.
The preceding explanation of the select equation syntax is now
explained by way of an example. The starting point is at the end of
the syntax definition, with the TEST clause.
Suppose the equation should match any file addressed to the
callsign 'foobar'. The PFH item to test is clearly 'destination'.
Its type is string, so the constant must be a string constant. The
callsign might be used as part of an address string, so wildcard
characters are used to search for an occurrence of the callsign
anywhere in the PFH item.
PFH_ITEM destination
COMPARISON =
CONSTANT *foobar*
The TEST clause can now be assembled:
( destination = *foobar* )
There is only one test in this equation, so there is no COMBINATION
operator required and the TEST clause becomes the EQUATION.
The EQUATION is assembled into a complete definition with the
chosen equation NAME 'F1'.
The first complete select equation, assigned to function key
1.
( F1 ( destination = *foobar* ) )
More complex equations such as those in the examples can be built
up following the same procedure. The next stage is to add a second
TEST clause and to combine the two TESTs with one of the
8
COMBINATION operators 'and' or 'or'. The derivation will look
something like this:
The first TEST is taken from the previous example:
PFH_ITEM destination
COMPARISON =
CONSTANT *foobar*
TEST ( destination = *foobar* )
Now a second TEST is added:
PFH_ITEM keywords
COMPARISON =
CONSTANT *news*
TEST ( keywords = *news* )
The two tests can be combined with a COMBINATION operator:
COMBINATION and
EQUATION (destination=*foobar*) and (keywords=*news*)
NAME F2
(F2 (destination = *foobar*) and (keywords = *news*) )
The second complete select equation, assigned to function key
2.
The features described in this section, together with the above
examples should be enough to create almost all the select equations
required. There are further facilities for forming more complex (
and powerful) equations but they can be used as and when required.
The next section covers the extra facilities and will give an idea
of what is available, but it need not be understood to get the
equations above working.
9
4 Writing Select Equations - Part 2. 4 Writing Select Equations - Part 2. 4 Writing Select Equations - Part 2.
In Part 1, the basic syntax for defining the equations was
explained. Some facilities were omitted for clarity and are
described here in full.
The Equation Syntax. The Equation Syntax. The Equation Syntax.
The syntax for the full definition was stated as: '(' NAME
EQUATION ')'
A more accurate definition is this: '(' NAME [ KEYTITLE ]
[ MASKS ] EQUATION ')'
Here the terms NAME and EQUATION are known and remain as before.
The two extra terms are optional (denoted by the square brackets)
which is why they could be omitted from earlier explanations. The
first, KEYTITLE is used to assign a title string with a function
key definition, just like in the default equations which PB now
uses.
The syntax for a KEYTITLE is: CONSTANT 'keytitle'
Here CONSTANT is replaced by any string and the command 'keytitle'
is used as shown without the quotes. Note that the actual title
goes before the command. The result is that the string is displayed
on the message line of the display each time the function key is
chosen. This is useful for reminding the user of what the selection
represents, useful now that this can be easily changed.
An example:
( F1 "This is F1" keytitle [EQUATION] )
Here EQUATION has been written to represent the actual select
equation. Note that if a keytitle is given, then the equation is
optional. If the equation is absent then it will always match all
files.
The other term in the full definition is MASKS, it is optional and
is used to modify the result of the equation. The equation can only
be used to test PFH items but the MASKS can be used to test the
download status of each file. If an equation contains any MASKS
then it will only match files which satisfy both the select
equation and which have any of the download status flags named in
MASKS.
10
The MASKS can be one or more of the following:
MASKS Description
maskdone Files completely downloaded
maskauto Files requested for auto
download
maskpriority Files requested for priority
download
masknever Files marked to never download
An example:
(F1 Requests keytitle maskauto maskpriority [EQUATION] )
Again EQUATION is optional when MASKS are used and if it is absent
it will match all files.
11
Constant Substitution. Constant Substitution. Constant Substitution.
In part 1, the term CONSTANT was defined to be a sequence of
characters which formed a number or string, which is a
simplification of the true definition. The formal definition of
CONSTANT is rather complicated and would not show its
possibilities. There are several features which can be used
independently or combined to form a CONSTANT:
1 constant can be specified explicitly as defined already
2 constants can come from configuration variables
3 constants can come from environment variables
4 constants can come from day/time values
5 constants can come from an arithmetic expression containing
other constants
6 constants can come from 'unit conversion' expressions
Wherever the term CONSTANT has been used in formal syntax
definitions, any of the above alternatives are valid. Each
alternative is now explained in more detail.
1. Explicit constants
These are what was described as a constant before and refers to a
sequence of valid characters to form a number or a string.
2. Configuration variable substitution.
The configuration file contains settings for variables such as
'mycall' and 'alias' which are used by PB to identify the user's
callsign. These variables may be referred to in the select
equations where a CONSTANT term is expected. Any occurrence of the
string 'mycall' is replaced with the string used in the
configuration file. The purpose of this is to be able to exchange
equations more easily with other users without having to change
callsigns in many different places. Similarly the variable 'alias'
(or 'myaddr') may be used and will be replaced by the 'alias'
string in the config file.
An example:
(F1 mycall keytitle (destination=mycall) or (destination=alias))
3. Environment variable substitution.
It is possible to use the contents of environment variables as
CONSTANTs in select equations. The syntax can be described formally
as:
VARIABLE 'getenvar'
Here VARIABLE is replaced with the name of an environment variable
to be searched for and 'getenvar' is used as shown. If the variable
can be found its value is used to replace the above expression and
form a CONSTANT. If it cannot be found an empty string is used.
12
An example:
(F1 Local keytitle (destination = COUNTRY getenvar) )
In this example the environment variable 'COUNTRY' (DOS variables
are always in upper case) could contain a callsign prefix with
wildcard, such as 'G*' or 'P*' and the equation would match
callsigns of a certain country. This substitution can be used so
that the user need not alter the equation (possibly in several
places) and setting the environment variable could be done by a
program or batch file.
4. Day and time values.
Most computers keep track of the date and time by counting the
number of seconds since an agreed 'epoch' or beginning. Any given
number specifies both a date and time and is therefore called a
'datime'. The server uses datimes and hence so do the select
equations. The PFH items which are of type 'time' are just a number
representing a datime. PFH datime items are tested by comparing
them with a CONSTANT which could be given as a number in either
decimal or hex form. However, PFH datimes are most likely to be
involved in tests which are relative to 'today', such as finding
files which were sent today or yesterday, for example. If the
constant used the actual number, then it would need to be altered
every day. For this reason there is a constant called 'today' which
is recognised by the equation parser and automatically replaced by
the appropriate number of seconds. In this way, the equation need
not be altered and will always work.
An example:
(F1 "Fresh Today" keytitle (upload_time >= today) )
The constant 'today' is replaced by the datime value of midnight
this morning. Its usefulness in select equations is also greatly
enhanced by the facilities which are explained in the next section.
5. Arithmetic expressions.
This enhancement to the term CONSTANT introduces the ability to use
constants in arithmetic expressions which are evaluated to form a
final value used in the comparison.
The syntax for such an expression is:
CONSTANT { ADDSUB CONSTANT }
Here the term CONSTANT can mean an explicit constant as defined
previously but any of the constant substitution mechanisms may be
used. The term ADDSUB is replaced by one of these symbols:
+ -
The curly brackets indicate that any number of constants may be
added or subtracted. A sequence of addition or subtraction is
13
evaluated from right to left but the evaluation order may be
controlled using round brackets, just as in ordinary arithmetic.
An example:
( F1 bigfiles keytitle (file_size > (32767 - 42 + 3) ))
The expression inside the innermost brackets will be evaluated to a
constant 32722 before being compared with the PFH item 'file_size'.
The above example is not very useful, it simply demonstrates the
idea of adding and subtracting constants.
A more complicated example:
( never (file_size > (MAX_FILE_SIZE getenvar - 1024) ))
The order in which terms are evaluated is important to get the
correct result. The constant substitutions such as 'today' take
priority and some use the term immediately before the substitution
command, such as 'getenvar'. Then the arithmetic operations are
performed from right to left but brackets can control the exact
order.
6. Unit Conversions.
This is a form of constant substitution designed to enhance
expressions involving datimes. The value of 'today' can be modified
by simply subtracting or adding another number. For example, to
test for files uploaded yesterday, the number of seconds in a day
(86400) can be subtracted.
An example:
(F1 "yesterday & today" keytitle (upload_time >= today - 86400) )
This demonstrates how different datimes can be created from the one
substitution 'today'. This technique is enhanced by a number of
'unit conversion' substitutions which convert one number into
another, such as days into seconds. The above example could be
written as:
(F1 "yesterday & today" keytitle (upload_time >= today - 1 day) )
14
Here the term 'day' takes the number before it (1) and converts
this number of days into a number of seconds. The result is then
substituted back into the equation for the test. The conversions
recognised are:
minutes multiplies by 60
hours multiplies by 60*60
days multiplies by
60*60*24
weeks multiplies by
60*60*24*7
These terms are recognised with or without their last 's'.
The conversions may be used in conjunction with other
substitutions, as in this example:
(F1 "3 days" keytitle
(upload_time >= today - OLDEST getenvar days)
and
(upload_time <= today - (OLDEST getenvar + 3) days)
)
Here the bracketing is important to ensure that the number of days
subtracted from 'today' is the sum of 3 and value of the
environment variable OLDEST.
This is perhaps the most complex form of substitution used to
arrive at a single constant and these facilities should cover the
search requirements of most users.
Two more examples:
(F1 "Last week" keytitle (upload_time >= today - 1 week) )
(F1 "This morning" keytitle
(upload_time >= today) and (upload_time < today + 12 hours)
)
15
5 Reading Select Equations. 5 Reading Select Equations. 5 Reading Select Equations.
Changes to PB Configuration File.
The select equations are defined in an ASCII file called the
equation file. The configuration file for PB should contain the
following line to identify the equation file:
select pb.eqn
Here 'pb.eqn' is the filename of the example file supplied with PB.
Any other filename may be specified for PB to read the equations
from. A filename must be specified - there is no default filename.
If the whole line is absent, PB will not read the equation file and
it will use the default set of built-in equations. The equations
which are used for the defaults are listed in the reference
section.
Error messages.
The parser checks the input select equation when the equation file
is read by PB when it starts. If the parser reaches the end of the
equations file without any errors it prints the message:
select: OK
in the list of messages which appear when PB reads its
configuration file. If an error is detected, the parser will print
out which equation it was processing at the time, an error message,
the contents of the line which caused the error and at which line
of the file the line is from. There is a list of error messages and
potential problems in the reference section.
Default Directory View.
One of the equations can be chosen to automatically filter the
directory display when going into directory view mode. This is done
by adding the following line in the configuration file:
defaultsel F4
The word following 'defaultsel' can be any of the equation names
used to define the select equations. If the name is recognised the
following message is printed:
defaultsel: OK
If the default selection fails, then the equation associated with
'F1' is used.
16
6 Reference Section. 6 Reference Section. 6 Reference Section.
This section covers the complete equation syntax definitions, a
list of terms with explanations, a list of error messages with
potential problem causes.
Equation Syntax Summary. Equation Syntax Summary. Equation Syntax Summary.
The syntax for defining select equations is usually best understood
from the examples but here the formal grammar is given for
reference. The grammar may appear to be a mixture of infix and
postfix*. This is because the definition specifies the equation
itself in infix form with infix sub-expressions but it also has
extra features which are implemented in postfix. The postfix
commands are those which operate on the item (or expression)
immediately before them. All the postfix commands currently
implemented are unary operators (they operate on one item).
The syntax definitions here may sometimes appear to contradict
those used in earlier explanations. In such cases the syntax used
before was a simplification and the form given here is correct.
The words in upper case are syntactical terms defined in the
grammar, items in single quotes are literals (they should be used
as shown but without the quotes), square brackets enclose an
optional term, curly brackets denote repetition and vertical bars
denote alternatives.
*The terms 'infix' and 'postfix' refer to two types of grammar. In
an infix grammar an operator is placed between the items it
operates on, such as '( a + b )'. In a postfix grammar the operator
follows the items it operates on, for example '( a b +)'. More
information on grammatical terms and practices can be found in most
programming textbooks. The ideas of postfix programming in
particular are used in programming languages such as FORTH.
SELECT_EQUATION: Defines an equation or directive.
'(' NAME EQUATION ')' |
'(' NAME KEYTITLE [EQUATION] ')' |
'(' NAME MASKS [EQUATION] ')' |
'(' NAME KEYTITLE MASKS [EQUATION] ')' |
'(' [{ DIRECTIVE }] ')'
NAME: Specifies which function key to associate
with the equation.
'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' |
'F8' | 'F9' | 'F10 | 'F11' | 'F12' |
'auto' | 'priority' | 'never'
17
MASKS: Specifies download status flags to search for.
'maskauto' | 'maskpriority' | 'masknever' | 'maskdone'
| CONSTANT 'extramask'
KEYTITLE: Associates a textual title with a function key.
CONSTANT 'keytitle'
EQUATION: An expression for a select equation.
TEST { COMBINATION TEST }
TEST: An infix test of a PFH item.
'(' PFH_ITEM COMPARISON CONSTANT ')'
COMBINATION: An infix operator for combining tests.
'and' | '&' | '&&' |
'or' | '|' | '||'
COMPARISON: An infix operator for making comparisons.
'=' | '==' |
' !=' | '<>' |
'>' | '<' | '>=' | '<='
PFH_ITEM: The names of PFH items which can be tested.
'file_number' | 'file_name' | 'file_ext' | 'file_size' |
'create_time' |
'last_modified_time' | 'seu_flag' | 'file_type' | 'source' |
'ax25_uploader' |
'upload_time' | 'download_count' | 'expire_time' |
'precedence' |
'compression_type' | 'bbs_message_type' | 'bulletin_id_number'
| 'title' |
'keywords' | 'file_description' | 'compression_description' |
'user_file_name'
18
DIRECTIVE: A postfix parser directive command.
(A directive is a command which overrides the normal operation
of the parser. It should only be used when necessary and with
full knowledge of the consequences.)
CONSTANT 'debug' |
CONSTANT 'equationsize' |
CONSTANT 'asctime' |
'keypress'
CONSTANT: An infix expression which is evaluated to a
constant.
VALUE { MODIFIER } { ADDSUB VALUE { MODIFIER } }
VALUE: An actual value or a substitution value.
SYMBOL | METASYMBOL
MODIFIER: A postfix unary operator.
'minute' | 'minutes' |
'hour' | 'hours' |
'day' | 'days' |
'week' | 'weeks' |
'getenvar'
ADDSUB: An infix binary operator.
'+' | '-'
METASYMBOL: A special symbol which is replaced by its
actual value.
'mycall' | 'myaddr' | 'alias' | 'today'
SYMBOL:
A symbol is a sequence of at least one character, up to the maximum
number of characters allowed in a symbol (currently 32) excluding
the following:
( ! " & - + = < > | )
The above characters may be included if the whole symbol is
enclosed in double quotes ". Symbols may represent strings or
numbers. Numbers may be in decimal or in hex if they begin with
19
'0x' (zero x). The string matching wildcard characters are '*' and
'?' and these characters will always be expanded.
This concludes the formal syntax definition of a select equation.
Note that symbol constants (strings) can be added like values
(numbers), but not subtracted.
Parser Directives. Parser Directives. Parser Directives.
Directives are used to alter the normal behaviour of the equation
parser and should only be used with understanding. The following
directive facilities are implemented:
1 Debug.
This is of little value to the user, but shows the equation parser
going through its various passes. The parameter used by debug (the
CONSTANT which precedes it) turns debugging information on if it is
'1' and off if it is '0'. When debugging is on, it stays on until
turned off. An example:
( 1 debug )
...
( 0 debug )
2 Select Equation size.
This affects how much memory is allocated to each select equation.
The input text is of unlimited length, the postfix buffer which
fills up during the first pass of the parser has a fixed length of
1k which cannot be altered. A copy of the postfix buffer is made
for the appropriate equation but of the exact size. The select
equation is formed during the second pass and uses a fixed size
buffer. The size is set to 300 bytes but this can be altered using
the directive. It should only be used for two reasons.
Firstly if there is not enough memory for a normal size buffer a
message will say so. The size of the buffer may then be decreased
until it fits. Note that the buffer size will change after the
point in the equation file where the directive is used so for
maximum effect it should be used before any equations are defined.
The second reason for using the directive may be caused by the
first: when the select buffer is too small for the equation
currently being parsed an error message will state the problem. In
this case it is necessary to in crease the size of the select
buffers. If there is plenty of memory the directive may go at the
beginning of the file, in which case all equations will be given a
bigger select buffer, or it may go immediately before the equation
which caused the error message.
20
The directive takes one parameter (as a CONSTANT immediately before
it). An example:
(50 equationsize)
... short equations in here
(500 equationsize)
... long equation in here
(100 equationsize)
... back to average length
3 Asctime.
This directive is useful when creating select equations which
involve datimes because a CONSTANT which is derived from an
expression involving METASYMBOLS or other CONSTANTs can be verified
as being the anticipated datime by putting 'asctime' after the
expression. The time will be converted into a readable form and
printed. This will only happen during the second pass of the
parser, such as when the definitions are read in from the equation
file. The position of the printed text can vary and will probably
disturb other screen printing. This feature should only be used for
testing select equation definitions. An example:
( today + 10 hours + 30 minutes asctime )
4 Keypress.
This directive is very much like the one above, in that it is used
to test select equation definitions being created. The effect of
'keypress' is that it will pause the program until the user presses
return. This happens when an error is detected in the equation file
but can be deliberately used at any point in the equation file to
trace the parser's progress. An example:
( 0x679795200 asctime keypress )
21
PFH Item Values. PFH Item Values. PFH Item Values.
The PFH items 'file_type' and 'compression_type' have agreed
values and when creating pacsat file headers or select equations to
search them, the following tables should be observed.
1 File Type.
(Please note that the numbering scheme used for file_type has been
revised and this list supersedes any earlier documentation.)
File Description
Type
0 ASCII uncompressed for display or
printing
1 RLI/MBL single message
2 RLI/MBI multiple message
6 MS/PC-DOS .exe
7 MS/PC-DOS .com
8 Keplerian Elements in NASA format
9 Keplerian Elements in AMSAT format
200 UoSAT OBC Task Parameter File.
201 UoSAT 'A' Log.
202 UoSAT 'B' Log.
203 UoSAT 'WOD' data.
204 UoSAT 'ADCS' data.
205 UoSAT 'TDE' data.
206 UoSAT 'SCTE' data.
207 UoSAT 'CCD' data (not images).
208 UoSAT 'ELT' Log.
209 UoSAT 'CP' Log.
210 UoSAT 'BCS' data.
211 UoSAT 'CCD' Images.
255 Escape - none of the above. Extra
description follows.
2 Compression Type.
Code Description
0 Not compressed
1 PKARC
2 PKZIP
255 Escape - none of the above. Extra
description follows.
22
Parser Error Messages. Parser Error Messages. Parser Error Messages.
Here is a list of error messages which are likely to come out of
the parser and some possible causes.
"Stack Underflow"
A symbol was expected on the stack which was empty. The most likely
cause is forgetting to supply a parameter to an operator but can
also be caused by forgetting to bracket an expression.
"Stack Overflow"
A symbol was pushed onto the stack when it was full. The equation
is probably too big.
"Constant '...' type mismatch"
A numeric constant was expected where a string constant was
expected or vice-versa.
"Bad length code on '...'" or "Bad type code on '...'"
These are internal errors which should not occur. If they do,
please advise UoSAT.
"PFH item expected for '...'"
A PFH item was expected but the symbol printed in the message was
not recognised as a PFH item.
"Press return to continue..."
An error causes this message and pauses the program, allowing the
message to be read. Also, the directive 'keypress' can been used
to pause the parser at this point. Press return to continue.
"Equation redefinition error"
The equation name used for the current definition has already been
used for another equation.
"Empty equation definition"
A definition did not comply with its syntax, namely that if an
equation name is given then one or more of the three items
KEYTITLE, MASKS or EQUATION must be defined.
"Memory allocation error (... bytes for pfx buffer)"
Not enough memory is available for a copy of the postfix definition
of the equation. More memory must be freed from somewhere or other
equations must be shortened.
"Memory allocation error (... bytes for eqn buffer)"
Not enough memory is available for the select equation buffer.
More memory must be freed from somewhere, other equations must be
shortened or the select equation size variable must be adjusted
using the directive 'equationsize'.
"Select equation exceeds ... bytes"
The select equation buffer is too small for the current definition.
Either the equation must be shortened or the select buffer size
must be increased using the directive 'equationsize'.
"Unevaluated symbols remaining on stack: ..."
23
An equation definition did not leave the stack empty, indicating
that one of the operators or modifiers used in the definition was
not recognised or that a spurious symbol was placed on the stack.
The symbol shown after the message is usually the cause of the
error.
"Unmatched close bracket."
A close bracket was found which had no matching open bracket. Check
brackets in the definition.
"Unexpected character '...' in symbol '...'"
A sequence of characters in the input did not form a proper symbol.
The message indicates which character was unexpected and the line
on which it was found. If the whole equation is on one line, it
should be split into several lines to allow the error message to be
more useful.
"Can't open file '...'" The equation file named in the
configuration file for PB could not be opened. Check the path.
24
PB Default Select Equations. PB Default Select Equations. PB Default Select Equations.
(F1 everything keytitle (file_type != 2))
(F2 mycall keytitle
(destination=(*+mycall+*))|(destination=(*+alias+*))
)
(F3 Bulletins keytitle (destination=*ALL*))
(F4 Logs keytitle (file_type > 200)&(file_type != 255))
(F5 Done keytitle maskdone)
(F6 Requested keytitle maskauto maskpriority)
(F7 Keps keytitle (file_type=8)|(file_type=9))
(F8 Images keytitle (file_type=211)|(keywords=*IMAGE*))
(F9 NEWS keytitle (keywords=*NEWS*))
(F10 PB/PG keytitle (keywords=*PB*)|(keywords=*PG*))
(F11 BBS keytitle (file_type=1)|(file_type=2))
(F12 Urgent keytitle (precedence>0))
(auto (destination=*ALL*)&(file_size<10000))
(priority (destination=(*+mycall+*))|(destination=(*+alias+*)))
; 'never' not defined. Nothing is blocked.
25
Example Select Equations. Example Select Equations. Example Select Equations.
The examples listed here are mostly from elsewhere in the
documentation.
( F1 (destination = foobar) )
( F2 (destination = ALL) and (title = image) )
( F3
(
(destination = ALL)
or
(destination = mycall)
)
and (file_type != 1)
and (file_type != 2)
)
(F1 ( destination = *foobar* ) )
(F1 (destination = *foobar*) and (keywords = *news*) )
(F1 mycall keytitle (destination = mycall) or (destination = alias))
(F1 Local keytitle (destination = COUNTRY getenvar) )
(F1 "Fresh Today" keytitle (upload_time >= today) )
(F1 bigfiles keytitle (file_size > (32767 - 42 + 3) ) )
( never (file_size > (MAX_FILE_SIZE getenvar - 1024) ) )
(F1 "yesterday & today" keytitle (upload_time >= today - 86400) )
(F1 "yesterday & today" keytitle (upload_time >= today - 1 day) )
(F1 "3 days" keytitle
(upload_time >= today - OLDEST getenvar days)
and
(upload_time <= today - (OLDEST getenvar + 3) days)
)
(F1 "Last week" keytitle (upload_time >= today - 1 week) )
(F1 "This morning" keytitle
(upload_time >= today) and (upload_time < today + 12 hours)
)
(F1 User keytitle (destination = (*+USERNAME getenvar+*)))
26
Address for problems and comments. Address for problems and comments. Address for problems and comments.
Marcel Losekoot,
G1NBR @ UOSAT5 or G1NBR @ GB3UP.gbr.eu or
UoSAT Unit, University of Surrey
Guildford, SURREY GU2 5XH
UK
27
