Boston 2

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

/ Boston 2 / boston-2.iso / DOS / HILFEN / MODEM / SALES / MISC.XXX / TX2MB220.ZIP / TXT2MSG.DOC < prev next >

Wrap

Text File | 1991-03-10 | 52KB | 991 lines

TXT2MSG 2.20 Page 1 T X T 2 M S G (fondly referred to as "Tex" by the FTL users) Textfile to PCBoard 14.x MessageBase Utility Release Version 2.20 Copyright 1988,90,91 Robert Vostreys All Rights Reserved (revised: Tue Mar 5, 1991) Table of Contents What is TXT2MSG? . . . . . . . . . . . . . . . . . . . . . . . . 2 Distribution File Contents . . . . . . . . . . . . . . . . . . . 3 Shareware Distribution . . . . . . . . . . . . . . . . . . . . . 3 TXT2MSG Operation . . . . . . . . . . . . . . . . . . . . . . . . 4 Commandline Parsing . . . . . . . . . . . . . . . . . . . . 4 Default Operation . . . . . . . . . . . . . . . . . . . . . 5 Commandline Switches . . . . . . . . . . . . . . . . . . . . 5 Script Questionnaire Processing . . . . . . . . . . . . . . 9 Example SQ2MSG Processing . . . . . . . . . . . . . . . . . 10 TXT2MSG Environment Variable . . . . . . . . . . . . . . . . 10 By Conference Number . . . . . . . . . . . . . . . . . . . . 11 Textfile Control of Message Header . . . . . . . . . . . . . 12 Notes and Limits of Operation . . . . . . . . . . . . . . . 13 Contacting the Author . . . . . . . . . . . . . . . . . . . . . . 14 The Future of TXT2MSG . . . . . . . . . . . . . . . . . . . . . . 15 PCBoard 14.x Messagebases . . . . . . . . . . . . . . . . . . . . 16 Message Insertion Logic . . . . . . . . . . . . . . . . . . 16 Structure of Messagebases . . . . . . . . . . . . . . . . . 16 TXT2MSG 2.20 Page 2 What is TXT2MSG? TXT2MSG is a Sysop utility for use with PCBoard 14.x based Bulletin Board Systems. TXT2MSG allows you to insert textfiles into your PCBoard messagebases from the DOS commandline or from within a batchfile. Starting with version 2.10, TXT2MSG also incorporates and replaces the widely used SQ2MSG which takes Script Questionnaire ANSWERx files and CALLERx logs and imports them into a messagebase. Version 2.20 adds ProDoor ZIPM and PCBoard Capture file processing. TXT2MSG becomes very useful when used with your event processing, giving you: reports of operations, netmail traffic, packing logs, abnormal user logoffs, script questionnaire answers, callers logs for a list of users, etc. TXT2MSG also allows your users to upload messages using a protocol transfer (such as Xmodem or Zmodem) and then have the message inserted into the appropriate conference. See sample batchfiles for examples of uses. This utility is entirely commandline driven. All operations and parameters are specified to TXT2MSG on the commandline and optionally the DOS environment via SET TXT2MSG=[options]. TXT2MSG has been written for speed and functionality in Borland TurboC with several assembly subroutines. Complete DOS 3.1 network support is implemented and TXT2MSG will correctly recover when in conflict with another process. You should have no problems operating in multi- tasking and LAN/Network environments. If some critical error occurs, TXT2MSG will abort and display an error and errorlevel that can be tested for in batch files. A table of errors and errorlevels appears later and in QuickRef.DOC. Copyrights and Acknowledgments Special thanks to these folks for their initial support of TXT2MSG: Roger Sligar The Right Place<tm> 404-476-2607 Tim Farley SemWare/QEdit Support 404-641-8968 NASA Huntsville SpaceLink Educational 205-895-0028 David Hellwege Access In Melbourne (61) 3-592-3338 Copyright, Trademark, and Servicemark notices: TurboC Copyright <c> 1987,1989-91 Borland International PKZIP Copyright <c> 1989-90 Phil Katz PCBoard Copyright <c> 1985-91 Clarke Development (CDC) SQ2MSG Copyright <c> 1987-88 Robert Vostreys RNET Copyright <c> 1989-91 Robert Vostreys TXT2MSG Copyright <c> 1988,1990-91 Robert Vostreys MS-DOS Trademark of MicroSoft Corporation PC-DOS Trademark of IBM Corporation References otherwise not documented: FTL Refers to FTL BBS, home of TXT2MSG, 404-292-8761 ILink Refers to the ILink International Network RIME RelayNet International Message Exchange DOS Refers to MS-DOS and/or PC-DOS TXT2MSG 2.20 Page 3 Distribution File Contents TXT2MSG is usually distributed using the Phil Katz PKZIP (.ZIP) packing utility but also may appear as a .PAK or .LHZ or whatever. All references to the distribution file will be termed 'Zipfile'. The Zipfile used to distribute TXT2MSG is named using the following naming convention: TX2Mvvvx.zzz vvv = version release number (ie '200') x = alpha/beta version code ('a'-'n') registered version code ('r') unregistered version ('u') general release version (none) zzz = packing method extension ('ZIP') TX2MBvvv.zzz may also be used occasionally. Please take the time to examine the contents of the TXT2MSG Zipfile. You should find the files listed below and perhaps a couple additional example batch files (late additions): TXT2MSG .EXE - The actual TXT2MSG program TXT2MSG .DOC - The documentation you are now reading QUICKREF.DOC - Quick reference information/listings REGISTER.DOC - Registration form and information CHANGES .ver - List of changes (history files) SAMPLE .MSG - Example textfile showing header control ABNORMAL.BAT - Example batchfile (abnormal logoff rpt) LOGMAIL .BAT - Example batchfile (mailrun process rpt) NASAMAIL.BAT - Example batchfile (multi-file example) EVENTSYS.BAT - Example batchfile (event process report) SCRIPTS .BAT - Example batchfile (SQ2MSG processing) TRACKUSR.BAT - Example batchfile (watching users rpt) The only file needed is the actual program itself (TXT2MSG.EXE). All of the other included files are provided only for your information and understanding. If you come up with an interesting use for TXT2MSG, please pass on the batchfile for the benefit of others. Shareware Distribution Shareware is a unique method of product marketing. Shareware products are easily obtained from most larger Bulletin Board Systems around the world. This method of distribution uses the honor system for product distribution, meaning, you may use the product for a trial period to determine if it is of use to you. If you continue using a shareware product you are expected to send the registration once you have determined the product fits your needs. Please feel free to test and use TXT2MSG to determine if it suits your needs. If you continue using it, complete the registration form (REGISTER.DOC) and mail that with the registration fee ($10 suggested) to the address on the form. In exchange, you will be kept up to date on all new versions as available, get timely support as needed, and be able to access and use the beta versions. There also may be 'special' versions of TXT2MSG only available to those folks who have registered. Your timely registration will encourage further development of TXT2MSG and other BBS Sysop shareware utilities! TXT2MSG 2.20 Page 4 TXT2MSG Operation Commandline Parsing TXT2MSG will accept options and file specifications in any order EXCEPT that the first file specification seen will be assumed to be a PCBoard messagebase file (or conference number, see below). Any other file specifications, which may include @list and wildcard filenames, are considered text files for processing (exception: See "Script Questionnaire Processing" below). Options (switches) may be intermixed in any order using the '/' or '-' switch characters. You may combine all single switch options under a single switch character. You could, for example, combine -r, -z, and -i as simply -rzi. The basic commandline syntax for TXT2MSG is represented as: TXT2MSG [options] d:\dir\msgs [@list] [files...] The Conference Number commandline syntax is represented as: TXT2MSG [options] ## [@list] [files...] Both the basic and Conference Number syntax can be used with the Script Questionnaire/Tracking operation. Note that the files to process (including those found in @list files) are treated as caller log files to search, not textfiles to process. The script ANSWERx or user tracking list files are designated by the -q switch: TXT2MSG [options] d:\dir\msgs -qANSWERx [@list] [callers...] TXT2MSG [options] ## -qd:\dir\ANSWERx [@list] [callers...] Examples of valid commandlines: TXT2MSG d:\conf\1\msgs e:\textfile.doc TXT2MSG d:\conf\1\msgs -rz e:\textfile.doc TXT2MSG d:\conf\1\msgs @e:\listfile e:\textfile.* -rz TXT2MSG d:\conf\1\msgs /nzbm e:\textfile.doc /ri f:\*.* (switches -n, -z, -b, -m, -r and -i) Additional commandline examples are shown under the headings of "Script Questionnaire Processing" and "By Conference Number" below. If you invoke TXT2MSG without any parameters, you will be shown the version, compile date, copyright, commandline syntax, and valid commandline switches to remind you of TXT2MSG operation. Likely, TXT2MSG will be able to parse most any commandline sequence you care to give it. If it gets confused or lost, you will be shown the offending switch(s) as it aborts operation with a DOS errorlevel. Wildcard filenames are accepted both on the commandline and in any @list file lists. You may use absolute or relative directory references as long as they are valid DOS file specifications. TXT2MSG 2.20 Page 5 Default Operation Full multi-node insertion and directory flushing. Direct screen writes for pop-up windows. Current date/time for message entry date/time. Local (non-ECHO). Accept instructions (header modifications) within textfile body. TO: "ALL" if public (-p), "SYSOP" if R/O (-r) message. FROM: "SYSOP (TXT2MSG PROCESS)". FROM: username in script (if using the -q switch). SUBJECT: "TXT: filename.ext" (the base filename being imported). SUBJECT: "SQ: filename.ext" (if the -q switch is used). Unlimited number of messages created to fit entire textfile. Only a single message generated per script if using -q switch. Commandline Switches Message Header Control Switches Note that the following switches may be overridden by special text within the textfile body if -n has NOT been specified and/or if -h HAS been specified. Each entry below has its "Override:" entry for your quick reference. Please note that the quotes ("") should NOT be included and the override must be flush left in all capital letters. See "Textfile Control of Message Header" for more information. If two commandline switches conflict, the LAST one will take precedence. This allows you to override any environment settings. -p Public message to "ALL". Override: "PUBLIC:" Override: commandline "-r". -r Receiver-Only to "SYSOP". Override: "PRIVATE:" Override: commandline "-p". -e Echo message. Use -e if the message is to be 'echoed' to another BBS via a netmail package such as RNet. Override: "NOECHO:" Override: commandline "-l". Override: message subject starting with "NE:". -l Local message. The reverse of the -e switch. The message is "local only". Override: "ECHO:" Override: commandline "-e". Override: message subject starting with "E:". -s Message SUBJECT. Use the -s switch to designate what the message subject should be set to. You must either place the entire switch in quotes (such as "-sTHIS IS A SUBJECT") or use underscores (such as -sTHIS_IS_A_SUBJECT) for -s, -t, and -f switches to accept multiple words. Any and all underscores will be replaced with spaces automatically. Override: "SUBJECT: This is a subject" TXT2MSG 2.20 Page 6 -f Message FROM. Use this switch to specify who the message is to be "from". See -s above for usage of quotes and underscores. Override: "FROM: firstname lastname". Override: commandline "-u". -t Message TO. Use the -t switch to specify who the message is to be "to". See -s above for usage of quotes and underscores. Override: "TO: firstname lastname". Override: commandline "-v". -u Use PCBOARD.SYS for FROM field. Use -uD:\DIR\PCBOARD.SYS to specify that the message should be "from" the username found in the PCBOARD.SYS file. Override: "FROM: firstname lastname". Override: commandline "-f". -v Use PCBOARD.SYS for TO field. The -vD:\DIR\PCBOARD.SYS tells TXT2MSG to use the current username found in the PCBOARD.SYS file for the "to" field. Override: "TO: firstname lastname". Override: commandline "-t". -d Use filedate for message date/time. TXT2MSG defaults to using the current system date/time for the date/time used on the message. However, specifying the -d switch will make the date/time of the message the same as the date/time stamp found on the file. Override: "DATE: mm-dd-yy". Override: "TIME: hh:mm". -h Header modifications allowed (TXT file control). TXT2MSG allows you to specify the header information for the message within the message text. This switch re-enables header control within the textfile if disabled by -n. -n Header modifications NOT allowed (commandline control only). If you do not want the text within the textfile to be parsed for header control (such as "TO: name") use the -n switch. If importing from an unknown source or document file the -n switch is nearly always recommended. The reverse is -h. Other Message Control Switches -a Alter low-ASCII characters. The -a switch will enable TXT2MSG's filtering operation to correct (convert) low ASCII characters. This includes handling the ESC code used in ANSI sequences. The -g (graphics) switch is the reverse. -g Allow low-ASCII characters (graphics). This switch will disable the low-ASCII filter. You will need to include this switch if you want to import ANSI graphic sequences into messages. TXT2MSG 2.20 Page 7 -i Identify/tagline. If you include the -i switch, TXT2MSG will append an identification tagline (and tearline) to the bottom of all messages. The tagline uses the block (254) character and appears similar to: " ■ TXT2MSG v.vvx [sysdate systime]". If you want to change the tagline use the environment TAGLINE= (this is the same environment variable ProDoor uses for its tagline). If the -i switch is enabled, TXT2MSG will also "pack" any existing taglines in the source text. This is very useful if importing "joint" messages from a ProDoor ZIPM or PCBoard Capture file. -x Specify the maximum number of messages per source textfile. Use -x# (# = 0 to 9) to specify how many messages TXT2MSG can make when a textfile is longer then 96 lines. A "(continued)" line is added to the bottom of a split message and to the beginning of the next message. If any messages are split because of length, the "message number" will be placed in the 25th position of the subject field ("1" on the first message, "5" on the fifth, etc). Specify -x0 (which is default) if you want TXT2MSG to make as many messages as needed (up to 9999 messages) to import the entire textfile. This has no effect during script questionnaire (-q) or joint (-j) file processing. -z Single-node fast multi-message insertion. The -z (zippy) switch tells TXT2MSG not to flush the directory structure when inserting multiple messages. This option is basically used for single-node systems or when you know there are no users accessing a particular messagebase during message insertion. Backup logic, for safety reasons, still forces a DOS3 LOCK on the messagebase during insertions. This switch has no true effect on single message insertions. -q Script Questionnaire processing (SQ2MSG). Use -q to specify the location and filename of a script questionnaire ANSWERx file to process. This should appear something like: "-qD:\PCB\MAIN\ANSWER1". Do not put any spaces between the -q switch and the filename to process. When this switch is in effect, TXT2MSG uses different rules for the FROM field and processes the other files specified much differently. See "Script Questionnaire Processing" below for more information. -j Joint (multimessage) sourcefile processing. Specify the joint switch when you are importing a ProDoor ZIPM or PCBoard Capture file. This also works with straight terminal program "logs" of a R;S;NS of a messagebase. Useful for translating an older or non-PCBoard messagebase to PCBoard 14.x format. Each message within the sourcefile will be processed into a message in the destination messagebase. You will need to execute TXT2MSG multiple times if importing multiple joint source files. In other words, TXT2MSG only accepts the first textfile when the -j switch is included. TXT2MSG 2.20 Page 8 Screen/Interface Switches -b BIOS screen writes. This switch will force TXT2MSG to use BIOS writes for screen displays. This is likely unneeded unless using an older multi-tasker or a not-so-compatible computer. TXT2MSG should detect most of the more common multi-tasking systems and enable this option automatically. If the auto-detection fails, use this switch to force BIOS screen operations. -c CGA snow reduction. Use this switch if you get 'snow' on the screen during direct screen writes and would rather not see it. TXT2MSG should automatically detect if you have an older CGA display and enable this automatically. If this automatic detection fails and you desire snow reduction use this switch. -m Monochrome/LCD display colors. This switch will force the output for best operation on monochrome and LCD displays. TXT2MSG will automatically detect most monochrome and mono-graphic display adapters as well as supporting the current screen MODE setting. If this automatic detection fails, this switch will force the issue. TXT2MSG 2.20 Page 9 Script Questionnaire Processing TXT2MSG and SQ2MSG have, until this time, been separate programs. They have been combined into one program (TXT2MSG) since the code between the two programs was basically being duplicated. The SQ2MSG code added only about 1K bytes to the final TXT2MSG.EXE size and eliminated the 20K separate program of SQ2MSG.EXE. The idea behind SQ2MSG is to process new script questionnaire answers into a message addressed from the user completing the script. This gives the Sysop (or Sysop helpers) the ability to do a (F)ind when reading the message to easily upgrade or edit that users record. Once you start reading scripts in the messagebase instead of going out to disk you'll wonder how you survived without it! Another feature which is important to SQ2MSG is that commonly you want to check that the new user read the required bulletins, or perhaps want to check if they tried to download files right off the bat. SQ2MSG will, optionally, append users' callers log entries to the end of their script answer message! You can now, simply by reading a single message, see new users' script questionnaire answers and their callers log entries. If they did what was required (or not), you can simply use the (F)ind command to edit their user record. In addition, this implementation of SQ2MSG gives you the ability to create a list of users to "watch". Users in this special list will have their callers log entries placed in a message for you to examine to see what they might be up to. This is explained further in the example batch files TRACKUSR.BAT and TRACKONE.BAT. SQ2MSG processing is slightly different than the normal TXT2MSG processing. General operation is exactly the same, except: The -f (from) switch will no longer work. The messages will always be addressed from the user who answered the script. You must specify the script questionnaire answer file to process with the -q switch. This would normally looks something like: -qD:\PCB\MAIN\ANSWER1. Do not put any spaces between the -q and the filename to process. The inclusion of the -q switch (and filename) tell TXT2MSG that you wish SQ2MSG processing not the normal TXT2MSG processing. The questionnaire answer file is processed differently than TXT2MSG normally processes text files. The file is scanned looking for "From: username,". When found, it takes all text between that point and the next "From: " (or the end of the file) and inserts it as a message. No message header modifications via textfile are permitted (ie, a -n switch is assumed). All other files specified (via wildcard, @list, or explicitly) are treated as callers logs. The specified files will be scanned for caller log entries from the username completing the script. These files are not imported (as normal TXT2MSG processing would do) - only the text/log entries which are from the given user are. This allows you to easily determine if a user read the required bulletins or tried to download files or whatever. TXT2MSG 2.20 Page 10 Example SQ2MSG Processing (see also the SCRIPTS.BAT example batchfile) TXT2MSG c:\pcb\main\msgs -qc:\pcb\main\answer1 d:\logs\caller? -r The above example shows perhaps the most common usage for the script questionnaire processing abilities of TXT2MSG (SQ2MSG). The answer file c:\pcb\main\answer1 is scanned and entered as messages to the c:\pcb\main\msgs (main board) messagebase. Messages will be R/O, addressed to SYSOP (-r), and have any callers log entries found in the d:\logs\caller? files appended. You need one of these statements for each of your script ANSWERx files (if you have more than one) since TXT2MSG only accepts a single -qANSWERx statement. TXT2MSG 21 -qc:\conf\1\answer5 -pil -tALL -sConf_21_Application This second example shows how you might have a script questionnaire (which produces c:\conf\1\answer5) for requesting access to a private (adult) conference. The script answer messages are placed into conference 21 and are addressed to ALL in a public message. The other conference members could then review this script answers to decide if they wanted this person to join their party. Note that no additional files are specified (only 21 and c:\conf\1\answer5 files) -- thus, no callers log entries will be included in the message. TXT2MSG Environment Variable TXT2MSG will search for the environment TXT2MSG= before it does any commandline parsing. You may specify any options you wish TXT2MSG to use as defaults. If any switches are found on the commandline which conflict with the environment, the commandline takes precedence. For example, your AUTOEXEC.BAT might have: SET TXT2MSG=-mbiz -fSYSOP -l This would set the default operation to use Monochrome color (-m), BIOS writes (-b), include a tear and tagline (-i), override directory flushing for faster operation (-z), messages will be addressed from SYSOP (-fSYSOP), and will be "local" (-l). If another -f was found on the commandline, it would override the -fSYSOP in the environment. As well, if a -e was found on the commandline it would override the -l. If you have a batch file with several calls to TXT2MSG, you might want to include a SET TXT2MSG statement to avoid having to repeat yourself on each invocation. If you find that the commandline for TXT2MSG is too long (either by the DOS limitation of 127 bytes or for aesthetic reasons) simply move some of it to the TXT2MSG environment. Use the TXT2MSG environment to specify those switches you find you are always using in TXT2MSG commandlines. If you are running a single node system you might wish to use SET TXT2MSG=-z to force high-speed insertion at all times. Or, perhaps during event processing you always send the messages to a special conference you might use a statement of SET TXT2MSG=d:\conf\special\msgs in your EVENT.SYS file. The TXT2MSG environment is NOT required for TXT2MSG to operate. TXT2MSG 2.20 Page 11 By Conference Number You may use a conference number in place of the conference messagebase file specification IF one of RNETCONF, CONFINFO, or CNAMES environment variables exist or if RNETCONF, CONFINFO, CNAMES.$$$, or CNAMES.@@@ files exist in the current directory. When TXT2MSG parses the messagebase file from the commandline it looks to see if it exists. If the file specified does not exist (presumably because you specified a number in place of a filename) and what you specified was a number, TXT2MSG then looks for RNETCONF, CONFINFO, and CNAMES environments (in that order). It will then expand the search if not found to look for one of the needed files in the current directory. If it finds the file it needs (via environment or in the current directory), TXT2MSG will open the appropriate file and find the messagebase filename based on the number specified. The RNETCONF environment should point to the location and filename of RNet 1.05+'s conference information file (most commonly, RNETCONF). This generic conference specification file is normally generated by PCBCONF.EXE and/or PROCONF.EXE for the 32765 conference support for RNet QWK-packet based echoconferences. Example: SET RNETCONF=D:\RNET\RNETCONF Found on most PCBoard systems, the CONFINFO environment should specify the location and filename of ProDoor 2.9+'s CONFINFO file. TXT2MSG supports both the 255 and the 2040 conference variants. If you are running ProDoor on your system, this environment is already set. Example: SET CONFINFO=D:\PROD\CONFINFO If you have neither the RNETCONF or CONFINFO files to work with you may use the CNAMES environment variable. Since this is an uncommon environment you might wish to set it before and reset it (erase it) after calling TXT2MSG. To use the CNAMES environment variable, set it to point to the location and filename of your PCBoard 14.x CNAMES file. TXT2MSG will search for CNAMES.$$$ and CNAMES.@@@ but do NOT specify an extension in the environment. TXT2MSG does support CNAMES up to 65534 conferences (PCBoard 14.5+). Example: SET CNAMES=D:\PCB\MAIN\CNAMES As long as any one or more of these environment variables are set or one of the files needed is in the current directory, you may use a conference number in place of the messagebase name. If you were to move a conference (say, to a different drive) you would not have to worry about changing your TXT2MSG batch files. Example TXT2MSG commandlines using Conference Number: TXT2MSG 0 c:\gen\blt11 -tALL -fSYSOP -sBulletin_11 -piln (conf 0, blt11 inserted as public message, from Sysop) TXT2MSG 15 -r -tSYSOP "-sUpload list" c:\pcb\main\download.txt (conf 15, R/O to Sysop, download.txt inserted as message) TXT2MSG 99 -r -qc:\main\answer1 c:\main\caller? -SScript_Answers (conf 99, R/O to Sysop, SQ2MSG process answer1 & callers) TXT2MSG 2.20 Page 12 Textfile Control of Message Header See QUICKREF.DOC for a quick reference to these options. One of the most useful features of TXT2MSG is that it allows modification of the message header from specific text within the textfile itself. This allows you (or the person/program creating the textfile) to have control over the header without having to modify the commandline switches. This operation may be disabled with the -n switch (see above) if this is not desired. This operation is semi- automatic in script questionnaire processing and fully automatic in join message processing. Each "keyword" which is accepted by TXT2MSG within the textfile is listed with a description and comments below. Please note that all keywords MUST be flush left, in all capital letters, with the appended colon and space. Anything not matching exactly will be treated as text and inserted into the message body. Accepted keyword lines are NOT inserted into the message text itself unless -n is used. TO: firstname lastname FROM: firstname lastname SUBJECT: subject text here These keywords are pretty much self documenting. Note: The space after the colon is REQUIRED. Examples: "FROM: SYSOP", "SUBJECT: HELLO WORLD!". ECHO: NOECHO: Use ECHO: and NOECHO: to specify if the message should have the Net/Echo flag turned on or off. Most inter-bbs mail packages honor the echo status flag. Specify ECHO: if the message is to be sent to other systems, and NOECHO: if the message is to remain local only. PUBLIC: PRIVATE: PUBLIC: forces the message to be public (readable by all) while PRIVATE: forces the message to be Receiver Only. CC: firstname lastname CC: !d:\dir\filename.lst CC: (carbon copy) names are additional names to send the message to. You can use this to specify a "group" of people to send a given message to. If the first character of a CC: name is an "!" the rest of the line is assumed to be a file specification pointing to a textfile with a list of names. This is useful to send messages to a list of users produced with grep or a similar utility. You may specify a maximum of 100 total CC: names including any names found in !files. All other aspects of the "cc" message will be the same. DATE: mm-dd-yy TIME: hh:mm TXT2MSG 2.20 Page 13 Notes and Limits of Operation TXT2MSG will only process a total of 250 files. This includes all files found via wildcard and @list specifications. The actual number of messages inserted might be more. A single 5000 line textfile with 100 carbon copy names would generate over 5000 [5000/95*100] messages! The number of messages generated by a script questionnaire ANSWERx or ZIPM/CAP joint source file is basically unlimited. The TO, FROM, and SUBJECT fields of a PCBoard 14.x message are limited to 25 characters (each). If you specify anything longer, it will be truncated to 25. Note that if multiple messages are being inserted from the same textfile (a file with over 95 lines of text) the subject length will actually be shorter to make room for the message counter. Textfiles are broken into multiple messages (max 9999) if they exceed 95 lines. You may specify the maximum number of messages which may be created from a single textfile with the -x# switch (0-9). Setting -x0 will enable TXT2MSG to insert unlimited messages from a single source. Any leading blank lines on messages are removed automatically. If more than two blank lines are found sequentially, any in excess of two will be ignored (not imported). Message line lengths over 79 are chopped to 79 characters. Joint (-j) message processing does not strip excessive blank lines, thus, inserting the messages as they appeared origionally. Special and dangerous ASCII characters (such as ^S, ^Q, ^X) are filtered out of the message text and replaced with a period ("."). If you are expecting to do extensive importing of textfiles with problem characters, I recommend using a translation utility such as the PD TRANSLAT.COM to clean-up the textfiles before passing them to TXT2MSG. You may enable/disable the low ASCII filter with the -g (enable) and -a (disable) switches All files (messagebases, textfiles, script questionnaire answerx, and callers logs) are opened using DOS3/NetBIOS SHARE. TXT2MSG will retry DOS3 SHARE locks for 30 seconds and then abort with an errorlevel if it fails. Files without CR (carriage return) such as those generated under the UNIX operating system and files using the Macintosh soft CR are correctly supported. This is useful for non-PC folks to protocol upload messages which TXT2MSG can then process for them. Amiga formatted soft-CR textfiles are also supported. TXT2MSG should correctly detect when it is running under a multi- tasker such as OmniView or DesqView. If it this autodetection fails or if you have a strange multi-tasker, use the -b switch to force TXT2MSG to operate at the BIOS level for screen writes. TXT2MSG will not enter the very first message into a messagebase. If you create a new messagebase and try to use it with TXT2MSG before it has had _any_ messages in it, TXT2MSG will abort with "Message number questionable" and errorlevel==7. Packed messagebases work just fine. You need about 128K free for TXT2MSG to run. At most (when doing script questionnaires and callers log scanning), TXT2MSG requires 93K to operate. DOS requires about another 32K for itself. I can cut down the memory usage at the cost of processing speed. TXT2MSG 2.20 Page 14 Error Messages and ErrorLevels TXT2MSG might abort with any of the following error messages or conditions. You may use "IF ERRORLEVEL..." statements in a batch file to trap these conditions as you see fit. Remember to always check errorlevels in REVERSE order, since the DOS IF ERRORLEVEL==x always assumes equal to or greater than x. ErrorLevel Message/meaning ---------- ------------------------------------------------- 0 Normal Termination (no error) 1 Window, Internal, or Memory allocation error 2 Error accessing @LIST file [filename] 3 Memory allocation error 4 Error accessing Messagebase [filename] {DOS Error} 5 Error accessing file [filename] {DOS Error} 6 Nothing to do! (No text files found) 7 Trashed message or NDX file! [filename] Repack! 8 Unknown command switch [switch] 9 User requested abort! 10 Invalid PCBOARD.SYS file [filename] 11 Error accessing ANSWERx file [filename] 12 Error accessing CALLERx file [filename] 13 Unexpected DOS Error [file] {DOS Error} [filename] refers to the file in question with the problem. {DOS Error} will be replaced with the actual DOS error text such as "Invalid Filename", "No such directory", "Invalid Drive", etc. [switch] shows the commandline switch where TXT2MSG got confused. If an error occurs, the errorlevel itself is also displayed for your reference as "TXT2MSG ERRORLEVEL==xx: {error text}" to STDERR. Contacting the Author I am always interested in hearing your comments, suggestions and bug reports such that they may be handled quickly. If you need to get in contact with me, address all correspondence to "ROBERT VOSTREYS" via: BBS: Faster-Than-Light 404-292-8761 / 404-299-3930 [HST 1440] The Right Place<tm> 404-476-2607 [HST 1440] EchoConference: ILink Sysops, MM-RNet, or ILink conferences. RIME Sysops or Admin conferences. Atlanta AtlSysops or NetLanta conferences. US Mail: Robert Vostreys, FTL Sysop Post Office Box 2315 Stone Mountain, GA 30086-2315 TXT2MSG 2.20 Page 15 The Future of TXT2MSG The future of TXT2MSG will be based on the comments, suggestions, and registration of the Sysops who use it. If you have need for a feature or ability for TXT2MSG, drop me a note! If you use TXT2MSG, you should register it. TXT2MSG is Shareware and inexpensive Shareware at that! With the features and abilities of TXT2MSG, it should be useful to any Sysop who wants to know what is going on his/her system. The latest version of TXT2MSG can always be downloaded from Faster- Than-Light, The Right Place (see above for numbers), Salt Air, and most of the larger public access PCBoard systems. If any registered or beta versions are made available they will be made on both Faster- Than-Light and The Right Place for download via password protection. TXT2MSG 2.xx is a complete rewrite of the previous 1.xx version for testing of new message insertion routines written in TurboC. These new insertion routines, as they are "proved", will soon be used in RNet (a utility for QWK-packet EchoConferencing for PCBoard 14.x). Version 2.10 was upgraded to use the TurboC++ compiler while also adding the conference number and SQ2MSG support. Version 2.20 was an upgrade to allow processing ProDoor ZIPM and PCBoard Capture sourcefiles. This version also revamped the filter, tagline packing, and insertion processing for greater speed. Joint sourcefile insertion of 500 messages (with -z) takes about 50 seconds! If you would like more information on the other utilities which are available or have ideas or needs for additional sysop utilities, I am always ready to listen -- Sysops need all the help and utilities they can get! If you come up with some interesting applications for TXT2MSG I would be interested in seeing what you have done. TXT2MSG has the power and ability to do many fancy things never before thought of which, hopefully, helps take some of the load off the Sysop. Pass on your batch files and ideas so other Sysops may benefit! Above all else, enjoy the wild wonderful world of BBSing! TXT2MSG 2.20 Page 16 PCBoard 14.x Messagebases Message Insertion Logic TXT2MSG is designed to dependably and quickly operate on PCBoard 14.x messagebases. You may safely insert messages concurrently with other nodes/processes as all of the required DOS3 and PCBoard 14.x message insertion rules are fully implemented and extensively tested. Logic behind PCBoard 14.x message insertion routines: Compose and prepare the message in memory. Check valid messagebase header and for non-overflowed NDX. Check for the 'LOCKED' flag/DOS3 lock in the messagebase header. If locked, wait one second and try again (30 retries). Issue DOS3 LOCK on the 'lock' header field for ourselves. Get the high message number and increment by one. Seek to end of file (save (LOF/128) for NDX pointer). Write message header and body to messagebase. Update NDX pointer to message header location (LOF/128). Update messagebase header values, remove DOS3 LOCK. Flush(*) directory/buffers to force DOS3 network update. (*) - you may override the flush operation to force faster message insertion speed in single node operations. This will usually only be of interest if inserting multiple messages since a single message insertion will be flushed automatically when the file is closed. Disabling directory structure flushing in multi-node operations may result in "lost" messages if concurrent entry is encountered -- unlikely, but why take the chance? Thus, the default is to flush. Structure of Messagebases A PCBoard 14.x Messagebase is composed of a fixed field 128 byte record file and accompanying fixed field 4 byte NDX pointer file. The first record of the messagebase is the messagebase header. This record is used to store the low message number (start of NDX file offset), high message number (last inserted message), total number of currently active messages, and number of system callers (in the conference 0 messagebase). The lock field is used to allow multiple nodes concurrent access when entering a message. The 128 byte messagebase header block uses the following 'C' structure: struct { unsigned char high_msg_num[4]; /* MBF single */ unsigned char low_msg_num[4]; /* MBF single */ unsigned char num_messages[4]; /* MBF single */ unsigned char num_callers[4]; /* MBF single */ unsigned char lock[6]; /* DOS3 LOCK area */ unsigned char unused[128-22]; } pcb14base_header; MBF (MicroSoft Binary Format) numbers are the native format of BASCOM 1.0 which was used as the base for the PCBoard BBS software for versions previous to 14.5. Failure to properly support the BASCOM MBF format will result in corrupted messagebases. TXT2MSG 2.20 Page 17 Each message within a messagebase is composed of a message header block and one or more message body blocks. The header is used to store the message number, status (security), to, from, date, and other such fields. The layout is shown in the following 'C' structure: struct { unsigned char stat_flag; /* security status byte... ' ' = public, unread '-' = public, read '*' = r/o, unread '+' = r/o, read '~' = comment, unread '`' = comment, read '!' = group pwd, all '#' = group pwd, unread '$' = group pwd, read '%' = sender pwd, unread '^' = sender pwd, read */ unsigned long msg_number; /* MBF single */ unsigned long ref_number; /* MBF single */ unsigned char block_count; /* number of body blocks+1 */ unsigned char msg_date[8]; /* MM-DD-YY */ unsigned char msg_time[5]; /* HH:MM */ unsigned char msg_to[25]; /* left, padded with spaces */ unsigned char reply_info[10]; /* "has reply" information */ unsigned char msg_from[25]; /* left, padded with spaces */ unsigned char msg_subject[25]; /* left, padded with spaces */ unsigned char msg_password[12]; /* left, padded with spaces */ unsigned char active_flag; /* (225)=good, (226)=killed */ unsigned char echo_flag; /* 'E' = echo, ' ' = local */ unsigned char reserved[5]; /* used by e-mail packages */ unsigned char host_tag_flag; /* '*' = has host tagline */ } pcb14msg_header; The text body itself is composed of (block_count - 1) blocks of 128 bytes. Each 'line' of text is terminated with a (227) and does not contain any CRLF's. A standardized maximum of 99 lines is used to maintain compatibility with older messagebase utilities and echo-mail packages. The NDX file associated with a PCBoard 14.x messagebase is a file of fixed length (4 byte) records. Each record is a MBF single pointing to a record number within the messagebase. This is a pointer to the message header record within the messagebase file. Record 1 in the NDX will usually have a MBF value of 2 since the first messagebase block is used by the messagebase header and thus the first message actually starts at block 2. The NDX record numbers (position) are based as an offset from the low_message_number. Record 1 in the NDX points to the low_message_number header offset x 128 bytes. If a message has been deleted (and thus might no longer be within the messagebase file) the NDX value is a negative pointer value. For example, Say you have a messagebase with a low_message_number of 1000. To look up the position of message 1015 you would read NDX record 16 (message_desired - low_msg_number + 1). This MBF would yield the record number (NDX MBF value * 128 byte offset) within the messagebase where message 1015's header block is located.