Beijing Paradise BBS Backup

home *** CD-ROM | disk | FTP | other *** search

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / U3250.ZIP / U3.DOC < prev next >

Wrap

Text File | 1996-05-28 | 52.8 KB | 1,195 lines

User Updater--Universal Version 2.50 Copyright 1996 by Thomas Almy TABLE OF CONTENTS INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 WARRANTEE . . . . . . . . . . . . . . . . . . . . . . . . . . 2 DISTRIBUTION . . . . . . . . . . . . . . . . . . . . . . . . . 3 USER UPDATER -- UNIVERSAL IS SHAREWARE . . . . . . . . . . . . 3 TRADEMARKS . . . . . . . . . . . . . . . . . . . . . . . . . . 3 RUNNING USER UPDATER -- UNIVERSAL . . . . . . . . . . . . . . . . . 4 USERBASE MODE . . . . . . . . . . . . . . . . . . . . . . . . 4 DOOR MODE . . . . . . . . . . . . . . . . . . . . . . . . . . 5 USER UPDATER COMMAND FILE . . . . . . . . . . . . . . . . . . . . . 6 OPPERANDS: FIELDS AND NUMBERS . . . . . . . . . . . . . . . . 7 EXPRESSIONS . . . . . . . . . . . . . . . . . . . . . . . . . 9 LET STATEMENT . . . . . . . . . . . . . . . . . . . . . . . . 10 PRINT STATEMENT . . . . . . . . . . . . . . . . . . . . . . . 10 SET STATEMENT . . . . . . . . . . . . . . . . . . . . . . . . 11 RUN STATEMENT . . . . . . . . . . . . . . . . . . . . . . . . 12 RETURN STATEMENT . . . . . . . . . . . . . . . . . . . . . . . 13 THE OPTIONAL "FINALLY" COMMAND . . . . . . . . . . . . . . . . 13 ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . . . . . . 14 EXAMPLES OF USE . . . . . . . . . . . . . . . . . . . . . . . . . . 16 RESET A FLAG . . . . . . . . . . . . . . . . . . . . . . . . . 16 DELETING NON-VERIFIED CALLERS . . . . . . . . . . . . . . . . 16 RAISING LEVELS AND POSTING MESSAGES . . . . . . . . . . . . . 17 LOW CREDITS WARNING . . . . . . . . . . . . . . . . . . . . . 17 LIST AND TALLY TERMINAL EMULATIONS . . . . . . . . . . . . . . 17 NOTIFY XMODEM USERS . . . . . . . . . . . . . . . . . . . . . 18 POSTS PER MONTH RATIO LIST . . . . . . . . . . . . . . . . . . 18 POST PER DOWNLOAD RATIO DOOR . . . . . . . . . . . . . . . . . 18 TIME PURCHASE DOOR . . . . . . . . . . . . . . . . . . . . . . 19 GENDER BASED DOOR . . . . . . . . . . . . . . . . . . . . . . 19 NIGHTLY MAINTENANCE AT BITTER BUTTER BETTER BBS . . . . . . . 20 TECHNICAL NOTES . . . . . . . . . . . . . . . . . . . . . . . . . . 21 OTHER UTILITIES BY THE AUTHOR OF U3 . . . . . . . . . . . . . . . . 22 User Updater -- Universal 2 INTRODUCTION The User Updater--Universal (or U3) program performs userbase maintenance in RemoteAccess 2.5x or 2.0x BBSes. Unlike other userbase maintenance programs, U3 provides virtually unlimited test conditions and actions. Conditions can be based on any combinations of date, flag, and numeric field values. When the condition is true, any number of fields can be modified, information can be printed, and/or external programs (such as robotic mailers) can be executed, and U3's own return error level code can be set. Almost every field in the userbase can be examined. Ten "global fields" can be used to store values, allowing the program to do such things as count the number of callers meeting a specific criteria or to calculate the average caller age. In addition, U3 can be used in a type 7 or 15 menu item (door) to perform the same set of operations on the current logged in user. This is called "door mode." U3 can be readily combined with other programs in batch files. The use of U3 is virtually limited only by your imagination! Sysops who have had some programming experience in a language like BASIC or Pascal will find U3 easy to use. Those without experience should study closely the examples at the end of the instructions. I wrote U3 because I found myself using several custom programs to do userbase maintenance, and it made sense to me to have a program which could do all modifications. I hope you ll find it as useful as I have and will register! **** WARRANTEE User Updater Universal (U3) is provided "AS IS" with no warranties or guarantees of any kind. Since U3 is distributed as fully functional shareware, it is the responsibility of the potential purchaser to determine that U3 is suitable for use before purchasing. The author does not make any claims, promises, or guarantees as to the usability of U3 for any particular purpose and cannot and does not accept any responsibility for system damage, loss of profit, or any other special, incidental or consequential damages resulting from this product. The author has taken care in writing this program, however U3 by its very nature is capable of destroying or modifying data. The user should always back up the BBS userbase files prior to testing U3 or modifying any U3 command files. User Updater -- Universal 3 **** DISTRIBUTION U3 may be distributed by anyone as long as the files in the original archive are intact. U3 may not be distributed as part of a commercial product or by any means that implies that it is a registered (paid for) copy without permission of the author. **** USER UPDATER -- UNIVERSAL IS SHAREWARE You may use User Updater to evaluate it for your needs. If you decide it is useful to you, then you must register, otherwise you must discontinue its use. Registration is an easily affordable $10. See the file REGISTER.DOC for instructions. Registrations may not be transferred. They are are specific to a single BBS name. Once registered the modest nag screen, beeps and delays will vanish. However the unregistered program is fully functional. **** TRADEMARKS All product names mentioned in this document are trademarks of their respective manufacturers. User Updater -- Universal 4 RUNNING USER UPDATER -- UNIVERSAL **** USERBASE MODE To run U3 you need to create a command file telling U3 what it needs to do. The syntax for this file is described in the next section. For accessing the user base, you must have the environment variable RA set to the directory containing the CONFIG.RA file, or else you must run U3 from the directory containing CONFIG.RA. Then run U3 from the command line: u3 -d -f -s commandFile RegistrationNumber where: -d -f and -s are optional command switches. commandFile is the name (and path if not in the current directory) of the U3 command file. RegistrationNumber is optional and is the number provided when you register U3. Until registered, U3 has an annoying delay which can be bypassed only by hitting a key. This allows U3 to be fully tested but not be easily used in an automated environment. The registration number can also be placed as the single line in a text file called U3.KEY, and placed in the current directory. This eliminates the need to place the registration number on the command line. The "-s" option causes U3 to skip all records for which the Deleted flag is set. Otherwise deleted records are processed. If "-d" is used as the first argument, U3 runs in debug mode and will not modify the userbase or run external programs. Instead it displays what it would have done if the -d option was not given. If "-f" is used, the userbase will not be modified, but all other actions occur. If no command line switches are used, U3 will not run if a copy of RemoteAccess is running. It is important that U3 only be used when RemoteAccess is not running, such as during night-time maintenance. If you are not interested in modifying the userbase, U3 can be run when RemoteAccess is running by using the -f option. When debug mode (the -d option) is used, U3 will always run so that command files can be tested without stopping RemoteAccess. You should always test U3 command files by using debug mode. Be certain that U3 will do exactly what you want before removing the -d option. You should also save a copy of USERS.BBS before testing U3. U3 is a very powerful program, and is very capable of totally mangling your user base given the wrong commands! The first thing U3 will do is open the CONFIG.RA and USERS.BBS files. It will give an error message and quit if it cannot find either of User Updater -- Universal 5 these files. Then U3 will open and parse the command file. If any error is encountered, a message will be printed and execution will stop. Only one error will be reported in any run. Errors during parsing describe the error and the location in the command file where the error was discovered. U3's print statements write to the display. The output can be directed to a file using DOS s output redirection. For example: u3 u3cmd.txt c:\ra 12345 >u3out.txt will write the output to U3OUT.TXT. You can then use a robotic mailer to send the output to you as mail, or can use the output file in an online bulletin. U3 can be invoked as many times as is desired, using different command files each time. This gives maximum flexibility. **** DOOR MODE U3 can also be used in Door Mode. In this case it is either invoked from a type 7 menu item, or from a batch file run from a type 7 or 15 menu item. To run U3 in Door Mode, and access the record of the current user online, invoke U3: u3 -u -d -f commandFile The -d and -f are optional command flags, as described previously. U3 must be run in the directory containing the EXITINFO.BBS file. The registration number is not necessary. There is no annoying nag screens in Door Mode when not registered. The user database is not touched, so other lines of RemoteAccess can be running. Changes made to the exitinfo record are incorporated into the user record when RemoteAccess is re-entered. The EXITINFO.BBS file has more information than the userbase record. These additional fields can be accessed and, with care, altered. Operation in Door Mode is otherwise identical with Userbase mode. See the end of this document for complete usage examples. User Updater -- Universal 6 USER UPDATER COMMAND FILE The command file is the heart of U3. In it you describe the actions you want U3 to perform. The file is a standard ASCII text file you can create with DOS s EDIT or EDLIN programs or any other editor which will create text files (TED, QEDIT, Brief, Epsilon...). To make things easier, U3 ignores line breaks, has no limits on line sizes, and ignores case. You can put comments in the command file: put a \ character in a line and everything to the right until the end of the line will be ignored. The command file consists of one or more IF THEN commands, with the format: IF expression THEN statements where expression is a logical expression (described later) and statements are one or more statements which are to be executed if the expression has a non-zero ("true") value. There are five types of statements. LET statements alter numeric and date fields in the record, SET statements alter text fields in the record, PRINT statements print data to the display or file, RUN statements execute external programs, and RETURN statements set U3's return code. Each user record is examined in turn, for each IF expression that is true, the THEN statements are executed for that user record. Each IF THEN command is independent -- whether or not an IF expression is true, the following IF THEN command is executed. Commands and the statements within are all executed sequentially. If a field is set by a LET statement, the new field value will be used if later referenced in the command file. Consider the following command file: IF level=10 \ A new caller THEN LET level = 20 LET D1 = 1 PRINT "New user ", name RETURN 20 IF level=20 & today-lastdate > 30 & !nokill THEN \ delete this caller LET deleted = 1 PRINT "User ", name, " deleted" Each user record will be examined. If the user security level is 10, then the level will be changed to 20, the D1 flag set, and a User Updater -- Universal 7 notification printed. The return code will be 20 if there are any new callers. If the security level is 20 and the user hasn't called within the past 30 days (difference between the today's date and the last call date greater than 30), and the nokill flag is not set then mark the user as deleted and print the message. Since the commands are executed sequentially, any user with security level of 10 who hasn t called in thirty days will end up being deleted. Why? Because their level is raised to 20 by the first IF THEN command, so the level is 20 in the IF expression of the second IF THEN command. If this were a problem, the order of the two IF THEN commands could be reversed. However in this particular example it is unlikely that a new user would not have called in the last thirty days. This example was formatted and capitalized to aid in reading, however remember that the U3 program ignores line breaks and capitalization. **** OPPERANDS: FIELDS AND NUMBERS Numeric expressions consists of operators (such as add and subtract) and opperands. Opperands can either be the names of fields in the userbase (or EXITINFO.BBS in Door mode), or numbers. A number is either an integer (examples: 0 123 6120) or a floating point number (examples: 1.3 2.4 222.111). In addition, the name "true" can be used in place of the value 1, and the name "false" can be used in place of the value 0. These are particularly convenient when dealing with flags. When a numeric field name is used in an expression, the value contained in the user record being examined is used in the calculation at that spot. Numeric fields are of different sizes and types, however all field contents are converted to floating point numbers for calculations. Some fields are described as "calculated value." These are not real fields in the record, but are values calculated from fields or outside information (such as today s date). Valid numeric fields are (those marked with "+" are for Door Mode only): ** dates: birthdate -- date of birth firstdate -- date of first call lastdate -- date of last call subdate -- subscription date today -- today s date (calculated value, not in userbase!) ** flags: value 1 if true, 0 if false hasalias -- alias and name fields are the same (calculated value) deleted -- deleted flag User Updater -- Universal 8 cls -- clear screen flag more -- more prompt flag ansi -- ANSI mode flag nokill -- no-kill flag xfer -- xfer priority flag fsedit -- full screen editor flag quiet -- quiet mode flag hotkeys -- hotkeys flag avt0 -- avt/0 emulation flag fsmsg -- full screen message viewer flag hidden -- hidden from userlist flag page -- page priority flag noecho -- no echomail in mailbox scan flag mbcheck -- selected areas mail check flag (RA 2.5x only) guest -- guest account flag postbill -- post bill enabled flag a1, a2, a3, a4, a5, a6, a7, a8, b1, b2, b3, b4, b5, b6, b7, b8, c1, c2, c3, c4, c5, c6, c7, c8, d1, d2, d3, d4, d5, d6, d7, d8 -- user flags ** Integers (these have values in range roughly +/- 2,000,000,000) credit -- credits pending -- pending charges numcalls -- number of calls uploads -- number of uploads downloads -- number of downloads uploadk -- kilobytes of uploads downloadk -- kilobytes of downloads todayk -- kilobytes of downloads today ** Integers (these have signed values -32768 to 32767) elapsed -- elapsed time today (negative times are possible when time banks are used) + deductedtime -- (don't know what this field does) ** Integers (these have non-negative values 0 to 65535) age -- caller's age (calculated value, if birthdate field is empty, the age is returned as 0) record -- record number (calculated value) msgpost -- number of messages posted level -- security level length -- screen length group -- group member (0 if not used) + baud -- login speed, 0 for local + timelimit -- number of remaining minutes for this call + pages -- number of paging attempts for this call + dlimit -- download limit for this call ** Integers (these have non-negative values 0 to 255) pwdchange -- calls since last password change. This value rolls over from 255 to 0 so is not accurate unless password changing is enforced. User Updater -- Universal 9 dobcheck -- calls since last date of birth check. This value rolls over from 255 to 0 so is not accurate unless checking is enforced. language -- language number selected (0 if not used) dateformat -- selected date format: 1- DD-MM-YY, 2- MM-DD-YY, 3- YY- MM-DD, 4- DD-Mmm-YY. sex -- sex: 0-unknown, 1-male, 2-female protocol -- default download protocol (ASCII character value, 0 means not specified) + netmail -- 0-no outgoing netmail, 1-outgoing netmail + echomail -- 0-no outgoing echomail, 1-outgoing echomail + wantchat -- 0-doesn't want to chat, 1-wants to chat + errorfree -- 0-no REQ or ARQ, 1- error correcting connect + sysopnext -- 0-not set, 1-sysop on next (ALT-N from console) + emsi -- 0-normal session, 1-IEMSI session + doesavt -- 0-doesn't do AVATAR, 1-does AVATAR + ripmode -- 0-doesn't do RIP, 1-does RIP + ripversion -- RIP Version (RA 2.5x only) Note that all dates are treated as integer values and are the number of days since February 28, 1900. Dates of January and February 1900 are not allowed and are treated as March 1, 1900. If a date field is blank, the value 0 is supplied. RemoteAccess 2.x has a date handling problem in that it encodes the year as the final two digits. To handle dates after December 31, 1999, after that date U3 will assume that years greater than the current year are 19xx while other years are in the current century (20xx). Since no dates after the current date are valid, this technique should keep U3 (and maybe RemoteAccess as well) functioning far into the future. In addition there are 10 global integer fields, which can hold values in range +/- 2,000,000,000 named u1, u2, ..., u10. These fields are not associated with a particular user record, and can be used to accumulate totals, count users, or as general temporary storage locations. The global fields initially have the value 0. **** EXPRESSIONS Expressions are traditional mathematical expressions. Standard order of precedence rules are followed. I.E. multiplication is performed before addition in the expression 2+3*5. Otherwise execution proceeds from left to right. Operators in decreasing precedence order are: - Unary minus (negate) + - Addition and Subtraction * / Multiplication, division = != < <= > >= Equal, not equal, less, less or equal, greater, greater or equal. Return a "true" value one or "false" value zero. ! Not (logical complement-- nonzero or true values become zero or false, and visa versa) & And (value true if both arguments true or non-zero) | Or (value true if either argument true or non-zero) User Updater -- Universal 10 In the expression 2+3*5, the multiplication is done before the addition because multiplication has higher precedence. Parentheses can be used to change the order of evaluation. For instance (2+3)*5 will do the addition first. All calculations are done in floating point with 15 digits precision. Note that the expression age>=18 will be true if the age of the caller is greater than or equal to 18. However 30>=age>=18 will not return true for ages between 18 and 30. This must be done with two comparisons and the "and" operator: 30>=age&age>=18. The order of precedence has the comparisons done before the and operator, so no parenthesis are necessary. Most expressions will be simple comparisons, or multiple comparisons connected with the and operator. In this case, all the comparisons must be true for the expression to be true. For example the expression age>16 & !nokill & level=30 will be true only if all of the following are true: age greater than 16, nokill flag *not* true, and security level equal to 30. **** LET STATEMENT The LET statement is used to assign new values to most numeric and date fields. The syntax is: LET field = expression where field is a valid assignment field and expression is any valid expression. If the field is a flag, then any nonzero expression value is considered to be TRUE, while a zero value is considered to be FALSE. For integer fields, the expression value, calculated in floating point, is converted to the next lower integer value. For instance, 5/2 would be stored as 2. All fields listed above, except for "record", "today", "hasalias", and "age" are valid for assignments, however most of them probably should not be used for assignments. Use this statement with caution! When assigning to date fields, the value assigned should be a date (e.g. "LET subdate=today") and never a date in the future (because of the centure checking). Be careful not to assign invalid values as no checking is performed. This includes storing a negative value in a field which only holds non-negative values. **** PRINT STATEMENT The print statement prints to the display or to a file if output is redirected, as described earlier. The syntax is: PRINT printExpressions where printExpressions are expressions, quoted text, or text field names. All printExpressions must be separated by commas. User Updater -- Universal 11 Each print statement prints a single line of data. Numeric expressions print as integers. Literal text can be printed by enclosing it in quotes (e.g. "a string"). To print a quote character, use two adjacent quote characters (e.g. " "" " will print as a space- quote-space sequence). Tabs and control characters are valid in literal text, making it possible to include ANSI color control sequences for fancy reports. To allow the use of editors which don't allow inserting control codes, they can be represented by the tilde "~" character followed by @, A through Z, [, \, ], ^, or _, to generate the appropriate character. For this reason, the tilde character itself must be represented by two adjacent tilde characters "~~". Text fields in the userbase can be printed as follows (those marked with "+" are available in Door Mode only): name -- user name location -- location organization -- organization (field not used in RemoteAccess) address1 -- address1 address2 -- address2 address3 -- address3 handle -- handle comment -- comment dataphone -- data phone voicephone -- voice phone forwardto -- name to forward mail to + emsicrt -- IEMSI CRT field + emsiproto -- IEMSI PROTOCOL field + emsiable -- IEMSI CAPABILITIES field + emsireq -- IEMSI REQUEST field + emsisoft -- IEMSI SOFTWARE field + pagereason -- paging reason There is some control possible over formatting. To print a numeric value as a date, follow the expression with ":d". If the date value is 0 (meaning "not set"), the date printed will be " - - ". To specify a fixed number of columns for a field, follow the expression with ":n" where n is an integer specifying the number of columns. Text fields will be left justified and truncated if necessary, while numeric fields will be right justified and are never truncated if the specified field length is too short. For instance: PRINT "Name birthdate, and age:",name:20," ",birthdate:d, age:3 Will print the text "Name and age:" (without the quotes), the first 20 characters in the name, padded if necessary on the right with spaces, two spaces, the birthdate of the caller, and the age in years of the caller right justified in a 3 column field. User Updater -- Universal 12 The length of the line printed is limited to about 250 characters, including any embedded control characters. You can print a blank line with the statement: PRINT "" **** SET STATEMENT The SET statement is used to assign values to text fields. The syntax of the set statement is: SET textField = printExpressions where textField is a text field name listed under the PRINT statement, and printExpressions are expressions, quoted text, and text field names separated by commas, as described under the PRINT statement. For example, the handle can be set to the callers real name with the statement: SET handle = name If the printExpressions would create text which would not fit in the field, the text is truncated (from the right) to fit. **** RUN STATEMENT The RUN statement works just like the print statement, except the generated line of text is used as a command line. The line to be executed may not be more than 124 characters long. For instance, a message can be sent to the user using mbutil (part of GEcho mail tosser) with: RUN "mbutil msg.txt #1 -To """, name, """ -Subject Welcome -Pvt" For the user Joe Blow, this would run the command: mbutil msg.txt #1 -To "Joe Blow" -Subject Welcome -Pvt The RUN command uses Ralf Brown's SPAWNO library so that U3 is swapped out of low memory to run the program. U3 will swap out to XMS if available, else EMS. If neither is available, U3 will swap to disk. U3 uses the command interpreter (usually COMMAND.COM) in the RUN command, so the user path is searched and batch programs (BAT extensions) are allowed. Users of JP Software's 4DOS can run BTM files and aliases as well. However if the program to run is an EXE or COM file, and the full path and filename is specified, then the program will be run directly without starting a command interpreter. This is faster, and conserves memory. For instance: User Updater -- Universal 13 RUN "foo bar" will run program foo, which can be an EXE, COM, or BAT file located anywhere in the search path. A copy of the command interpreter will be started to run the program. The statement: RUN "\xyz\foo bar" will run program foo, which can be an EXE, COM or BAT file, but must be in directory \xyz\. A copy of the command interpreter will be started to run the program. On the other hand: RUN "\xyz\foo.exe bar" will run program foo.exe in directory \xyz\ without starting a command interpreter. **** RETURN STATEMENT The syntax of the RETURN statement is: RETURN expression where expression is any valid expression. The return statement sets the return error level of U3 to the value of thee expression. The last RETURN statement executed determines the value used. The return level cannot be less than 0 or greater than 255. If no RETURN statement is executed, then the level 0 is returned. If an error occurs while running U3, the level 1 is returned. The error level can be examined in a DOS batch file by using the IF ERRORLEVEL statements. If you use 4DOS, you can examine, print, or even evaluate expressions based on the level. **** THE OPTIONAL "FINALLY" COMMAND At the end of the IF THEN commands which are executed for every user record there can be a single FINALLY followed by more IF commands. These final IF THEN commands are executed after all user records are processed. No record fields can be accessed, only the global fields U1 through U10. This feature is typically used to print accumulated results. Consider this command file that calculates the average age of callers in security level 20: IF AGE > 0 & LEVEL = 20 \ if age is zero, birthdate is unknown! THEN LET U1 = U1 + AGE \ sum of ages in U1 LET U2 = U2 + 1 \ number of users in U2 FINALLY \ calculate this at the end IF U2 > 0 \ must be at least one to average THEN PRINT "Average age is ", U1/U2 User Updater -- Universal 14 The sum of the ages is stored in global field U1 and the number of users in global field U2. After all records are examined, the average age, U1/U2, is printed. An enhanced version of this command file which generates a ANSI color bulletin is shown later in the EXAMPLES OF USE section. User Updater -- Universal 15 ERROR MESSAGES U3 can generate the following error messages. The first error will cause the program to terminate, returning an error level 1. "could not access EXITINFO.BBS" -- In Door Mode, the EXITINFO.BBS file must be in the current directory. "could not access CONFIG.RA" -- The RA environment variable must be set to the directory containing CONFIG.RA, or CONFIG.RA must be in the current directory. "could not read CONFIG.RA" -- This error can occur if another program is accessing the configuration file and has it locked. "could not access USERS.BBS" -- This error can occur if another program is accessing the userbase, such as a running copy of RemoteAccess. You might want to try the -f command option. "could not open command file" -- The command file could not be found. "insufficient memory for code array" -- Not enough memory to run U3. U3 needs about 150k bytes to run. "defective EXITINFO.BBS" -- in Door Mode, there was something funny about the EXITINFO.BBS file. "strange symbol reference" -- program bug, please send command file to U3 author! "WARNING: Attempted record write denied" -- when using the -f command option, a LET or SET statement was encountered that attempted to modify the record. This warning message does not abort execution, but simply leaves the record unaltered. The following are FATAL COMPILATION ERRORS. These are generated because of errors in the command file. The error message will indicate the line number and column where the error was discovered. "text string not terminated before end of line" -- text strings cannot wrap around line boundaries. The command file is probably missing a closing quote. "unrecognized control character" -- only carriage return, line feed, and tab control (non printing) characters are allowed in commands. "text string too long" -- text strings cannot be longer than 127 characters. "invalid number format" -- numbers must only consist of digits 0 through 9, and an optional single decimal point. User Updater -- Universal 16 "unidentified symbol name" -- the indicated keyword or field name is either mis-spelled or not allowed (non-global field names after the FINALLY keyword, or Door Mode fields when not in Door Mode). "U3 command file too big" -- the command file, when encoded, must be less than 10,000 bytes. This command file is too big. More likely than not the problem is too much text. If this is a problem, notify the author, who can increase this size in future versions. "right parenthesis expected" -- an expression is missing a closing right parenthesis. "expression cannot involve text field" -- only numeric values can be used in expressions. "field name expected" -- something other than a valid field name was found where a field name was expected. "expression too complex" -- you need to simplify this expression. Expressions can only have 31 simultaneous subexpression results during a calculation. This is actually a very large number. Try rearranging the expression so execution can proceed left to right. "text field name required" -- in SET statement. You probably want the LET statement. ""=" expected" -- in SET or LET statement, you need an "=". "integer constant expected" -- field sizes must be integer constants. "constant too large" -- field sizes must not be bigger than 254. "assignable field name required" -- in LET statement, field name give was not assignable (such as "age" or a text field). "THEN expected" -- the keyword THEN must be used after the IF expression but before the LET, SET, RUN, PRINT, or RETURN statements. "unexpected token" -- catch-all error. U3 expected a possible end of command file, but there was more in the file. Common causes are a missing commas or keywords (LET, SET, RUN, PRINT, RETURN). User Updater -- Universal 17 EXAMPLES OF USE This section describes a number of U3 command files, showing a variety of functions that can be performed. **** RESET A FLAG The first example uses U3 to reset a flag. It represents a "quicky" command file that might be written and used once to handle a one-time maintenance task: if true then let a1=false That's it. Since "true" is always true, flag a1 gets reset for all users. If you want to know which users you have reset the flags for, you can use a slightly longer "quicky" command file: if a1 then let a1 = false print Name This will reset the flag for any user whose flag is set, and will print out their names. **** DELETING NON-VERIFIED CALLERS This second example could be used for nightly maintenance: \ Delete non-verified callers who haven't called in 5 days if level = 10 & today-lastdate > 5 then let deleted = true print name, "is deleted, not verified" It will delete any user with security level 10 who hasn't called in 5 days. You will need to use the RAUSER program to actually purge the "deleted" user record. Of course, RAUSER will delete users based on number of days since last call, but it won't do it for specific security levels (just those less than a specified value). Also, this example will delete users who have the NOKILL flag set! If you didn't want to delete users who have NOKILL set, and also didn't want to delete already deleted users, the first line could be changed to: if !deleted & !nokill & level = 10 & today - lastdate > 5 Of course, you can also use the -s command line flag to eliminate the need to explicitly check that the record has not been deleted. User Updater -- Universal 18 **** UNDELETING USERS Ops! Deleted a bunch of users by accident? This short command file will undelete any deleted records, and tell you to whom they belong. Don t use the -s command line flag with this -- it won t work! if deleted then let deleted = false print name, " restored!" **** RAISING LEVELS AND POSTING MESSAGES This third example raises a user's level and sends a message if a flag has been set. This example and further examples assume the use of MBUTIL as the robotic mailer. MBUTIL is part of the GEcho mail tosser program. However robotic mailers could be used. \ raise level from 20 to 21 if c8 flag set, and send message \ to user about the change if level=20 & c8 then let level=21 print name, "has been verified" run "mbutil Post verified.txt #1 -To """, name, """ -subject Welcome -pvt" **** LOW CREDITS WARNING This fourth example sends a warning message when credits drop below a certain amount (100 in this case). A flag is used to determine if the message has been sent. The flag is reset when credits are restored. \ For registered users (level 30), send a message if \ credits have dropped below 100 if level = 30 & !c1 & credit - pending < 100 then let c1 = true run "mbutil Post locredit.txt #1 -To """, name, """ -subject Notification -pvt" \ Reset flag c1 when credits are again above 100 if level = 30 & c1 & credit-pending > 100 then let c1 = false User Updater -- Universal 19 **** LIST AND TALLY TERMINAL EMULATIONS This command file will list which terminal emulation a caller uses. The choices are AVATAR, ANSI, or ASCII. The user database is not modified. It will print the total number of users with each setting. if avt0 \ avatar flag set then print name, " uses AVATAR" let u1 = u1 + 1 \ count AVATAR users if ansi & !avt0 \ ansi flag set, but avatar not set then print name, " uses ANSI" let u2 = u2 + 1 \ count ANSI users if !(ansi | avt0) \ neither ansi or avatar flag set then print name, " uses ASCII" let u3 = u3 + 1 \ count ASCII users finally \ print totals at end if u1 > 0 then print u1, " AVATAR users" if u2 > 0 then print u2, " ANSI users" if u3 > 0 then print u3, " ASCII users" **** NOTIFY XMODEM USERS Would you rather see your callers using ZMODEM protocol rather than XMODEM protocol? This command file will send messages to users who use XMODEM! \ Send a message to all people using Xmodem protocol if protocol = 88 then run "mbutil Post xmodem.txt #1 -To """, name, """ -subject ""XMODEM Usage"" -pvt" The value 88 is the character "X", so when the default (last used) protocol was XMODEM, the robot mailer is called to send a friendly suggestion. **** POSTS PER MONTH RATIO LIST Lots of programs will show you the posts per call ratio. Would you rather know the posts per month ratio? This command file will do it, and won't list callers who have posted fewer than five messages (a single post of a first time caller is 30 posts per month!) if msgpost > 5 then print name:20 , msgpost/((today-firstdate)/30) : 5 Do you want to see the list sorted? That's easy! Use the sort program that comes with DOS: u3 postmnth.dat | sort /+21 /r User Updater -- Universal 20 If you have a DOS version of the Unix (TM Bell Labs) program "tail" you can extract the top N callers, and make a custom Top N Caller list. **** POST PER DOWNLOAD RATIO DOOR This command file is intended for use in Door Mode, to be executed automatically at the start of a BBS call. It checks the messages posted vs number of files downloaded and set flag A4 if there are more messages posted than files downloaded. This flag can then be used to control access to file areas. U3 can be run as a type 7 menu item. if msgpost >= downloads \ set flag if good user then let a4 = true if msgpost < downloads \ reset flag if bad user then let a4 = false the same two commands could be made part of a nightly maintenance run of U3 if it was desirable to alter the flag once per day rather than on each call. **** TIME PURCHASE DOOR This command file is for use in Door Mode, only. It will charge the caller 10 credits and in return add 10 minutes of access time during the current day. if credit >= 10 \ must be some credits to spend then let credit = credit - 10 let timelimit = timelimit + 10 let elapsed = elapsed - 10 If some people are allowed credit balances (postbill flag set), then this command file should be modified to allow those people to borrow: if credit >= 10 | postbill then let credit = credit - 10 let timelimit = timelimit + 10 let elapsed = elapsed - 10 **** GENDER BASED DOOR Assume a game that has both male and female modes of operation. RemoteAccess provides no way of running alternate programs depending on gender. The problem is solved with this command file: if sex = 2 then return 2 \ caller is female User Updater -- Universal 21 The game is run from this type 7 menu item batch file: u3 -u gender.dat if errorlevel 2 goto female game -Male goto end :female game -Female :end **** A SIMPLE BULLETIN This command file will generate a simple ANSI bulletin showing all callers and their ages. It illustrates how to embed ANSI control codes and how to make a bulletin head and tail (within U3). if u1 = 0 \ Initially u1 is 0, so we will print the head then print " ~[[1mCALLERS AND THEIR AGES~[[0m" print "Name Age" if !deleted \ Only consider non-deleted records then \ (we can also use -s on the command line) let u1 = u1 + 1 let u2 = u2 + age print "~[[32;1m", name:25, "~[[33m", age, "~[[0m" finally \ when finished, print average age if u1 > 0 then print "" \ empty string prints blank line print "" print "The average age is ~[[1m", u2/u1, "~[[0m" **** NIGHTLY MAINTENANCE AT BITTER BUTTER BETTER BBS Finally, here is the command file I use for nightly maintenance: if !nokill & ((level < 20 & today-lastdate > 3) | (level < 30 & today-lastdate > 90) | (level < 35 & today-lastdate > 120)) then let deleted = true print "User ", name, ", level ", level, ", deleted -- no usage" if !deleted & !nokill & today-lastdate > 30 & numcalls = 1 & downloads = 0 & msgpost = 0 then let deleted = true print "User ", name, " no posts/secondcall/downloads in 30 days" if !deleted & level > 10 & b1=false then let b1 = true User Updater -- Universal 22 print "User ", name, " Scrabble upgraded" User Updater -- Universal 23 TECHNICAL NOTES I'm always curious about such things, so I'm providing a short technical description of the insides of U3. U3 is written in C, and compiled with the Borland C++ V4.02 compiler. The executable program was compacted using Fabrice Bellard's LZEXE. As mentioned before, U3 uses the Ralf Brown's SPAWNO package to swap out of memory in the RUN command. For several years I have done userbase management with C programs that read the userbase, modify the fields as needed, and then write out the changes. I've also written several programs to obtain statistics of users. All of these programs are identical in structure. Of course, each time I wanted to make a change, I had to modify the source and recompile. I thought, "what if the portion of these programs that differed were separated out and interpreted? Then the programs would be simpler and easier to maintain." So I proceeded to write U3. If U3 interpreted the command file with each record, performance would be hurt for large user bases. Indeed, I wanted U3 to run quickly! So I decided to compile the command file into a "byte code" program that would executed by a runtime byte code interpreter. This had the added advantage that all syntax errors would be discovered before processing any of the records, rather than taking the risk that an error would not be discovered until the faulty statement was executed. U3 first opens all the files to make certain they are available. Then it compiles the command file. The compiler is a traditional "recursive descent" design, which is more compact and easier to debug than the more recent table driven techniques. The compiler was designed to be robust, and to abort on the first error. While programmers generally prefer to see all error messages at once, most compilers will generate many error message for a single problem, making debugging difficult and discouraging for novices. If the command file compiles without error, records are read one at a time, the interpreter is run to process the record, and, if the record was changed (LET or SET statement executed), the record is written back to the file. The interpreter implements a "virtual stack machine" which executes 29 different instructions. No attempt was made to make it general; the instruction set was tailored to the application. Actual referencing of the userbase record is done via table lookup, which will make U3 easy to modify for future version of RemoteAccess. User Updater -- Universal 24 OTHER UTILITIES BY THE AUTHOR OF U3 ECHOREPT -- GEcho report generator (freeware, with sources) PROCESSI -- Updates download counts in RA 2.0x from FrontDoor/InterMail FREQs (freeware with source) PPNL10 -- Pretty Print Fidonet nodelists (freeware with source) NNANS593 -- NNANSI ANSI.SYS fast/powerful replacement (shareware with source, free non-commercial use) KBDR.COM -- Makes caps lock key a control key (freeware) RESTART -- system configuration manager (freeware with source) RUNIT10 -- Program to spawn DOS VDM's from other DOS VDM's (for OS/2 2.0 or later) (Freeware) ALMYUTIL -- text utilities to add/remove tabs and leading spaces from text files. Also splits large files into smaller files. (freeware) JUSTFY14 -- reformats text files (freeware with source) REANSI13 -- convert among ANSI/Graphic, Avatar0+, RemoteAccess, Renegade, Wildcat codes, and plain ASCII. Superset uf UNANSI (freeware with source) UNANSI12 -- convert ANSI to vanilla ASCII (freeware with source) UNHTML10 -- removes HTML or CGML markup from text files (freeware with source) Programs are available from my Internet Web site, http://www.teleport.com/~almy, or via FTP at ftp.teleport.com/vendors/almy.