____________________ 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