ftp.wwiv.com

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

/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / OFFLINE / O_QWK11.ZIP / O_QWKER.DOC < prev next >

Wrap

Text File | 1993-12-31 | 54KB | 1,272 lines

=========================================================== O_QWKer - QWK Mail Door for Opus 1.7x (C) 92,93,94 Bernardo Cardoso / Fausto Carvalho (2:361/1) =========================================================== Version 1.1 31-Dec-93 Sysop Reference Manual by Fausto Carvalho O_QWKer 1.1 Page 2 In memory of John Valentyn O_QWKer 1.1 Page 3 ============================= Organization of This Manual ============================= Page - Introduction ................................................4 - Current Features ............................................4 - Requirements ................................................5 - Configuring O_QWKer .........................................6 Configuration Commands ...................................6 Definition Group ......................................6 Session Group ........................................10 Sysop Local Mode Group ...............................12 - Installing O_QWKer .........................................14 Installing the Menu Option ..............................14 Multi-Line Setup ........................................16 Using O_QWKer across a Network ..........................16 Installing Compressors ..................................17 Installing Protocols ....................................18 Scanning Echomail .......................................18 - Security and Access Management .............................19 Scanning Messages for .QWK Packet .......................19 Importing Messages from .REP Packet .....................20 Message Import Error Codes ...........................21 - Menus and On-line Help .....................................22 Menus ...................................................22 On-line help ............................................23 - Insights ...................................................24 - License ....................................................25 - Disclaimer .................................................25 - Acknowledgements ...........................................26 - Contacting the Authors .....................................26 O_QWKer 1.1 Page 4 ============== Introduction ============== A mail door able to deal with the QWK format has been in the wish list of many Opus Sysops for quite a long time. We decided to embrace this project due to high pressure from our users: they are used to off-line reading and most of systems around here have QWK mail doors. In fact QWK is perhaps the off-line reading format which is closer to being accepted as a standard in BBSing, and that's far more evident when the three most popular off-line readers for Opus mail doors (in no particular order OMK, Blue Wave and Silver Xpress) support it. Another strong reason to carry this work has been our feeling that a mail door following the Opus spirit (free to use in a Lawful and Friendly manner) should be available for Opus 1.7x and later Sysops, since OMK stopped at version 1.14. After the release of our first major contribution to WOC (one year ago), a number of problems has been spotted. We hope that this release fixes them all without adding more... ================== Current Features ================== O_QWKer (pronounces Oh!Quicker) has been designed to be easy to set-up and use, yet powerful enough to have the confidence of Sysops and users. During the early design and implementation phases more and more features have been added. In fact our option to submit it to restricted Beta testing instead of wide distribution from the earlier versions proved to be the best way to attain a reliable piece of software, since the Opus Beta Test Team contributed valuable suggestions and careful testing of all features. Here are the most relevant: * Opus style user interface with ANSI/AVATAR support * Full Opus menus and command stacking * On-line help using external .OEC files * gets most of relevant data directly from Opus system files * multi-line support * multi-domain support * security is based on Opus privileges and keys * supports all the standard QWK features, including ADD, DROP and RESET commands * up to 8 different compressors * up to 8 different transfer protocols * inactivity, allowed time and carrier loss handling * orphaned messages stored in BAD_ECHO or an alternative path * allows mandatory areas definition O_QWKer 1.1 Page 5 * supports local Sysop usage with special features (eg. network access) * Opus style log file with different detail modes * supports MSGID kludge in Echomail areas * uses LREAD.DAT message pointers * message user counters updated - this is a must for systems enforcing Msg/DL ratios * supports automatic Echomail scan - ideal for barefoot Opus * includes a strategy to avoid multiple tear lines * if Opus binary date is null, FTS-0001/SEAdog ASCII time/date is used The door has been developed under Borland's Turbo Pascal 6.0. It has been tested with the following off-line readers: Speed Read 1.10 SLMR 2.0 and 2.1 OffLine 1.50 OLX 2.1 WinQWK 1.30 Blue Wave 2.10 1st Reader 1.0 ============== Requirements ============== O_QWKer requires DOS 3.x or later, Opus 1.7x or later and less than 210 KBytes of available RAM. It uses swap memory routines to allow the use of memory-hungry archiving programs like ARJ. A setting of FILES = 20 or more is required in your CONFIG.SYS or equivalent. An ANSI driver (e.g. ANSI.SYS) is required for correct console display. O_QWKer 1.1 Page 6 ===================== Configuring O_QWKer ===================== As we said above, most of the needed information to allow O_QWKer to run properly is extracted by the mail door directly from your Opus parameter file (*.PRM), so it is quite easy to configure it. Options not defined in the .PRM file, or just left to your decision, are defined in a plain ASCII configuration file called O_QWKer.CFG, which is searched in the same directory as the executable O_QWKer.EXE. Nevertheless please note this is just the default name - more on this later, under "Installation". You may have a look at the SAMPLE.CFG and MINIMAL.CFG files, both included in the distribution archive. Configuration Commands ---------------------- Lines beginning with % are considered comments and are ignored. In fact, the parsing of a .CFG line stops upon finding a % character, so it may appear anywhere to start a comment. The commands inside the configuration file do NOT need to appear in specific order. Definition Group ---------------- BBSID Identification of the QWK packet. This name is limited to 8 (DOS filename) characters and must be chosen in a way which can help users to identify your BBS. It should be as unique as possible. Ex: BBSID MidiThru BBSWHERE Location of your system, to be included in the QWK (optional) packet header. This parameter is just to keep compatibility with QWK format definition. Ex: BBSWHERE Aveiro, Portugal BBSPHONE Data phone number of your system to be included in (optional) the QWK packet header. This parameter is just to keep compatibility with QWK format definition. Ex: BBSPHONE 351-34-313554 PRM .PRM file. In the absence of this command, the (optional) door uses the OPUS environment variable (defined with SET OPUS=xxxx.PRM). Ex: PRM C:\OPUS\BBS.PRM NEWS News file to be included in the QWK packets. (optional) Ex: NEWS C:\OPUS\QWK\NEWS.TXT O_QWKer 1.1 Page 7 WELCOME ANSI screen to be included in the QWK packets (optional) (it's shown at the beginning of the users off-line reading session). Ex: WELCOME C:\OPUS\QWK\HELLO.ANS GOODBYE ANSI screen to be included in the QWK packets (optional) (shown to the users at the end of their off-line reading session). Ex: GOODBYE C:\OPUS\QWK\BYEBYE.ANS NEWFILES New files list, to be included in the QWK packets. (optional) This file must be created by a separate program (not included) like Opus-Fam. Ex: NEWFILES C:\OPUS\FILES\NEWFILES.TXT BULLETINS Bulletins directory. This directory contains files (optional) with names BLT-*.*, and the inclusion in the QWK packets is based upon the file date. This means that all new bulletins since the users last call date are included in his/her packet. Ex: BULLETINS C:\OPUS\BULL\ FORCE The user may active and deactivate several options (optional) in his/her O_QWKer configuration menu, to control what is included in their QWK packet. This command exists to control the use of those options and it is applicable on the following: WELCOME always include Welcome Screen GOODBYE always include Goodbye Screen NEWS always include News file NEWFILES always include new files list BULLETINS always include new bulletins REPLIES always include messages originated by the user NOVICE force Novice help level inside O_QWKer Ex: FORCE NEWS There is another syntax for this command, which allows you to force the scan of certain message areas, so that the user is not allowed to turn them off. That's the AREAS option. Ex: FORCE AREA 1 EXCLUDE This command has the opposite effect of FORCE. In (optional) its first syntax, it allows you to deny the user option of scanning message base for his/her Opus Alias name. For that you use the option ALIAS. Ex: EXCLUDE ALIAS O_QWKer 1.1 Page 8 The second syntax is AREAS, and allows you to define message areas to be excluded from the available O_QWKer areas list to any user with privilege bellow AsstSysop. Ex: EXCLUDE AREAS 0 31 99 FULLSCAN AREA This command makes the message scanning process (optional) ignore user pointers and always scan all messages in the areas to which it is applied. It is useful in an area where messages are frequently deleted, such as your Local Mail area. In such areas, it is not difficult to have an user pointer directed beyond the last message, which means no messages will be included in the packet, even if there are some unread. With the full scan, you guarantee that all eligible messages are delivered. You should activate a maintenance procedure to periodically erase received messages in the areas that you full scan, because even received messages keep being included in the user packets. Ex: FULLSCAN AREA 1 PACKER TEXT PACKER COMPRESS PACKER UNCOMPRESS These three commands groups define the packet compression scheme available for user selection. TEXT - description shown to users COMPRESS - command used to compress QWK packets UNCOMPRESS - command to uncompress REP packets You may define up to eight compression methods. The first one defined is used as default. Ex: PACKER TEXT Zip 1.10 PACKER COMPRESS C:\UTIL\PKZIP.EXE -U PACKER UNCOMPRESS C:\UTIL\PKUNZIP.EXE REDIRECT COMPRESSORS (optional) This option allows the redirection of compressor output to the user, thus giving visual feedback while their QWK packet is being compressed. When defined, it is applied to any capable defined compressor, like PKZIP and LHA. It is automatically disabled for Local usage. Ex: REDIRECT COMPRESSORS O_QWKer 1.1 Page 9 PROTOCOL TEXT PROTOCOL UPLOAD PROTOCOL DOWNLOAD These groups of three commands define the transfer options available for user selection. TEXT - description shown to users UPLOAD - batch file to upload REP packets DOWNLOAD - batch file to download QWK packets You may define up to eight protocols. The first one defined is used as default. Please note you must use a batch file, so that parameters can be passed to the protocol engine. Ex: PROTOCOL TEXT Zmodem (DSZ) PROTOCOL UPLOAD C:\OPUS\RZ.BAT PROTOCOL DOWNLOAD C:\OPUS\SZ.BAT NEWLINE This option defines what character will be used as (optional) CR/LF in messages included in the packet. All known off-line readers expect the character "a" (ASCII 227 decimal), so this is the default value. Changing the default implies the need of a special reader, but will give the possibility to work with codepages where char 227 may not be made available for separator functions (e.g. Chinese). Ex: NEWLINE 160 MSGID KLUDGE If this option is defined, all messages entered on (optional) Echomail areas will include a MSGID kludge. Ex: MSGID KLUDGE SHOW KLUDGES If this option is defined, all messages scanned to (optional) Sysop or AsstSysop will include Kludges, Seen-by's and Path lines. Ex: SHOW KLUDGES ALTER TEARLINE (optional) According to FTSC documents and Echomail Policy, only one tearline may appear on an echomail message. Nevertheless it is not uncommon to find messages containing 2 or even 3 of those. O_QWKer avoids deleting lines from the received messages but will substitute any candidate occurrence to -*- Going further, there are many echomail processors which do not respect the existence of a tearline in the message and add another one, so this option will avoid the normal inclusion of a tearline, and will rather include: -*- Opus-CBCS x.xx via O_QWKer vx.xx O_QWKer 1.1 Page 10 If you use the internal Opus echomail scanner, forget about this option, since you'll never need it. Ex: ALTER TEARLINE HELPPATH If this option is defined, it states where O_QWKer (optional) will be looking for the on-line help OEC files. By default, it is used the path to the executable O_QWKer.EXE. Ex: HELPPATH C:\O_QWKer\HELP Session Group ------------- STATUS LINE When this option is defined, a status line will (optional) appear at the console, allowing the Sysop to know who is using the mail door, the baudrate, and the caller's remaining time inside O_QWKer. Ex: STATUS LINE TIMELIMIT Maximum allowed time (in minutes) for an O_QWKer (optional) session. It defaults to 10 (minutes). Ex: TIMELIMIT 15 IDLETIME Maximum inactivity time (in minutes) allowed while (optional) inside the mail door. It defaults to 3 (minutes). Ex: IDLETIME 2 REFUND Percentage of time used inside the door to be (optional) refunded to the user. It defaults to 0% (no time refunded). Ex: REFUND 50 MAXMSGS Maximum number of messages which can be included (optional) in a single QWK packet. If used with the PROPORTIONAL qualifier, this command refers to the number of messages allowed if the user is connected at 1200 baud, so for 2400 it's the double the 1200 baud rate, and so on. By default it assumes the fixed value of 200. When O_QWKer is used in local mode, PROPORTIONAL resolves to 2,147,483,647 so we may say it is unlimited. Ex: MAXMSGS 300 MAXMSGS PROPORTIONAL 100 O_QWKer 1.1 Page 11 MAXLINES Maximum number of lines for each message included (optional) in the QWK packet. If the message is bigger, it is automatically split in chunks (several messages with the same number at the reader). Default is 60 lines. Ex: MAXLINES 100 LOGMODE Detail level of the log. The options are: (optional) LOGMODE TERSE (light) LOGMODE VERBOSE LOGMODE TRACE (lots of info) It defaults to VERBOSE. Ex: LOGMODE TERSE LOGFILE O_QWKer log filename. It defaults to O_QWKer.LOG (optional) in the executable (O_QWKer.EXE) directory. For multi-line Opus installations you should use one different file for each task. You can specify it by using the standard Opus wildcard for task number (##). Ex: LOGFILE C:\LOG\O_QWKer.LOG LOGFILE C:\O_QWKer\LOG##.LOG TEMPDIR Directory used by O_QWKer to process packets. All files in this directory are erased, so be sure to define it properly. The TEMPDIR value can also point to a RAMdisk. For multi-line Opus installations you should use a different directory for each task. You may specify it by using the standard Opus wildcard for task number (##). For security reasons TEMPDIR defaults to the name \O_QWKer$.TMP on the executable's volume, but please note this isn't an option but rather a protection to your system. A swap directory is also created inside TEMPDIR. Ex: TEMPDIR C:\TMPQWK TEMPDIR E:\QWK## KEEPTEMP By default, all temporary files created during the (optional) message scan process are erased upon generation of the QWK packet. Use this option to tell O_QWKer to keep them (until the Download messages command is selected again). Ex: KEEPTEMP O_QWKer 1.1 Page 12 QWKAREA Opus File Area number or Pathname to where QWK (optional) packets are to be moved in case of a Download failure, so that the user is allowed to perform a deferred download after quitting the mail door. In your NERF.BAT file you should check if there is any *.QWK file on the corresponding directory and erase it after each user logs out, to guarantee that no one will be able to receive packets belonging to another user. If this option is not defined in the configuration file, O_QWKer will not try to move the packet to somewhere in case of Download failure. Ex: QWKAREA 10 QWKAREA F:\QWKPKT BADPATH DOS path where orphaned messages are stored. This (optional) option has precedence over the BAD_ECHO pathname in BBS.CTL. If neither exist (either BADPATH in .CFG file or Opus BAD_ECHO) then the orphaned messages are discarded. Ex: BADPATH F:\BADQWK Sysop Local Mode Group ---------------------- ASSIGN This command allows you to use O_QWKer across (optional) networks. Although it exists mainly to support local usage, it applies to both local and remote sessions. All occurrences of the path defined as the first parameter will be searched in Opus system files (SYSMSG.DAT, SYSFILE.DAT) and processed by this door as being the path corresponding to the second parameter, just like DOS Assign command. You may declare up to 5 ASSIGN paths. Ex: ASSIGN C: O: ASSIGN X:\OPUS\SYSTEM C:\OPUS LOCALQWK Directory where QWK packets generated in local mode are stored. This is useful to a Sysop using his/her off-line reader across a network. Default is \O_QWKer$.LOC on the volume where the executable is installed. Ex: LOCALQWK N:\SLMR\QWK LOCALREP Directory where REP packets to be processed in local mode are stored. This is useful to a Sysop using his/her off-line reader across a network. O_QWKer 1.1 Page 13 Default is \O_QWKer$.LOC on the binary's volume. Ex: LOCALREP N:\SLMR\REP LOCALUSER Name of the LASTUSxx.DAT file to be used in local mode. Be aware that if you want to take advantage of the auto-scan O_QWKer feature in barefoot Opus installations, you should use the name of correct LASTUSxx.DAT file for your keyboard mode Opus task. Ex: LOCALUSER C:\OPUS\LASTUS02.DAT O_QWKer 1.1 Page 14 ==================== Installing O_QWKer ==================== Installing the Menu Option -------------------------- The door installation is quite easy: you just need to put the executable O_QWKer.EXE inside your chosen directory, create the configuration file as explained above and declare an Outside menu option: ... SECURE 2 ... _OUTSIDE Normal "QWK Mail door" = RUN C:\OPUS\O_QWKer.EXE ... In the example, O_QWKer would be accessible to all users with privilege Normal or above, and would read its configuration from the default file O_QWKer.CFG (in the C:\OPUS directory). If you want to use another CFG filename (e.g. QWK.CFG) you must add it at the end of the previous command line: ... SECURE 2 ... _OUTSIDE Normal "O_QWKer" = RUN C:\OPUS\O_QWKer.EXE G:\QWK.CFG ... Important Notice: it is clearly stated in section 7.1.1, page 151 of OTEC_170.TXT that you should 'NOT use periods in external program command lines! For example, "/N:lastus01" is OK, but "/N:lastus01.dat" corrupts memory'. We never came to the memory corruption occurrence while going against this recommendation, but it's better to be aware that it may cause problems. If you prefer to have the door placed on a directory of its own, there are at least two ways of having the job done: i) Using a path in the menu option ... SECURE 2 ... _OUTSIDE Normal "QWK Mail door" = RUN D:\MAILDOOR\O_QWKer.EXE ... ------------ ii) Calling the door using a batch file (using DOS outside option) ... SECURE 2 ... _OUTSIDE Normal "QWK Mail door" = DOS C:\OPUS\YOUR.BAT ... --- O_QWKer 1.1 Page 15 Inside your batch file you must pass command line parameters to O_QWKer: YOUR.BAT rem rem Let's assume home dir is D:\O_QWKer, Opus dir is C:\OPUS rem and your are using YOUR.CFG configuration file rem D: CD \O_QWKer O_QWKer YOUR.CFG %1 %2 %3 %4 %5 %6 C: ----------------- CD \OPUS rem rem Returning from outside rem If you are running out of core when shelling to O_QWKer, you may want to try the EXIT approach: ... RELOG 3 SECURE 2 ... _OUTSIDE Normal "QWK Mail door" = EXIT 77 ... Now if your NERF.BAT contains the adequate ERRORLEVEL trap, you may run the mail door. The EXIT method doesn't pass the arguments automatically to the external program, so you need to provide them explicitly in the batch file. As the door gets everything relevant from LASTUSxx.DAT, it's enough to pass the task number in the command line. Let's see an example for Task 2: ... IF ERRORLEVEL 77 GOTO O_QWKer ... :O_QWKer O_QWKer -t2 GOTO RELOG ... :RELOG Opus -o ... Please refer to Opus documentation about the options RELOG and AFTER RELOG EXIT. O_QWKer 1.1 Page 16 Multi-Line Setup ---------------- If you want to setup O_QWKer for multi-line systems, you will probably prefer to have a slightly different installation in your BBS.CTL file: ... Task $(Task) ... SECURE 2 ... _OUTSIDE Normal "QWK" = RUN O_QWKer.EXE O_QWKer.C$(Task) ... This way NACL would expand the name of the configuration file according to the defined Task number, and you would get: Task = 2 CFG filename -> O_QWKer.C2 Task = 1F CFG filename -> O_QWKer.C1F More on this subject in page 35 of OSOM_170.TXT operations manual. There is another option, based on the use of a single .CFG file, but using the task wildcard ## in the commands LOGFILE and TEMPDIR. With this approach you may use a single configuration file, since you will have different temporary directories and log files to each Opus Task. If you define, for example, TEMPDIR E:\QWK##, Task 1 will use E:\QWK01 whereas Task 44 will use E:\QWK2C (44 = 2C hexadecimal). Using O_QWKer across a Network ------------------------------ It isn't mandatory that O_QWKer is used from inside Opus. A Sysop with network access to his BBS may want to receive/send his echomail without logging-in the system. Here are some notes on achieving this. You should create a batch file which runs the door with your special .CFG file. It should be something like the following: rem Echo Using O_QWKer in local mode across the Network X:\MAILDOOR\O_QWKer X:\MAILDOOR\NETLOCAL.CFG -k rem This example assumes that you have O_QWKer installed in the directory MAILDOOR on the BBS disk (you see it as drive X), and your special .CFG filename is, in this example, NETLOCAL.CFG. This special configuration file must be prepared carefully. Don't forget to have PRM option pointing to the Network volume, to have a different log file (LOGFILE) and another temporary directory (TEMPDIR), preferably in your workstation local disk. You also will need to use ASSIGN to have the door correctly interpreting data extracted from Opus system files and redirect the accesses to the correct volumes (e.g. ASSIGN C: X:). O_QWKer 1.1 Page 17 Finally you may want to have a copy of LASTUSxx.DAT with your data, and renamed to something else. Please be aware that currently, used this way, O_QWKer neither updates the user message counters in USER.DAT, nor triggers the echomail scan. And that's it. You may create several variations based on this setup, but the idea is built around the ASSIGN configuration commands and the -k switch. Installing Compressors ---------------------- You may make available up to 8 different packing schemes to your users, but only one is mandatory. Both QWK and REP packets are exchanged as archives, to minimize transfer time. You define each of them using a group of three .CFG lines. Take ZIP as an example: PACKER TEXT Zip 2.04g PACKER COMPRESS C:\UTIL\PKZIP.EXE -A PACKER UNCOMPRESS C:\UTIL\PKUNZIP.EXE Following there is a list of common archivers, and the recommended .CFG syntax to be used. Type COMPRESS UNCOMPRESS -------------- ---------------- ---------------- ARC (V.Buerg) arca.com arce.com ARC (PKWare) pkarc.exe -oct a pkxarc.exe PAK pak.exe a /wa pak.exe e /wa ZOO zoo.exe -add zoo.exe xO ZIP pkzip.exe -a pkunzip.exe LHA lha.exe a /m lha.exe e /m ARJ arj.exe a -y arj.exe e -y Please note that many off-line readers only support ZIP, LHA and ARJ packets, so perhaps it's a wise move to stick with these. By default, compressor output is shown only on console, so a user may think that the program just crashed while he waits for the compression of a QWK packet containing many messages. To overcome this annoying situation, you may redirect the compressor output to the COM port, so it is shown to the user rather than the Sysop. This is accomplished by the global CFG option REDIRECT COMPRESSORS Nevertheless there are some compressors that don't send their output to stdout, so they can not be redirected. This is the case with ARJ. When an user uploads a REP packet compressed with a method that doesn't match his current compressor user option, O_QWKer reports him the fact and logs the occurrence. O_QWKer 1.1 Page 18 Installing Protocols -------------------- O_QWKer doesn't have any built-in file transfer protocols, so you must install them externally. O_QWKer executes the command defined in the configuration file (see PROTOCOL UPLOAD and PROTOCOL DOWNLOAD options above) and passes the following parameters: %1 Port (1 - COM1, 2 - COM2, etc.) %2 Baudrate %3 Filename Let's see how you can use this together with DSZ (Omen Technology Inc.) (By the way, you should use the .EXE version of DSZ). ------------------- O_QWKer.CFG ... PROTOCOL TEXT Zmodem (DSZ) PROTOCOL UPLOAD RZ.BAT PROTOCOL DOWNLOAD SZ.BAT ... SZ.BAT @echo Sending QWK packet dsz ha cts port %1 speed %2 sz %3 RZ.BAT @echo Receiving REP packet dsz ha cts port %1 speed %2 rz Both SZ.BAT and RZ.BAT are included in the distribution archive, so that you don't need to cut and paste that information. Scanning Echomail ----------------- O_QWKer searches your PRM file for the existence of the option LOG ECHOMAIL, and updates the ECHOTOSS.LOG (or whatever name is defined). But it goes beyond that: in a barefoot installation this mail door updates the internal Opus flags, so that an automatic mail scan is triggered if any echomail message areas received a message via O_QWKer and your system is configured to act that way (SCAN ECHOMAIL in your CTL file). This implies three conditions: * Outside menu command must use DOS or RUN * SECURE must be set to 2 * you must use LASTUSxx.DAT in your O_QWKer.CFG (in LOCALUSER) If you prefer, you may alternatively check the existence of ECHOTOSS.LOG file upon user exit and perform an Opus run with -s switch or use your preferred Echomail processor. If ECHOTOSS.LOG is not defined, then no log is generated. O_QWKer 1.1 Page 19 ================================ Security and Access Management ================================ O_QWKer relies upon Opus privileges and key features in order to achieve an easy way to control packet creation and message upload. Furthermore, you can use the commands FORCE AREAS and EXCLUDE AREAS for additional access management. At this point it is important to present our interpretation of the access keywords in Message Areas definition (in BBS.CTL). The first two may be obvious; ACCESS and PEEK. The first grants reading access and the second defines the privilege needed to read private messages not addressed to the reader. So the question is between EDIT and UPLOAD: in our view, EDIT relates only to messages introduced on-line, whereas UPLOAD relates with messages prepared off-line and introduced in the BBS either using the Upload command or an Off-line Reader Door. Based on this interpretation, O_QWKer doesn't care how the EDIT privilege and keys are set. Now, you may ask "Do I get any advantage setting EDIT and UPLOAD priv/keys different?". Indeed: if you want an area to have short messages and not many replies with heavy quoting, just give EDIT access and deny UPLOAD, so that users can't prepare off-line lengthy messages... Got the picture? The best way to introduce you to this issue is to present the sequence of actions taken by the door during Message Scan and Import processes. Scanning Messages for .QWK Packet --------------------------------- For each existing Message Area 1. Message Area ACCESS privilege and keys are matched against user profile 2. If the Area is declared mandatory by FORCE AREA configuration command skip to 4. (you may argue this should be the first test, but this way the door will not grant access to a privileged area which you erroneous have declared mandatory, thus giving an additional degree of security) 3. Check if this Area is currently toggled on by the user 4. If user's privilege is below AsstSysop, check if Area is excluded by the EXCLUDE AREA configuration command 5. If Area is only for Public Messages, skip to 8. 6. Check PEEK privilege and keys and if PEEK access is granted, ignore 7. 7. Match Username 8. Include message (starting after current message pointer in O_QWKer 1.1 Page 20 LREAD.DAT) and skip (7. or 8.) for next message until no more messages in Area. If private and addressed to current user, flag it as Received If message has more than MAXLINES lines, there is a split in smaller messages. 9. Update O_QWKer$.PTR (temporary new message pointers) for later update Importing Messages from .REP Packet ----------------------------------- 1. Match .REP identification, to ensure this packet is to your BBS. This is one of the reasons you should configure a unique BBSID name For each Message in Packet 2. Message Area ACCESS privilege and keys are matched against user profile 3. Check UPLOAD privilege and keys 4. If user's privilege is below AsstSysop, check if Area is excluded by the EXCLUDE AREA configuration command 5. Check if Area is Read/Only 6. Capitalize From: and To: message fields (user names) 7. Match Username against From: message field 8. Create message, according to Area message allowed types: if Area only accepts Private messages, Pvt flag is set, even if the message have been composed as public; if the Area is Public only, Pvt flag is reset. 9. If Area is Echomail and MSGID KLUDGE is defined in the configuration file, the kludge is inserted in the message O_QWKer 1.1 Page 21 Message Import Error Codes -------------------------- When the import process fails, the user gets an error report instead of the area number where the message would be placed (the error is also logged). The error codes are the following: *BAD* Severe Error. Shouldn't occur. Report to the authors. *R/O* Message Area is Read-Only *PRV* Not enough privilege to access Message Area *EXC* Message Area excluded by Sysop (EXCLUDE AREA option) *N/A* Message Area not found *USR* Name in From field doesn't match username *N/X* Matrix/Netmail not yet supported *NO$* Not enough Credit to send Matrix message *TO?* Matrix Address not found *ERR* QWK command error (ADD, DROP or RESET area) O_QWKer 1.1 Page 22 ======================== Menus and On-line Help ======================== Menus ----- There isn't much to say about O_QWKer menus, except that they follow Opus menus as much as possible. This includes support for NOVICE, REGULAR, EXPERT and HITECH menus, plus command stacking and ANSI support. The NOVICE menus are assigned to all new users, regardless their Opus help level. Later, an user may decide to have O_QWKer menus to follow the Opus level, by switching to "NO" the "Help Novice" User Option. The tree includes the following menus: Main - Grants access to packet upload and download, configuration menu, and general information screen Configuration - Allows access to further menus for areas, protocols, compressors and user options Areas - In this menu it is possible to toggle areas for inclusion in the message scan process, and also to reset the user message pointers for each area. Please note that all/only the areas to which the user has access, either R/W or R/O, are shown in the associated screen, and Down/Up commands allow for viewing more in case a page isn't enough Compressors - The user is allowed to choose from up to eight programs you made available in the configuration file (PACKER... commands) Protocols - The user is allowed to choose from up to eight transfer protocols you made available in the configuration files (PROTOCOL... commands) User Options - Allows to set/reset several user options which control the information included in QWK packets and the help level O_QWKer 1.1 Page 23 On-line Help ------------ Help command (?, just like in Opus) is available at all O_QWKer menus. Each help corresponds to an OEC external file. The recognized names are: Loading O_QWKer - INITIAL.OEC Main Menu - MAIN.OEC Configuration Menu - CONFIG.OEC Areas Menu - AREAS.OEC Compressors Menu - COMPRESS.OEC Protocols Menu - PROTOCOL.OEC User Options Menu - USER.OEC Download - DOWNLOAD.OEC Download Error - DLERROR.OEC Upload - UPLOAD.OEC Upload Error - ULERROR.OEC Leaving O_QWKer - FINAL.OEC By default, these OEC files have to be placed in the executable directory (the same as O_QWKer.EXE), otherwise they won't be shown to the users. You may use the configuration option HELPPATH (please refer to "Configuring O_QWKer", above in this manual) to override this default. A message is shown to the user if no helpfile is found. The OEC commands correctly evaluated by the help sub-system are: [Enter] [ClrEol] [Home] [Newline] [Cls] [Blink] [Colour on Colour] Colour names are: Black, Blue, Green, Cyan, Red, Magenta, Brown, LightGrey, Grey, LightBlue, LigthGreen, LightCyan, LightRed, LightMagenta, Yellow and White. Blink is enforced up to the next colour change. O_QWKer 1.1 Page 24 ========== Insights ========== Besides the two main files - O_QWKer.EXE and the Config file, the O_QWKer mail door relies upon a file maintained by itself, called O_QWKer.DAT and located again in the same directory. It contains the user options (selected areas, packet options, protocol, compressor) indexed with the same key as in Opus's USER.DAT. Please note that no particular message pointers are used by this mail door - it uses and updates the LREAD.DAT file on each message area, including the Sysop pointers. If the O_QWKer.DAT file is erased, all users will have to re-select areas, compressor, protocol and options, so it is recommended that you include this file in your daily backup procedures. There are also two other files you might also find hanging around, although normally erased by the door. The first is a swapfile (with an unique DOS name) created by the door inside O_QWKer$.SWP directory (itself inside TEMPDIR directory). Normally the door swaps to EMS or XMS before executing the archiver or the file transfer program. If memory is not available, the swapper uses the directory pointed by the TMP or TEMP in the DOS environment (defined with DOS command SET TMP=C:\XXX). As a last move, this O_QWKer$.SWP directory is used. The second is O_QWKer$.PTR, a temporary holder of user's message pointers, used to restore them if the .QWK packet download is aborted. O_QWKer 1.1 Page 25 ========= Licence ========= All FidoNet Sysops are hereby authorized to use and/or distribute O_QWKer provided only that (1) no money is charged for either its use or distribution (2) it is distributed together with all files included in the original distribution archive (change of compression method is allowed) (3) the inclusion of O_QWKer software in any kind of compilation or another software package is subject of a previous written authorization from his authors (4) it is used under the Opus spirit - in a LAWFUL and FRIENDLY manner (5) it is not a version under restricted testing ============ Disclaimer ============ Please be aware that programs such as Mail Doors have to deal with Opus at a very low level. This means accessing files like USER.DAT, SYSMSG.DAT and other critical points and possibly updating some of these files. While every attempt has been made to code and test this software, you should keep current backups of your system, should any problems develop. You should carefully observe all configuration options and install the door as advised in the documentation. Although we tried to incorporate security mechanisms to overcome your creative procedures, we obviously cannot guarantee that O_QWKer will be able to preserve the integrity of your system. O_QWKer is provided on an AS-IS basis. No responsibility shall be taken by its authors in relation to anything happening to your system, directly or indirectly arising from its use, malfunctioning and/or installation. O_QWKer 1.1 Page 26 ================= Acknowledgements ================= Besides everybody that kept Opus alive all these years, this project had the direct collaboration of nice people around the WOC (specially from the Opus Utility Team), that helped in many ways to shape what O_QWKer currently is and what it will be in the future. Some people involved in the testing cycle and technical support deserve a very special reference, for helping tracing and fixing the problems: Cheryl Buzzell Erik Likvarn Trev Roydhouse Mark Shultise Jon Morby Stein-Ivar Johnsen Roger Franz Chinian Wang John Valentyn Rob Lerman Todd Savoie Chris Moran Antonio Vieira Jeff King Vasco Santos Patrick Lee Thomas Wagner Kay Akagi Thanks a lot, on behalf of all O_QWKer users! QWK format copyright (C) Mark "Sparky" Herring ======================== Contacting the Authors ======================== O_QWKer is a copyrighted joint work by Bernardo Cardoso Programming Fausto Carvalho Design, Verification and Doc's You may contact the O_QWKer development team using MEADOW or sending Netmail to 2:361/1 or 2:361/7