Beijing Paradise BBS Backup

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

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / 1STDEAL.ZIP / 1ST-112.ZIP / SYSTEM.ZIP / ADVANCED.DOC < prev next >

Wrap

Text File | 1994-09-01 | 174.6 KB | 4,929 lines

┌──────────────────────────────────────────────────────────────────┐ │ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ▄██ │ │ │ │ ██ ▄▄▄▄▄▄ ▄▄▄▄▄▄ │ │ │ │ ██ ██▀▀▀▀ ▀▀██▀▀ │ │ │ │ ██ ▀▀▀▀██ ██ │ │ │ │ ██ ██████ ██ │ │ │ │ │ │ │ │ 1stReader for DOS │ │ │ │ The Advanced User's Guide │ │ │ │ │ │ │ │ │ │ │ │ Entire work │ │ │ │ Copyright 1994 by Mark Herring │ │ │ │ All Rights Reserved │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Sparkware │ │ │ │ Post Office Box 386 │ │ │ │ Hendersonville, Tennessee 37077 │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────────┘ NOTICE EXCEPT FOR THE EXPRESS WARRANTY SET FORTH ABOVE, SPARKWARE GRANTS NO OTHER WARRANTIES, EXPRESSED OR IMPLIED, BY STATUE OR OTHERWISE, REGARDING THE DISK, PROGRAMS AND RELATED MATERIALS, THEIR FITNESS FOR ANY PURPOSE, THEIR QUALITY, THEIR MERCHANTABILITY, OR OTHERWISE. THE LIABILITY OF SPARKWARE UNDER THE WARRANTY SET FORTH ABOVE SHALL BE LIMITED TO THE AMOUNT PAID BY THE CUSTOMER FOR THE PRODUCT. IN NO EVENT SHALL SPARKWARE BE LIABLE FOR ANY SPECIAL, CONSEQUENTIAL, OR OTHER DAMAGES FOR BREACH OF WARRANTY. SPARKWARE RESERVES THE RIGHT TO MAKE ANY CHANGES TO THESE PROGRAMS, DOCUMENTATION AND CUSTOMER SUPPORT PLANS AT ANY TIME WITHOUT PRIOR NOTICE. THIS SOFTWARE PROGRAM IS A PROPRIETY PRODUCT OF SPARKWARE AND IS PROTECTED BY COPYRIGHTS AND INTERNATIONAL TREATIES. YOU MUST TREAT THIS SOFTWARE LIKE ANY OTHER COPYRIGHTED MATERIAL, EXCEPT THAT YOU MAY MAKE AN ARCHIVAL COPY OF THE SOFTWARE FOR EACH COPY THAT IS LICENSED TO YOU. YOU MAY DISTRIBUTE THE SOFTWARE TO OTHERS SO LONG AS (A) THE 1ST.KEY OR QMAIL4.KEY FILE IS NOT DISTRIBUTED, (B) THE SOFTWARE IS DISTRIBUTED UNMODIFIED. YOU MAY NOT DECOMPILE, DISASSEMBLE, REVERSE ENGINEER, COPY, TRANSFER, OR OTHERWISE USE OR MODIFY THIS SOFTWARE EXCEPT AS STATED HEREIN. SPARKWARE GRANTS YOU THE RIGHT TO USE THIS SOFTWARE FOR TRIAL PERIOD NOT TO EXCEED THIRTY (30) DAYS. USE AFTER THIRTY DAYS REQUIRES REGISTRATION AS DOCUMENTED IN THIS MANUAL. 1stReader Entire work Copyright 1993 by Mark Herring All Rights Reserved Sparkware Post Office Box 386 Hendersonville, Tennessee 37077-0386 (615) 230-8822 24 hour support bulletin board system (615) 230-MAIL Office (10-12, 1-5 central time weekdays) TABLE OF CONTENTS DOS command line switches................................ 3 /CALL............................................ 3 /DAY............................................. 3 /DEBUG........................................... 3 /MAXLINES........................................ 4 /MPU401.......................................... 5 /NON............................................. 5 /NOSCAN.......................................... 5 /ONLYREPS........................................ 5 /QWK............................................. 6 /REP............................................. 6 /SETUP........................................... 6 /SHOWDEL......................................... 6 /SILENT.......................................... 7 /SLOW............................................ 7 /SWAP............................................ 7 /TIME............................................ 7 /XON............................................. 8 Creating 1stReader LOAD files............................ 9 1stReader Support Files.................................. 10 .BAT (or .BTM) files............................. 11 $$MAIL.BAT....................................... 11 $$REPLY.BAT...................................... 12 $$CALL.BAT....................................... 12 $$CHECK.BAT...................................... 12 $$TERM.BAT....................................... 12 $$BATCH.BAT...................................... 13 $$START.BAT and $$END.BAT........................ 13 $$REPLIES.BAT.................................... 13 $$FILER.BAT...................................... 13 $$EXIT.BAT....................................... 13 $$SPELL.BAT...................................... 14 $$CNAMES.BAT..................................... 14 $$Fxx.BAT........................................ 14 $$SHELL.BAT...................................... 14 .CMD and .LST files.............................. 15 $$1ST.CMD........................................ 15 $$ppff.CMD....................................... 16 Multiple EDITORS and LIST programs....................... 16 SHELL modifiers.......................................... 17 /API............................................. 17 /CGA, /EGA and /VGA.............................. 18 /CLS and /NOCLS.................................. 18 /CURSOR_ON and /CURSOR_OFF....................... 18 /DISPLAY......................................... 18 /EXPORT.......................................... 19 /FONT............................................ 19 /IN.............................................. 19 /OUT............................................. 19 /LIST............................................ 20 /MACRO........................................... 20 /MSGTEXT......................................... 20 /NS and /SS...................................... 21 /NULL and /NONULL................................ 21 /PAUSE........................................... 21 /SCRNSAVE........................................ 21 KEYBOARD.$$$..................................... 21 MESSAGE.$$$...................................... 22 LIST.$$$......................................... 22 <confname>.TMP files............................. 22 .CMD controls.................................... 23 Features................................................. 23 FEATURE=CALL..................................... 23 FEATURE=MAIL..................................... 23 FEATURE=MANAGER.................................. 24 FEATURE=SETUP.................................... 24 FEATURE=SNAPSHOT................................. 24 FEATURE=TAGLINES................................. 24 FEATURE=TERMINAL................................. 24 MultiMedia Extensions (MME).............................. 25 .MME files....................................... 26 Special files.................................... 27 $$ALARM.......................................... 27 $$CHKPRT......................................... 27 $$EXIT........................................... 27 $$H-<help_recnum>................................ 27 $$HELP........................................... 27 $$INTRO.......................................... 27 \1ST\BBS\<confnum>............................... 27 NEWS............................................. 28 NEWFILES......................................... 28 SERVICES......................................... 28 LEAVING.......................................... 28 $$TRANS.......................................... 28 The 1stReader Applications Program Interface (API)....... 29 1stReader Integer API table...................... 29 1stReader Long Integer API table................. 34 1stReader String API table....................... 35 @Variables supported by 1stReader................ 38 1stReader script language................................ 40 ABORT............................................ 40 API.............................................. 40 AUTOEXIT......................................... 40 BREAK............................................ 41 CALL............................................. 41 CAPTURE.......................................... 41 CHECKTIME........................................ 41 CLS.............................................. 41 COMMENT.......................................... 41 COUNT............................................ 41 DEBUG............................................ 42 DISCONNECT....................................... 42 DOWNLOAD......................................... 42 EDIT............................................. 42 EXIT............................................. 42 FLAG............................................. 43 FOUND=........................................... 43 GOSUB............................................ 43 GOTO............................................. 43 HANGUP........................................... 43 HELP............................................. 43 IF............................................... 44 KEYSTROKE=....................................... 44 KILL............................................. 44 LIST............................................. 44 LOCATE........................................... 44 LOCKLINE......................................... 45 LOOKFOR.......................................... 45 MME.............................................. 45 NEWFILES......................................... 45 NEW_PASSWORD..................................... 46 PAUSE............................................ 46 PLAY............................................. 46 PROMPT........................................... 46 REQ_FILE......................................... 46 REQ_SETFILE...................................... 46 REQ_NEXT......................................... 46 REQ_DONE......................................... 47 REQ_CONF......................................... 47 REQ_SET.......................................... 47 REPLIES.......................................... 47 RETURN........................................... 47 RUN.............................................. 47 SET_FLAG......................................... 47 SET_PASSWORD..................................... 48 SHOW............................................. 48 SWITCH........................................... 48 TERMINAL......................................... 49 TERSE............................................ 49 TRANSMIT......................................... 49 TRANSMIT......................................... 49 TIMEOUT.......................................... 50 UPLOAD........................................... 50 WAITFOR.......................................... 50 WEEKDAY.......................................... 50 Special @variables............................... 51 Special characters............................... 52 Hints and Tips........................................... 53 Support for .BIN and .B1N files.................. 53 The WELCOME file................................. 53 Using KEYBOARD.$$$ from the internal editor...... 54 Pre-Print and Post-Print strings................. 54 Printer definition............................... 54 Create your OWN help files....................... 54 1stReader is network ready....................... 55 GO.ASC, GO.ANS, GO.BIN, GO.B1N................... 55 Automatic DOORWAY ON and DOORWAY OFF modes....... 56 "Header" files................................... 56 Auto sensing dialog boxes........................ 57 "Ok" and "Cancel" buttons........................ 57 Attention John Hancock fans!..................... 57 Specialized conference files..................... 58 Support for DOOR.ID.............................. 58 Downloading files................................ 58 Longer signatures................................ 58 Multiple signatures.............................. 59 Support for the "1ST" file....................... 59 Automatic SuperShell............................. 59 Nonstandard serial ports......................... 60 New commands supported in DOOR.ID................ 60 LIST is restricted............................... 60 Robocomm-named packets supported................. 61 QMAIL4 is assumed................................ 61 Three button mice users.......................... 61 Using SPACE BAR and SHIFT+ENTER.................. 61 Protect those 'questionable' taglines............ 62 'Hotkey' your .CMD and .LST entries.............. 62 Entry fields are accessible...................... 62 Sysops can use Qmail Door in DOS using 1stReader. 63 Control characters in .LST files and KEYBOARD.$$$ 63 $$DIAL.SCR supported............................. 64 Addition bulletin board systems supported........ 64 Carriage returns in the modem init string........ 64 SERVICES.NEW..................................... 64 Clear all entry fields with one keystroke........ 65 QSZ supports 'crash-recovery'.................... 65 Assign different prefixes to telephone numbers... 65 Access interrupts from DOS command line functions 66 NAPLPS support is now available.................. 67 Make temporary changes to your 1stReader setup... 67 Tagline support from the terminal section........ 67 The 'CONFIRMATION' field......................... 68 The .COPY command................................ 68 1stReader automatically aborts a script.......... 68 Picklist notices................................. 68 Scroll quickly through large messages............ 69 Restricting some .CMD functions.................. 69 Locate a file inside your system's PATH statement 69 Move files automatically into the BBS directory.. 69 Disconnect immediately after an upload/download.. 70 Modify the 1stReader API after a DOS shell....... 70 Usenet message headers........................... 70 Alias signatures................................. 71 The virtual keyboard............................. 71 The EXTRA FEATURE button......................... 71 Display files directly from a .CMD file.......... 72 '$<macro>' now available in ANSI files........... 72 Sensing color attributes......................... 73 The NEWS.LST file................................ 73 The ATTACHED.LST file............................ 73 Save some disk space............................. 73 The INSTALL module............................... 74 Creating offline help for bulletin boards........ 74 Please Note ----------- Except for the express warranty set forth, Sparkware grants no other warranties, expressed or implied, by statue or otherwise, regarding the disk, programs and related materials, their fitness for any purpose, their quality, their merchantability, or otherwise. The liability of Sparkware under the warranty set forth above shall be limited to the amount paid by the customer for the product. In no event shall Sparkware be liable for any special, consequential, or other damages for breach of warranty. Sparkware reserves the right to make any changes to these programs, documentation and customer support plans at any time without prior notice. This software program is a propriety product of Sparkware and is protected by copyrights and international treaties. You must treat this software like any other copyrighted material, except that you may make an archival copy of the software for each copy that is licensed to you. You may distribute the software to others so long as: A) The 1ST.KEY or QMAIL4.KEY file(s) is not distributed. B) The software is distributed unmodified. You may not decompile, disassemble, reverse engineer, copy, transfer or otherwise use or modify this software except as stated herein. Sparkware grants you the right to use this software for a trial period not to exceed THIRTY (30) days. Use after thirty days requires registration. Qmail 1stReader Entire work Copyright 1993 by Mark Herring All Rights Reserved Sparkware Post Office Box 386 Hendersonville, Tennessee 37077-0386 (615) 230-8822 24 hour support bulletin board system (615) 230-MAIL Office (10-12, 1-5 central time weekdays) Page 1 This manual is designed to help the advanced 1stReader access all of the features found in the 1stReader offline mail system. If you are new to 1stReader or offline mail readers in general, we strongly recommend that you do not use this guide until you are familiar with 1stReader. 1stReader was designed to be easily understood by the novice user. However, there are plenty of features available for the advanced power user "under the hood". The design philosophy behind the 1stReader system was to provide an interface for novice users that they could easily understand and use. The power user features are hidden underneath this interface and you have the ability to access them. Remember, you do NOT need this guide in order to use 1stReader. However, you can change the way 1stReader operates by following the tips and suggestions in this guide. Page 2 DOS command line switches ------------------------- 1stReader supports a number of DOS command line switches you can use at startup. These switches, when placed after the DOS command 1ST.EXE, allow you to change how 1stReader is configured and operates. You can 'stack' as many command line switches as you wish. You can also create files that contain the DOS command line switches that can be easily loaded. /CALL: <list of systems> -----------------------. Tells 1stReader to immediately begin calling <list of systems> from the DOS command prompt. This switch lets you call bulletin board systems directly from a batch file instead of navigating through the 1stReader user interface. Example: 1ST /CALL: SPARKY EXECNET CHANNEL1 /DAY: <days to call> -------------------- The DAY switch lets you tell 1stReader which days of the week to call a bulletin board system. This switch is designed for users who want 1stReader call and receive new messages from inside a batch file that runs nightly on your system. Great for sysops who use 1stReader to make their nightly mail runs. The days of the week are represented by numbers. Sunday=1, Monday=2, Tuesday=3, Wednesday=4, Thursday=5, Friday=6 and Saturday=7. This example shows how to setup 1stReader so it will only call these systems on Sunday, Tuesday and Thursday: Example: 1ST /DAY: 135 /CALL: system1 system2 system3 /DEBUG ------ This command line switch will create various 'debugging' files that can tell you how 1stReader is operating. Depending on what you are doing within the reader, up to three debugging files can be created in your 1stReader system subdirectory. These files are: Page 3 1ST.DBG This file contains information about your system and how it was operating while executing 1stReader. It will contain the following data on each line in the file: Free RAM available Free string space available Free stack space available Next file handle number to allocate Time of execution Description of operation SCRIPTS.DBG This file contains a capture of the scripts executed by 1stReader when you call a bulletin board system. All @variables will be translated in this file so it provides an accurate record of how scripts were executed by 1stReader. SERIAL.DBG This file contains characters received by 1stReader from your modem when calling a bulletin board system. /MAXLINES: <maximum number of lines per message> ------------------------------------------------ The internal editor inside 1stReader lets you create replies of up to 200 lines each. If you decide to use an external editor then the size of your replies can be as large as you wish. 1stReader 'breaks' your replies at 99 lines per message. This is due to the limits imposed by some bulletin board software and older offline mail readers still in use today. However, you can adjust the size of the reply by using the /MAXLINES command line switch. Example: 1ST /MAXLINES: 200 This command would cause 1stReader to break long replies at every 200 lines. If you wish to break a long message at the end of a paragraph you can insert ".PG" after the line you wish to break. ".PG" is not included in your reply when transmitted to the bulletin board system. Page 4 /MPU401 ------- If you have a MPU401-compatible MIDI device connected to your computer then this command will make 1stReader output .MID files to your MIDI device rather than using a sound card. Note that your MIDI interface must be connected to port 330h. /NON ---- 1stReader uses "RTS" checking to determine when your modem is ready to send characters to the remote system. You can disable ALL checking by using the /NON switch. Example: 1ST /NON /NOSCAN ------- If you have turned on the multimedia switch inside 1stReader then anytime you display a text file the reader will try to locate a .MME, .MID, .CMF or .VOC file that matches the filename being displayed. The "/NOSCAN" switch stops 1stReader from scanning for these sound files when displaying text files. /ONLYREPS: <list of systems> ---------------------------- This DOS command line switch works just like the /CALL: switch except that it will only call systems in the <list of systems> that have message replies waiting to transmit. Example: 1ST /ONLYREPS: SPARKY EXECNET CHANNEL1 If the mail sites SPARKY and CHANNEL1 have replies waiting to be transmitted back to these systems, 1stReader will call these systems. If EXECNET does not have replies waiting to be transmitted then the reader will skip calling EXECNET. Page 5 /QWK: <file extension> ---------------------- Since 1stReader is designed to work with QWK formatted mail packets, by default it looks for mail packets using the "Q*" file extension. You can override this extension by using the /QWK command line switch. Example: 1ST /QWK: OPX Why would you want to change the file extension? Later in this guide we cover two batch files named "$$INTRO.BAT" and "$$EXIT.BAT". Programmers can use these files to create programs that convert other non-QWK mail packets to and from the QWK format. The /QWK command line switch lets them tell 1stReader which type of mail packet to scan for in the list of packets on file. /REP: <file extension> ---------------------- This command line switch works just like the /QWK switch except that it lets you change the default extension for mail reply packets. "REP" is the extension used for QWK mail packets, but by using this switch you can change the extension to any value desired. Example: 1ST /REP: TMP /SETUP: <filespec> ------------------ You can load a different 1stReader setup file (.SET) from the DOS command line using this switch. Example: 1ST /SETUP: NETWORK.SET /SHOWDEL -------- If this command line switch is used then whenever you delete a reply in 1stReader the message will remain in the REPLIES conference until you close the mail packet. Normally, when you delete a reply in the REPLIES conference, 1stReader will immediately remove it from the list of replies. This switch keeps the message in the REPLIES conference so you can undelete it later in the same session. Example: 1ST /SHOWDEL Page 6 /SILENT ------- Sometimes it might be nice if you could turn off the noises and beeps 1stReader makes. You could either be at the office or doing a late night mail run at 3:00 am. In either case, use this command line switch to make 1stReader totally silent - no matter how you have configured the reader. Example: 1ST /SILENT /SLOW: <milliseconds> --------------------- 1stReader pauses five milliseconds for each ANSI position statement it receives while displaying color files and messages. If you have a faster computer this pause might not be long enough. You can use this DOS command line switch to vary the number of milliseconds to pause. Example: 1ST /SLOW: 15 /SWAP: <filespec> ----------------- 1stReader's SuperShell system swaps the memory being used into either EMS memory (if enough is available) or to a disk file. Normally, this disk file is named $$1ST.RAM and is located in your 1stReader system subdirectory. If you use this command line switch then you can point 1stReader to another filename if you wish. If you have a large RAM disk available it would be nice to point the swap file into the RAM disk for faster speed. 1stReader overwrites <filespec>. /TIME: <military format> ------------------------ This command line switch works with the /CALL and /ONLYREPS switches so you can set the time you wish to start calling the <list of systems>. Remember, you MUST use military format if you wish to call systems starting after 12:59 pm (1:00 pm is translated into 13:00 hours). Examples: 1ST /CALL: SPARKY EXECNET CHANNEL1 /TIME: 20:00 1ST /ONLYREPS: SPARKY EXECNET CHANNEL 1 /TIME: 20:00 Page 7 /XON ---- 1stReader uses the "RTS" method of checking to determine when your modem is ready to receive characters. This switch is just like the /NON switch except that instead of turning off ALL forms of line checking, it forces 1stReader to use XON/XOFF checking (required by older modems). Example: 1ST /XON Page 8 Creating 1stReader LOAD files ----------------------------- You can create text files that contain multiple DOS command line switches and easily load them from the DOS command prompt with 1stReader. Simply use a text editor to create a file (you may give it any name you wish) and then tell the reader to load it from the DOS command prompt. 1stReader will read the switches from the file just like you entered them from the DOS command line prompt. For example, if you wanted to create a LOAD file that would always allocate 2,000 messages per conference and 10,000 lines per message (using EMS memory) and loads the BIGSERF.FNT file, you could create a file named BIGEMS in a text editor. The file would contain this entry: /EMS: 2000:10000 /FONT: BIGSERIF.FNT You could then tell 1stReader to load the BIGEMS file by using the DOS command: 1ST @BIGEMS The "@" tells 1stReader to look for the file "BIGEMS" and if found use the DOS command line arguments it contains to start up 1stReader. There is one special filename reserved for this feature. If you create a file named "SWITCHES.1ST" and you simply start 1stReader by typing "1ST" from the DOS command line, then 1stReader will look for SWITCHES.1ST. If SWITCHES.1ST is found then the reader will read it for the DOS command line switches. Page 9 1stReader Support Files ----------------------- There are files you can place inside your 1stReader system subdirectory that can help you change the way 1stReader operates. Before you continue, we need to explain the file directory structure used by 1stReader. You can, of course, change this layout in the SETUP section inside 1stReader, but by default this subdirectory tree structure is used: \1ST\ 1stReader system subdirectory \1ST\SCRIPTS\ Script files location \1ST\PACKETS\ Mail packets location \1ST\FILES\ Files you download \1ST\PROGRAMS\ Programs area \1ST\FOLDERS\ Folders area \1ST\MME\ Location of sound files \1ST\WORK\ Temporary mail work area \1ST\REP-WORK\ Temporary replies work area \1ST\SERVICES\ Temporary services work area \1ST\BBS\QWK-ID\ The BBS subdirectories The two locations we are concerned about right now are the System subdirectory (we'll call it SYSTEM) and the BBS subdirectories (we'll call it BBS). The BBS subdirectories are created underneath the \1ST\BBS area. Each system you call with 1stReader has a unique BBS subdirectory underneath this area. It is here that all bulletins, archived file lists, script files and other items unique to each system is stored. So, when we refer to the BBS subdirectory, we are actually referring to the unique subdirectory for a particular bulletin board system, not \1ST\BBS\ itself. The files described below can be located in either the SYSTEM, SCRIPTS or BBS subdirectory. 1stReader will always look in the BBS subdirectory for the file first. If the file is not found then 1stReader will check for the file in the SCRIPTS subdirectory. Finally, if the file is not found in that subdirectory the reader checks the SYSTEM subdirectory. The major exception to this rule is when 1stReader is at the OPENING SCREEN menu. Since you haven't selected a system from the menu 1stReader will skip checking the BBS subdirectory first. If the file is found the BBS subdirectory then that file will only work when you have selected that system from the opening screen menu. Otherwise, if the file is not found in the BBS subdirectory but it is found elsewhere that file is available at ALL times. Page 10 There are four different types of support file. They are .BAT, .CMD, .LST and .MME files. .BAT (or .BTM) files -------------------- You can "by pass" the built-in features found in 1stReader with your own personal favorites if you wish. Of course, you can use your own internal file LIST or EDITOR programs by entering their DOS commands in SETUP's EDITOR section. But you can replace many of the internal systems found in 1stReader by using batch files. 1stReader will follow the normal BBS/SCRIPTS/SYSTEM search method to locate these files unless specifically mentioned in the descriptions below. Also, if you have turned on 4DOS support within 1stReader remember that 1st will be looking for .BTM files instead. 1stReader never actually executes the batch file you create. Instead, it reads the contents of the batch file and creates a temporary batch file to execute named $$EXEC.BAT. When 1stReader is reading the contents of your batch file it can substitute values from the Applications Program Interface (API). The API is defined later in this guide. All you need to remember for now is that you can substitute API variables in your batch files as needed. $$MAIL.BAT ---------- If you wish to use your favorite telecommunications software to call bulletin board systems you can replace the internal module in 1stReader by creating a $$MAIL.BAT file. This file passes along to the application the QWK-ID of the system you have selected in the '%1' parameter in the batch file. There are two communication systems that are designed to transfer mail packets to and from offline mail systems. These two programs are ICOM from Liberation Enterprises and ROBOCOMM from Parsons Technologies. If you wish to use either of these systems with 1stReader you need to create a $$MAIL.BAT file that will CHDIR into the proper subdirectory and then execute the program. Inside the batch file you need to use these commands to run either program: For ICOM use the command: ICOM /RUN:%1 For ROBOCOMM use the command: ROBOCOMM /A%1 /R Page 11 The QWK-ID for the system is passed in the '%1' parameter so you need to make sure you have a job (for ICOM) or an agenda (for ROBOCOMM) prepared to call the bulletin board system. $$REPLY.BAT ----------- This batch file works just like $$MAIL.BAT except that it is used if you wish to transmit replies back to the bulletin board system without picking up new mail. If this batch file is found and you have selected the "Get Mail" button and you also have replies on file, you will be asked if you wish to only transmit replies to the system. $$CALL.BAT ---------- This batch file works just like $$MAIL.BAT except that it is used to call the bulletin board and place the user in an interactive terminal mode. You can interface 1stReader with your favorite terminal program (ProComm, Telix, etc) by using this batch file. $$CHECK.BAT ----------- This batch file lets 1stReader test archives for any potential viruses that might be included in programs you download from other bulletin board systems. Unfortunately, it is a fact these days that people create programs that try to destroy your data. In response to this threat, companies have created programs to detect these virus programs before they can infect your computer. 1stReader can automatically test for viruses by using the $$CHECK.BAT batch file. Only one parameter is passed to this batch file in the '%1' parameter, the location of the subdirectory that contains the files to be tested. $$CHECK.BAT should call your virus checking software passing the location of this subdirectory to the program. $$CHECK.BAT is automatically executed after you unpack an archive downloaded from a bulletin board system. $$TERM.BAT ---------- You can use your favorite telecommunications program with 1stReader. The $$TERM.BAT file can call a communications program when you select the 'Terminal' button from the 'Opening Menu' screen. Simply use this batch file to call your telecom program. Page 12 $$BATCH.BAT ----------- If you call more than one system in a batch mode (either by using the /CALL, /ONLYREPS or by tagging multiple systems from the list of systems, when finished calling these systems, 1stReader will execute $$BATCH.BAT if the batch file exists. $$START.BAT and $$END.BAT ------------------------- These batch files are executed automatically by 1stReader when you begin and exit 1stReader. You can use these batch files to perform any functions you wish. $$REPLIES.BAT ------------- This batch is executed by 1stReader as soon as a reply mail packet is unbundled. The idea behind this batch file is to allow you to process the reply mail packet in any way you wish before you read the mail packet. The same parameters used in the $$INTRO.BAT file are passed to this batch file from 1stReader. $$FILER.BAT ----------- This batch file will execute whenever you click on the "Files" button in the "Read messages" screen. It's designed so you can process the NEWFILES.DAT file any way you wish. The NEWFILES.DAT file contains a list of newly uploaded files on a bulletin board system. Only one parameter is passed in '%1' to the batch file, - the full name of the NEWFILES.DAT filespec. $$EXIT.BAT ---------- $$EXIT.BAT works just like $$INTRO.BAT, except that instead of being a "preprocessor" for the mail packet it is a "post- processor". This batch file is called after you have exited the mail packet but before the contents of the work subdirectories are erased. Any files found in the REP-WORK subdirectory are included in the .REP reply mail packet. Three parameters are passed to the $$EXIT.BAT file. These parameters are: %1 Name of the QWK-ID for the system %2 Path to the work subdirectory %3 Path to the replies subdirectory Page 13 $$SPELL.BAT ----------- If this batch file exists then 1stReader will ask you if you wish to perform a spelling check on your reply just before you save the message. The batch file uses the '%1' parameter to store the filename being passed to the batch file. This is a great way to interface spelling checkers like SHARESPELL with 1stReader. Example (assumes ShareSpell is in the \SSPELL subdirectory): @ECHO OFF CD \SSPELL SS %1 $$CNAMES.BAT ------------ This batch file works when a user clicks on the "Conf List" button in the 'Join a conference' screen. The idea behind this batch is to allow 1stReader to shell to a program that the user can query for conference information. Some systems have over 5,000 conferences so a database isn't such a bad idea! $$Fxx.BAT --------- These batch files (where 'xx' is a value from 1 to 10) correspond to the function keys on your keyboard. If you press the [SHIFT]+F10 key, for example, then 1stReader will execute $$F10.BAT (if found). This feature lets you interface programs that you wish to have executed from one keystroke rather than inserting them into the [F7] command files. $$SHELL.BAT ----------- Whenever you manage files 1stReader will take you into the file manager. If you wish to use your own file managing system create a file named $$SHELL.BAT. This batch file should call your file manager. 1stReader passes the location of the subdirectory to be managed in the '%1' parameter. Page 14 .CMD and .LST files ------------------- .CMD (Command) and .LST (pick list) files let you integrate other programs into 1stReader. .CMD files are text files that contain program descriptions and program commands in a pulldown menu. You can call up the .CMD file(s) by pressing the [F7] key on your keyboard. .LST files let you pass on keyboard macros into 1stReader using a pulldown menu too. Press the [F8] key on your keyboard to call up .LST files. Please note that .LST files are available for certain keyboard prompts only. The format of a .CMD file is: TITLE=<title description> Description #1,DOS command #1 Description #2,DOS command #2 Description #3,DOS command #3 The format of a .LST file is: TITLE=<title description> Description #1,Keyboard macro #1 Description #2,Keyboard macro #2 Description #3,Keyboard macro #3 You may have up to 100 commands per file. You can also "chain" other .CMD or .LST files by using the syntax: Desc,FILE=filespec.CMD or Desc,FILE=filespec.LST To create a .CMD file press ALT+F7. or press ALT+F8 to create a .LST file. This will place you in the editor where you can create the file. If you are in 'novice mode' then you will know that a picklist is available because 1stReader displays "[F8]=Picklist" on your screen. $$1ST.CMD --------- Usually, you will be interested in $$1ST.CMD. If this file exists then 1stReader will load the file and display the menu of functions in the middle of your screen. You can then select which program you wish to execute and 1stReader will SHELL and execute the DOS command. Page 15 $$ppff.CMD ---------- Almost all of the keyboard input fields are identified in 1stReader by page and field number. If $$ppff.CMD exists (where "pp" is the page number and "ff" is the field number) then 1stReader will display THIS file instead of $$1ST.CMD, if $$ppff.CMD exists. You can create custom .CMD files for specific keyboard input fields by pressing the ALT+F7 key at anytime. Multiple EDITORS and LIST programs ---------------------------------- If you wish to use external editors or list programs you can create EDITORS.CMD and LIST.CMD files that contain the descriptions and commands needed to execute them. For example, EDITORS.CMD might contain: TITLE=External Editors QEdit,Q %1 %2 TED,TED %1 DOS 6.00 Editor,EDIT %1 Instead of entering the DOS command for an editor you would use the entry "EDITORS.CMD" instead. Then, when you are about to SHELL to DOS to execute the external editor 1stReader will ask you to select an editor from this list. '%1' gets translated into the ORIGINAL filespec and '%2' gets translated into the REPLY filespec. The same technique works for LIST.CMD except that you would only use '%1' to be replaced by the name of the file to list. 1stReader supports up to 100 external editors and file listers using this technique. You can create these files by going into Setup's "EDITOR" section then entering LIST.CMD and/or EDITORS.CMD in the appropriate entry field. Then press ALT+F7 to create the file. Page 16 SHELL modifiers --------------- 1stReader lets you control HOW it shells to a program using "shell modifiers". These switches let you control whether the current screen is saved or cleared before you shell to DOS, if you wish to PAUSE before returning back to 1stReader, etc. Shell modifiers can be used in any DOS command executed from within 1stReader. Usually, this means DOS commands issued from .CMD menus. You can add SHELL modifiers directly into batch files by adding this line into the batch file itself: :1ST shell modifier1 shell modifer2 ... /API: <filespec> ---------------- The /API modifier tells 1stReader to create a file named <filespec> that contains the entire contents of the 1stReader API (Applications Program Interface). This modifier lets third-party programmers read the current environment used by 1stReader so they may take advantage of them for their own programs. The 1stReader API is defined later in this guide. Here is the format for the file created by this modifier: Version number INTEGER Number of INTEGER API variables INTEGER (IMax) Number of LONG API variables INTEGER (LMax) Number of DEFAULT switches INTEGER (SwMax) Number of STRING API variables INTEGER (SMax) API(0)-API(IMax) INTEGER values INTEGER*(IMax+1) API&(0)-API&(LMax) LONG values LONG*(LMax+1) Switch(1)-Switch(SwMax) INTEGER*(SwMax) Next comes the API$() lookup table. This is a table that is SMax+1 entries long. Each API$() value has an offset and length value in this table. Example: API$(0) OFFSET:LENGTH API$(1) OFFSET:LENGTH You would read the offset to the variable you wish to read and then SEEK to this position in the file and read LENGTH number of bytes to access the string variable. Page 17 /CGA, /EGA and /VGA ------------------- These modifiers are to be placed on DOS commands when the shelled program requires that the system is connected to either a CGA, EGA or VGA monitor. For example, let's say you wanted to run a program that displayed a GIF file. You can restrict use of the program to systems that have VGA color monitors by using this command: Display a GIF file,NANOGIF /VGA A system equipped with a monochrome, CGA or EGA monitor would not execute this command. /CLS and /NOCLS --------------- The /CLS modifier tells 1stReader to erase the screen and display the DOS command before execution. /NOCLS tells 1stReader to leave the current screen intact and shell to the program, providing a "seamless" screen. When the application returns control back to 1stReader the current screen is always restored. /CURSOR_ON and /CURSOR_OFF -------------------------- These two modifiers control the cursor while shelling from 1stReader. If you wish to turn the DOS cursor on while shelling to a program use /CURSOR_ON. /CURSOR_OFF will turn the cursor off. Note that 1stReader always restores the cursor to the same condition after a DOS shell has taken place. /DISPLAY: <text> ---------------- This modifier can be used to display a dialog box while shelling to a program from 1stReader. Any text following this switch is displayed inside a dialog box on the screen as 1stReader shells to DOS. Page 18 /EXPORT: <filespec> ------------------- This modifier lets you export the current message into <filespec> so you can shell to another program that reads <filespec> for input. This is a powerful feature that lets third-party software link into 1stReader and offer you capabilities above those found in the reader. The format of the exported message file is: 1stReader release number Name of the bulletin board Location Telephone number Sysop's name Qmail Door serial number PCBoard message status (225=Active, 226=Deleted) Conference number Message number Message status flag Date Time To From Subject Reference number Number of lines in text body ...Message text... <filespec> is automatically deleted by 1stReader when you return from the DOS command. /FONT ----- This modifier reloads a video font that was loaded by 1stReader using the /FONT: <filespec> DOS switch. Sometimes, when you execute a program from within 1stReader, the program can reset the video font. This modifier tells 1stReader to reload the current font from disk after executing the DOS command. /IN: <filespec1> /OUT: <filespec2> ----------------------------------- These two modifiers work together...there is no point in using /IN without also using /OUT. They provide you with a "flexible" API setup for third-party programmers. This concept takes a bit of explaining. Remember the /API modifier described earlier? That modifier creates a file of every entry contained in the 1stReader API. As a third-party programmer, you might only be interested in using a few of the entries, but maybe not every single one. Page 19 1stReader uses <filespec1> as a "template" in order to create <filespec2>. The template can contain any information your application requires in any order you wish. @variables defined in <filespec1> are translated and written to <filespec2>. For example: <filespec1> <filespec2> ----------------------- ------------------------ My App 1.01 My App 1.01 @API$(0) C:\1ST\1ST.SET @API$(5) C:\1ST\ @API$(36),@DAY@ MARK HERRING,Wed As you can see, 1stReader "reads" <filespec1> and translates it into <filespec2>. Any "literals" that 1stReader cannot translate get passed "as is". <filespec1> is never deleted by 1stReader. <filespec2> is erased after returning from the DOS command. /LIST: <filespec> After completing the DOS shell, 1stReader will look for <filespec> and if found will list the file on the screen. Unlike LIST.$$$, <filespec> is not deleted by 1stReader. /MACRO: <text> -------------- You can 'stuff' text into 1stReader's macro buffer immediately after returning from a DOS command using this modifier. /MSGTEXT: <filespec> -------------------- This modifier works just like /EXPORT except that <filespec> only contains the text of the message and nothing else. /EXPORT creates a file that includes the TO, FROM, SUBJECT and other message header info. /MSGTEXT will work great for those users who want to use UUENCODE to rebuild an encoded file received via a Usenet message, among many other uses. Page 20 /NS and /SS ----------- The /NS (No Supershell) modifier tells 1stReader that if SuperShell has been turned ON by the user then it should not invoke a SuperShell during this DOS command. /SS (SuperShell) works in the opposite manner. It tells 1stReader to invoke SuperShell even if the user has not turned SuperShell on. /NULL and /NONULL ----------------- "/NULL" tells 1stReader to add ">NUL" to the DOS command line so that BIOS output will not echo to the screen. "/NONULL" does the exact opposite - it will remove any ">NUL" added to a DOS command. This lets you shell to programs that use BIOS output and lets you see the output. /PAUSE ------ This modifier tells 1stReader to pause and wait for a keystroke before returning control back to the user. /SCRNSAVE: <filespec> --------------------- This modifier saves the current screen into <filespec> as a BINARY file. KEYBOARD.$$$ ------------ This isn't a DOS command modifier but rather a file that can contain information to be passed back to 1stReader. If you shell to DOS from a keyboard input field, and the application you execute creates a KEYBOARD.$$$ file in the current subdirectory, this file is read by 1stReader and its contents entered into the current keyboard entry field. This is an excellent way for third-party applications (like address books) to pass information back to 1stReader. Page 21 MESSAGE.$$$ ----------- This too isn't a DOS command modifier. Instead, it is a file that contains a full message that is to be saved by 1stReader into the mail reply packet. The idea behind supporting this file is to allow other programs that might be shelled to from 1stReader to save messages automatically, without having to go through the same steps 1stReader performs to save the message. Here is the format used for MESSAGE.$$$: Line 1: Conference number to save message Line 2: If a public message this line is blank, otherwise the message is a personal msg. Line 3: Message TO field (address to whom) Line 4: Message SUBJECT field Line 5: Tagline to pass to 1stReader Message text follows on line #6 and below. 1stReader always checks for MESSAGE.$$$ after a DOS shell and deletes the file after saving the message. LIST.$$$ 1stReader will check for this file after a DOS shell. If the file is found then LIST.$$$ will be displayed by 1stReader's internal LIST module and then be deleted. <confname>.TMP files -------------------- The template files let you create 'forms' that are automatically inserted into the editor when a user ENTERS a new message. The form can be a standard bug report form or any form you wish. The idea behind this feature is to give the user an idea of what they should enter in a new message. 1stReader looks for <confname>.TMP using the current conference's name (up to the first eight characters). For example, if the user was in the 'TEST' conference and entered a new message, 1stReader would look for TEST.TMP and if found it would load it into the editor. If TEST.TMP is not found then 1stReader looks for $$1ST.TMP instead. If the internal editor is used 1stReader also toggles the editor into an 'overstrike' mode. Page 22 .CMD controls ------------- Some programs that can be installed into a .CMD menu might only operated after you have selected a bulletin board system from the opening menu. They might not work properly because the user might be located at the opening menu or in the terminal mode. If you wish to prevent a program from appearing in the menu when a BBS has not been selected, add "<BBS>" to the DOS command for that option. This tells 1stReader to skip loading this command into the menu screen if a BBS has not yet been selected. Example: Forward msg,FORWARD /IN:FORWARD.IN /OUT:FORWARD.$$$ <BBS> Features -------- You can also access some of the 1stReader internal routines from a .CMD menu. In order to access the routines 1stReader checks to make sure you are not already using the routines. If you are using the routines then these commands will not appear in your CMD menu at that time. For example, if you are using the file manager and press the [F7] to call up $$1ST.CMD and try to manage a subdirectory from the list of commands, the FEATURE=MANAGER command will not be displayed to you. FEATURE=CALL ------------ Lets you call the currently selected bulletin board system from the .CMD menu. 1stReader will place you in the terminal mode and call the system logging you onto the BBS. Example: Call this system,FEATURE=CALL FEATURE=MAIL ------------ This feature works just like the CALL feature except that it will make a full mail run to the selected bulletin board system. Example: Make a mail run,FEATURE=MAIL Page 23 FEATURE=MANAGER directory [<ABS>] --------------------------------- Lets you access the 1stReader file manager. If directory is entered on the same line then 1stReader will manage directory. If "<ABS>" is included on the command line then the reader will not ask you for a directory path before entering the file manager. Example: Manage Downloads,FEATURE=MANAGER @API$(2) <ABS> FEATURE=SETUP ------------- Lets you access the 1stReader setup section (the same section used by the SETUP button on the Opening Menu). Example: 1stReader setup,FEATURE=SETUP FEATURE=SNAPSHOT <filespec> --------------------------- This feature lets you capture the current screen into <filespec> as a .BIN file. If you do not user a filespec then 1ST-SNAP.BIN is used by default. Example: Save screen,FEATURE=SNAPSHOT TEST.BIN FEATURE=TAGLINES ---------------- You can manage your 1stReader taglines from anywhere within 1stReader using this feature. Example: Manage taglines,FEATURE=TAGLINES FEATURE=TERMINAL SCRIPT: filename PHONE: phone BAUD: baud This feature lets you access the 1stReader terminal section. If you have created a $$TERM.BAT file then the reader will use this batch file to call up your terminal program (1stReader will ignore the SCRIPT and PHONE parameters if used). You can also pass on to the terminal section the telephone number of the system you wish to dial (and the baud rate to use) as well as the name of a script file to execute. Example: Call Sparky's,FEATURE=TERMINAL PHONE: 230-8822 BAUD: 19200 Page 24 MultiMedia Extensions (MME) --------------------------- If you have a Sound Blaster (or compatible) sound card installed in your computer system then 1stReader can play .VOC (sampled data), .CMF (FM music), .MID (midi) and .MME files through your sound card. All you need to do is to turn the "MultiMedia" switch ON in the SETUP/SWITCHES section Please Note: It is not recommended that you turn on the MultiMedia switch while running 1stReader under Windows or Desqview. If you do not have a sound card installed in your computer or you do not wish to use MME within 1stReader you should turn the multimedia switch OFF. If you start 1stReader using the /SILENT DOS command switch then 1stReader will not play multimedia files for that session. Whenever you are in the 1stReader file manager you can select a .VOC, .MID or .CMF file and 1stReader will play the file through your sound card. However, when the reader displays a text or ANSI file it will also look for a file that matches the filename being displayed (but not the extension) and if found, that file will be played through the sound card. It is better to give an example of how this works... Whenever you unpack a QWK mail packet in 1stReader the reader always looks to display a WELCOME file included in the mail packet. If you have MME turned on then 1stReader looks for these files in the this order: \1ST\BBS\<QWK-ID>\WELCOME.MME \1ST\BBS\<QWK-ID>\WELCOME.MID \1ST\BBS\<QWK-ID>\WELCOME.CMF \1ST\BBS\<QWK-ID>\WELCOME.VOC \1ST\MME\WELCOME.MME \1ST\MME\WELCOME.MID \1ST\MME\WELCOME.CMF \1ST\MME\WELCOME.VOC \1ST\WELCOME.MME \1ST\WELCOME.MID \1ST\WELCOME.CMF \1ST\WELCOME.VOC 1stReader will stop the search with the first filename it locates. If the file is found 1stReader will play the file through your sound card. This feature lets you tie sound files together with text files that are already displayed by 1stReader. Page 25 Note that if the file you are displaying already includes an extension then 1stReader strips the extension from the filename and performs the same search. For example, if the filename was WELCOME.TXT then 1stReader strips the ".TXT" from the filename and begins the search. This feature allows sysops to include .VOC files that are automatically played whenever a mail packet from their system is unpacked, or a bulletin is displayed....anything! .MME files ---------- The ".MME" file extension is used by 1stReader to link other .VOC or .CMF files together into one sound 'stream'. A .MME file is a text file that points to other .MID, .CMF and/or .VOC files that are to be played in order by 1stReader. An example of a .MME file might be: APPLAUSE.VOC WELCOME.VOC STARTREK.CMF If this file was called WELCOME.MME then when the WELCOME file is displayed by 1stReader it will read WELCOME.MME and then play, in order, APPLAUSE.VOC, WELCOME.VOC and STARTREK.CMF. These three files can be located in the BBS subdirectory, inside the \1ST\MME subdirectory or in \1ST itself. Page 26 Special files ------------- 1stReader has reserved filenames for special features used throughout the reader. As always, 1stReader looks for these files in the BBS subdirectory first, then the \1ST\MME subdirectory and finally in the \1ST subdirectory. These files can use the .MME, .MID, .CMF or .VOC extensions depending upon your needs. $$ALARM ------- Played whenever 1stReader connects to a bulletin board system or finishes a file transfer with the bulletin board. $$CHKPRT -------- This file is played whenever you attempt to print text on your printer but your printer is not ready to print (either not connected, not turned ON or the printer is not ONLINE). $$EXIT ------ Played when you exit 1stReader and return to DOS. $$H-<help_recnum> $$HELP ----------------- $$HELP is played after the online help facility is used AND the user has not turned on the "Advanced Features" switch. 1stReader will look to see if $$H-<help_recnum> is on file and if found, will play it before it plays $$HELP. <help_recnum> is the record number for that particular help function. $$INTRO ------- Played at the start of 1stReader before you arrive the opening menu. \1ST\BBS\<confnum> ------------------ This file lets a sysop tie a particular MME file to a conference on their system. It is played whenever you join <confnum> in 1stReader. Page 27 NEWS NEWFILES SERVICES LEAVING -------- These four MME files are played after a mail packet has been unpacked but before arriving at the "Read messages" menu. NEWS is played if a news bulletin is in the mail packet. NEWFILES is played if a list of new files has been included. SERVICES is played if services were included in the mail packet. And finally, LEAVING is played when the user selects the "QUIT" button from the "Read messages" menu. $$TRANS ------- This file is played after a file transfer has been completed. If $$TRANS.* is not on file then 1stReader will use $$ALARM instead. Page 28 The 1stReader Applications Program Interface (API) -------------------------------------------------- The 1stReader API is designed to let third-party programmers have access to the internal information used by 1stReader. Power users will also find the API of interest. That's because we have provided you with special functions that let you access the API from with batch files and 1stReader itself. These functions are: @API(xx) Accesses the integer API entries. "xx" can be between 0 and 275. @API&(xx) Accesses the long integer API entries. "xx" can be between 0 and 10. @API$(xx) Accesses the API text entries. "xx" can be between 0 and 165. @SWITCH(xx) Accesses the setup switches. "xx" can be between 1 and 36 The actual API values are listed below. It is important to remember that 1stReader supports these (and ALL) @variable definitions in filespecs, text entries and descriptions. They come in VERY handy with the .CMD and .LST files. Here is a list of the 1stReader API entries. If you have specific questions about any of these entries please leave us a message on our customer support system at (615) 230-8822. 1stReader Integer API table ------------------------------------------------------------- 1: Text file (1STTEXT) file handle 2: Segment address of 1STTEXT (if loaded) 3: SCREENS file handle 4: Length of the DialDir entry 5: Phone Book file handle 6: Number of screens on file 7: Screen buffer segment address 8: Current screen number 9: Reader screen buffer 10: Does a mouse exist? 11: Mouse cursor state 12: Are we in ScrnEdit? 13: Last keyboard field entered 14: The user cannot access help from this location 15: Total number of systems on file 16: Current system record number 17: Are we inside QmSetup? 18: Are we inside ShowFile? 19: Qmail Door serial number Page 29 20: Is the user a sysop? 21: Maximum number of lines per message 22: Number of conferences on file 23: Number of login names 24: Number of active conferences 25: File handle for MESSAGES.DAT 26: Current conference number 27: Current MIDI velocity value 28: Is music enabled for this display? 29: Is this display an ANSI ART display? 30: Last conference joined 31: Number of messages in conference 32: Current message number in conference 33: Number of lines in current message 34: Is this message an ANSI message? 35: Last message number loaded 36: Current line number in message 37: File handle for the replies file 38: A DosService call was made 39: Normal message text color 40: Quoted message text color 41: Search message text color 42: Current message file buffer 43: Was a bookmark read? 44: Is this message addressed to you? 45: Message type (1=Public, 2=Private, 3=Comment, 4=Sender, 5=Group) 46: Is the message read (1=Yes, 0=No) 47: Number of mouse traps in effect 48: Number of files downloaded in TERMINAL mode 49: Are we in batch mode using /CALL or /ONLYREPS? 50: File handle for zippy file search 51: Are we in color mode? 52: How many active keywords are there in the scan? 53: Is this message a USENET message? 54: Was F10 pressed? (The action key) 55: Number of names in TWIT file 56: Reload the TWIT file? 57: Last conference joined since Zippy 58: File handle for folders 59: Are we in the initial IPL for the reader? 60: Stacked OPTION command (used when CTRL is pressed) 61: Are we currently inside QmListFile? 62: Was a packet found on startup in the work subdirectory 63: Highest conference number 64: Last message line displayed at top in internal quoter 65: Number of messages tagged for archiving 66: If set then the message is not redisplayed 67: Number of files found in the mail packet 68: Direction of the QmScrnEdit field movement 69: File number for services.dat 70: Number of services on file 71: File handle number for the .QWK packet Page 30 72: Number of new bulletins found 73: Packet number selected 74: Set for QmListConf 75: Display this message in ANSI 76: Button pressed in MouseRange() 77: Mouse button selected in MouseRange() 78: Number of messages in this packet 79: Have we initialized the modem? 80: Force carrier on modem? 81: The comm ABORT switch 82: Recycle to next call in queue 83: Echo received characters from comm port on screen? 84: Number of LOOK variables defined 85: Timeout value for comm routines 86: Is autoZmodem downloads enabled? 87: Are we in terminal mode? 88: Reload the current message? 89: Are we in the terminal program 90: Buffer position for comm routines 91: Was JH called? 92: IRQ number 93: Base address 94: Reading without a packet on file? 95: Flow control parameter 96: Is the comm port open? 97: FIFO buffer size 98: Are we now reading a packet? 99: Are we inside a script? 100: Is this message routed from PostLink? 101: Is this message routed from Usenet? 102: Is AutoExit in terminal enabled? 103: Are we inside the DOS SHELL (F6) handler? 104: Was /QWK: used? 105: Was /REP: used? 106: Are we inside the function menu routine? 107: Maximum number of messages per conference 108: Use "UN:" on this message? 109: Was this mail packet mangled by EZ-Reader? 110: Mixed case entry flag 111: Fido style taglines flag 112: Have mail headers been swapped out? 113: Current field number in screen 114: Are we inside the editor subroutine? 115: CONTROLTYPE = ADD found in DOOR.ID 116: Should ADD/DROP buttons be displayed? 117: Are we inside the DOOR setup routine? 118: Strip @X codes? 119: International date format (0=USA, 1=EUROPE, 2=JAPAN) 120: Is a message loaded? 121: Are we inside the QmListConfs routine? 122: Is Doorway mode turned on? 123: Was doorway mode turned on while executing a script? 124: Maximum number of lines in a reply 125: Were services included in this packet? Page 31 126: Was KEYBOARD.$$$ read? 127: HELP.DAT handle 128: Help record file 129: If set then use 4DOS BTM files 130: Maximum possible number of messages allowed 131: Was HELP just called? 132: Last archive packet used 133: Number of Replace$() variables defined 134: Archiver used to unpack mail packet 135: Are we ordering 1stReader? 136: Was the last unpack operation successful? 137: Stop the pause in QmFileDisplay? 138: Size of 16550 FIFO stack (modified by 1st) 139: Are we inside help? 140: Is the user a Qmail Door owner? 141: Are we inside the internal editor? 142: Number of times TIMEOUT was hit in script 143: Number of times for TIMEOUT to hit before ABORTing script 144: Capture buffer file number 145: Reload the message display screen? 146: Current serial port 147: Connect flag from $$DIAL.SCR 148: Is this a Blue Wave packet? 149: Is the user "NEW USER"? 150: 0=TERMINAL, 1=CALL, 2=MAIL, 3=REPLY 151: Reserved 152: Reserved 153: Reserved 154: Is /MLIST used on the command line? 155: Fido tags turned on by @FIDO@? 156: Do not use $$DIAL.SCR 157: Reset the line input routine? 158: Use the disability switch? 159: Is DesqView active? 160: Screen buffer address 161: Did the last ANSI string contain a MUSIC string? 162: Number of lines in display for ANSIART message 163: Number of lines in display for ANSI file display 164: No Blink active? 165: Top of screen to protect in QmSetWindow 166: Left margin of screen to protect in QmSetWindow 167: Bottom of screen to protect in QmSetWindow 168: Right margin of screen to protect in QmSetWindow 169: Maximum number of lines in screen 170: Is this message larger than 200 lines? 171: Was this message already displayed as ANSI? 172: Last ROW used in virtual keyboard 173: Last COLUMN used in virtual keyboard 174: Can .VOC files be played by this system? 175: Can .MID and .CMF files be played by this system? 176: Abort all MME files in queue? 177: Always display messages in ANSI 178: Number of messages to be stored in EMS Page 32 179: EMS handle for messages stored in array 180: Size of bookmark segment 181: Bookmark segment address 182: Noblink ANSI message 183: Number of lines in the display 184: Number of lines to protect in message display 185: Number of conferences in the first data segment 186: Number of conferences in the second data segment 187: Was ESC pressed to terminate the list of msgs 188: EMS handle for QmText (if loaded high) 189: Are we reading from the database? 190: Has we asked if this message should be displayed as ANSI 191: Display mail packet names in packet screen. 192: Tearline in a message 193: Redial attempts 194: If set then on loss of carrier abort a redial. 195: Alias number used when saving a message 196: If true then NEWFILES.EXE is supported 197: Is the /SILENT switch used 198: Maximum length of UCode$() 199: If ON then do not act on $<command> in ANSI display 200: Draw the dialing box in terminal mode? 201: Are we in a DOS shell? 202: Number of ESC sequences in the current msg 203: DOS success flag 204: If set then do not perform a hangup during redials 205: Number of script files in the current CHAIN 206: Reserved 207: Reserved 208: If true we are calling for MAIL 209: Maximum number of taglines allowed 210: If TRUE then initialize API$(130-134) 211: If /SHOWDEL switch is turned ON 212: Number of messages to move forward to get to the next message 213: Are we in the QmComm module? 214: Are we in the file manager module? 215: Are we editing a big file? 216: Is DEBUG turned on? 217: Is local ECHO turned on? 218: Sound Blaster support using CTVDSK? 219: Sound Blaster support using CMFDRV? 220: Dialing prefix number to use 221: If set then scan for MME files in subdirs 222: Were MME files found in API$(5) 223: Were MME files found in API$(28) 224: Were MME files found in API$(111) 225: Were MME files found in BBS directory? 226: File handle number for SERIAL.DBG 227: True if /ONLYREPS was used 228: Are we managing taglines? 229: Are we inside QmSetup()? Page 33 230: Number of milliseconds to pause during an ANSI position 231: Have we already tried to init the Sound Blaster? 232: Have we loaded a font? 233: Last interrupt number serviced 234: Returns the value of AL after an interrupt 235: Address of the API$() data segment 236: Address of the API$() data offset 237: Address of the API&() data segment 238: Address of the API&() data offset 239: Address of the CFG data segment 240: Address of the CFG data offset 241: Address of the DIALDIR data segment 242: Address of the DIALDIR data offset 243: Address of the Index() data segment 244: Address of the Index() data offset 245: Address of the CONF data segment 246: Address of the CONF data offset 247: Register pair AX returned after the interrupt 248: Register pair BX returned after the interrupt 249: Register pair CX returned after the interrupt 250: Register pair DX returned after the interrupt 251: Register pair SI returned after the interrupt 252: Register pair DI returned after the interrupt 253: Register pair DS returned after the interrupt 254: Register pair ES returned after the interrupt 255: Register pair SS returned after the interrupt 256: Register pair SP returned after the interrupt 257: Register Flags returned after the interrupt 258: Maximum number of lines per message 259: EMS handle for lines pointers stored in array 260: Scrollback segment address 261: Scrollback buffer size 262: Pointer into scrollback buffer 263: True if we are calling to order keyfile 264: Disable Desqview time slice 265: Modem redial delay 266: Enclosed file was found in the current message 1stReader Long Integer API table ------------------------------------------------------------- 0: Serial number 1: Total number of records in MESSAGES.DAT 2: Total number of records in REPLY file 3: Beginning position of the bookmark inside the .QWK 4: Current baud rate 5: Last time a character was received in comm channel 6: Current message record number in MESSAGES.DAT 7: Total number of records in FOLDER 8: Highest message number in the base 9: CONNECT baud rate Page 34 1stReader String API table ------------------------------------------------------------- 1: Path to the packets subdirectory 2: Path to the download files subdirectory 3: Path to the programs files subdirectory 4: Path to the opening subdirectory 5: Path to the system subdirectory 6: Path to the reply packets subdirectory 7: Mail packet extension (Q*) 8: Reply packet extension (REP) 9: Mail packet filespec (No path) 10: Name of PACKET ID 11: Name of BBS 12: Mail packet name 13: Reply packet name 14: Path to BBS subdirectory 15: Path to the work subdirectory 16: Path to the replies subdirectory 17: Path to the services subdirectory 18: Path to the folders subdirectory 19: Last import file subdirectory 20: TWIT list filespec 21: Last folder filespec (no .FOL extension) 22: Current conference name 23: Name of the SERVICES.LST file 24: Last conference name 25: Release date 26: Suffix of the ID keyfile 27: Path to the .SET file 28: Path to the startup subdirectory 29: Path to the SYSTEM files subdirectory 30: Name of system 31: Telephone number 32: Sysop's name 33: Door ID 34: Date of packet 35: Time of packet 36: User's name 37: Second scan name 38: Third scan name 39: Name of system's phone book 40: Welcome filespec 41: BBS news filespec 42: Goodbye filespec 43: Quote name 44: Name of the bookmark file 45: CTRL sequences for OPTIONS 46: ALT translation string 47: Telephone number being dialed 48: Mail packet transfer protocol letter (defaults to Zmodem) 49: Quote character 50: Full path to MESSAGES.DAT 51: Full path to the REPLY .MSG file Page 35 52: Scan entry #1 53: Scan entry #2 54: Scan entry #3 55: Scan entry #4 56: PostLink routing site 57: Last directory viewed in reader menu 58: Path to the subdirectory being viewed in program manager 59: Filespec currently selected in the program manager 60: Usenet Path 61: From 62: Newsgroups 63: Subject 64: Message ID 65: Date 66: References 67: Sender 68: Organization 69: Domain 70: Reply-To 71: To 72: Last color change issued by ANSI 73: Name of the USENET.ID file 74: User name in upper/lower case 75: User name in Usenet format 76: Comm port base address in HEX 77: String passed to program from DOS shell 78: String value present when QmEditor executed 79: Control name for door ADD/DROP 80: Name of the service file (no path or extension) 81: Last DOS command selected in QmMenu 82: Conference name (dots removed) 83: Current contents of the keyboard input buffer 84: Current conference name 85: Message number 86: Date 87: Time 88: Status 89: To 90: From 91: Subject 92: Refer 93: Reader 94: Serial number 95: Tagline 96: Actual PCB message header 97: Last color saved by @X00 98: Last highlight ANSI switch used 99: Fido Address (if any) 100: Current conference number 101: File request filespec 102: User's first name 103: Doorway ON string 104: Doorway OFF string Page 36 105: PC Pursuit access number 106: PC Pursuit user ID 107: PC Pursuit password 108: PC Pursuit city ID 109: List of systems to call using /CALL or tagging 110: Linked script file 111: MME subdirectory 112: Log capture filespec 113: Name of reader for OEMS 114: Tagline entry 115: Date seperator 116: Temporary help file to pass 117: Path to the database subdirectory 118: Start time to call systems (using /CALL:) 119: Data to be replaced with "Ω" in the DOS shell 120: System IDs called in batch mode 121: Serial number of reader 122: Attached filename 123: Original script name 124: Last telephone number dialed 125: Swap filespec 126: Script file to execute BEFORE dialing phone number 127: Script file to execute AFTER dialing phone number 128: Modem dialing prefix #1 129: Attached filename on PCBoard 130: Full name of the $$1ST.LST file 131: Full name of the $$1ST.CMD file 132: Full name of the $$pp.LST file 133: Full name of the $$pp.CMD file 134: Name of conference .LST file 135: Name of conference .CMD file 136: Name of the .CFG file 137: Modem dialing prefix #2 138: Font filename 139: Command line used to start 1stReader 140: Last DOS command executed by 1stReader 141: Used if message is a return receipt from PCBoard Page 37 @Variables supported by 1stReader --------------------------------- This is a list of all @variables supported by 1stReader. You may use these variables in any file, script, .CMD, or .LST file. Variable Description ------------------- --------------------------------- @CLREOL@ Clears display to the end of line @DATE@ Current system date @SYSDATE@ Current system date @TIME@ Current system time @SYSTIME@ Current system time @TO@ Message "TO" field @FROM@ Message "FROM" field @SUBJECT@ Message "SUBJECT" field @GOODNAME@ Your name in upper/lower case @USENETNAME@ Your name in Usenet "." format @EDIT@ DOS editor command @LIST@ DOS list command @ORIGINAL@ Original message filespec @REPLY@ Reply message filespec @BBSID@ Qmail Door packet ID @MEMORY@ Free memory available in 1st @VERSION@ 1stReader release edition @PHONE@ Telephone of the BBS @CONF@ Current conference name @CONF2@ Current conference (underscored) @FILEDIR@ files subdirectory @FIRST@ First name (from BBS login field) @COMPORT@ Serial port entry in SETUP/COMM @DAY@ Today's name (Mon, Tue, etc.) @POS:nn@ Tabs to column "nn" (one per line only) @API$(xxx) This variable reads the 1stReader API string table and is replaced with the current value. @API(xxx) This variable reads the 1stReader API integer table and is replaced with the current value. @API&(xxx) This variable reads the 1stReader API long integer table and is replaced with the current value. Page 38 @SWITCH(xx) This variable reads the 1stReader switches table. If the switch is turned ON then a "-1" is returned. Otherwise, a "0" is returned. See the "SWITCH" script function for a complete list of switch numbers. @REPLACE(xx) At times 1stReader will pass arguments to batch files using '%1', '%2' or '%3'. You can call these replacement variables directly if you wish. These @variables are available if you are reading a message from a 'Usenet' conference: @U-PATH@ 'Path' line in message @U-FROM@ 'From' line in message @U-NEWSGROUPS@ 'Newsgroups' line in message @U-SUBJECT@ 'Subject' line in message @U-MESSAGE-ID@ 'Message-ID' line in message @U-DATE@ 'Date' line in message @U-REFERENCES@ 'References' line in message @U-SENDER@ 'Sender' line in message @U-ORGANIZATION@ 'Organization' line in message @U-DOMAIN@ 'Domain' line in message @U-REPLY-TO@ 'Reply-To' line in message 1stReader will also substitute any DOS environment variables by enclosing them in "%" characters. For example, %PATH% would be replaced with the DOS path from your environment. Page 39 1stReader script language ------------------------- Script commands are in FULL CAPITAL letters. Required values are enclosed in <arrows> and optional values are enclosed in [brackets]. Of course, do not include these characters in the actual command. Sometimes command parameters will be enclosed by quotation marks. If present in the command description then these quotation marks are required in the actual command line. @API$(xxx)="value" Type: command @API&(xxx)=value @API(xxx)=value @SWITCH(xxx)=value These commands let the scripts modify the 1stReader API. See the API definition list to determine the correct value for "xxx" for each variable. ABORT <value> Type: command The ABORT command works with the TIMEOUT command to determine how many carriage returns must be sent (without a response back from the BBS) before 1stReader declares the script to be 'locked up'. If the number of carriage returns transmitted exceed <value> then the script is aborted by 1stReader. API <value> Type: function The API function reads the integer API table for entry <value>. Some API values are flags that can be tested for ON or OFF conditions. This function lets you conduct those tests. AUTOEXIT <on|off> Type: command The AUTOEXIT command controls how 1stReader will exit out of the TERMINAL mode. If AUTOEXIT ON is set then if carrier is lost while the user is in terminal mode, 1stReader will exit the script. AUTOEXIT OFF causes 1stReader to stay in the terminal mode until the user presses ALT+X to exit. Page 40 BREAK [value] Type: command Sends a TRUE break signal to the host computer. [value] is the number of 18ths of a second to hold the break signal. If [value] is omitted then 1stReader uses 18 as a default. CALL <script file> [label] Type: command The CALL script command lets you call another script file and then when the script exits control returns back to the original script that was running. This command helps modularize script functions without having a maze of GOTOs to get back to the original script. You can specify a label to start execution of <script file> by adding it to the CALL command. CAPTURE <on|off> Type: command The CAPTURE command will open a file named <BBSID>.CAP in the 1stReader system subdirectory. This file will capture the screens displayed by 1stReader so you can review it later. If the capture file is left open when a script terminates then 1stReader will close the capture file automatically. CHECKTIME(hh:mm,hh:mm) Type: function CHECKTIME accepts two times (in military format). The first "hh:mm" represents the START time to check and the last "hh:mm" represents the END time to check. If the current time IS BETWEEN these two values then this function is set to TRUE. Otherwise, the function returns FALSE. CLS Type: command The CLS command will clear the screen and set the cursor to the top of the screen. COMMENT "string" Type: command This command lets you display a comment on the screen in the area setup below the LOCKLINE value. COUNT <qwk|rep> Type: command The COUNT command increments the number of QWK mail packets received and the number of REP mail packets uploaded to the bulletin board system. Page 41 DEBUG Type: function The DEBUG function lets you test to see if DEBUG SCRIPTS (switch #18) has been turned on by the user. You could use the SWITCH function to test for this condition but the DEBUG function provides better script readability. DISCONNECT <baud rate> Type: command Some systems you may call have high speed and low speed lines. You might try to connect to a node capable of 38400 baud but since all high speed nodes are busy you end up connect to a 2400 baud node. Obviously, if you are using 1stReader in the middle of the night on automatic you do not want to make a full mail run at the lower speed. The DISCONNECT <baud rate> command tells 1stReader that if you connect at speeds lower than <baud rate> to disconnect from the system. Example: IF DISCONNECT 9600 THEN GOTO LOGOFF If you connected to the system at less than 9600 baud then control is sent to the LOGOFF label. DOWNLOAD <filespec> Type: command The DOWNLOAD command will download <filespec> using the Zmodem file transfer protocol. EDIT <filespec> Type: command The EDIT command lets you edit <filespec> from inside a script. If <filespec> does not exist it will be created for you. EXIT Type: command The EXIT command will immediately disconnect the BBS and exit the script. You should use it if you wish to exit a script without waiting for the BBS to disconnect from you. Page 42 FLAG <filespec> <byte_num> Type: function This script function is intended to use <filespec> as a set of external 'semaphores' for scripts. You can use this function to check the value of <byte_num> in <filespec>. If the value of <byte num> is ZERO then FLAG returns a FALSE condition, otherwise it returns TRUE. You can use this function in a IF THEN statement to branch depending if a semaphore is turned on or not. FOUND=<value> Type: function The FOUND function returns which prompt string was found using a WAITFOR command. If a WAITFOR command uses multiple target prompts (example: WAITFOR "Yes|No") the FOUND= function will return a value of "1" if "Yes" was found or "2" if "No" was found. GOSUB <label> Type: command The GOSUB command lets you call a subroutine in your script that is located at <label>. You can nest up to 20 GOSUB calls in one script. GOTO <label> Type: command The GOTO command transfers flow of the script to <label>. A label always starts with a colon and is one word long on a line by itself. Up to 100 labels may be defined in a script. HANGUP Type: command The HANGUP command will immediately terminate the connection to the remote BBS. HELP <number> Type: command The HELP command displays the online help available from inside 1stReader's HELP files. See the list of HELP functions for more information. Page 43 IF ...... Type: statement You may use the IF statement to test for various conditions and execute a command based on the results. The syntax of the IF statement is: IF <function> THEN <command> You may use any <function> defined in the script language and combine it with any <command> as the object of the IF statement. 1stReader also provides for a NOT modifier so you can test if a particular function is not true. The NOT statement must come before the <function>. The syntax of the IF statement using a NOT modifier is: IF NOT <function> <command> KEYSTROKE=<value> Type: function This function returns the ASCII value of the keystroke given to the last PAUSE command. If a lower case character was pressed then 1stReader automatically converts it to upper case for you. Example: PAUSE IF KEYSTROKE=13 .... ' Enter was pressed IF KEYSTROKE=27 .... ' ESC key was pressed IF KEYSTROKE=32 .... ' Space bar pressed KILL <filespec> Type: command The KILL command will erase <filespec> from the drive. LIST <filespec> Type: command The LIST command will display a text file using the internal file lister. The difference between the SHOW and LIST commands is that the SHOW command loads the text into memory and displays it using the help screen while LIST will display any size file using the internal list routines. LOCATE <row>,<column> Type: command The LOCATE command locates the cursor at <row>,<column> on the screen. You can use this command to position the cursor just before a PRINT statement to position text on the screen. Page 44 LOCKLINE <row> <attribute> Type: command The LOCKLINE command lets you allocate a section of the screen for COMMENTs from the script file. <row> is the row number on the screen (rows 1 through 24) to "lock" so comments may be printed below it. In other words, <row> is the last row that information received from the BBS is displayed. Immediately after <row> a line is drawn by 1stReader. <attribute> is the color attribute value that is used to paint the remaining rows underneath the solid line. LOOKFOR "prompt string" "transmit string" Type: command The LOOKFOR command is used to scan incoming data for "prompt string" and if found, transmit "transmit string". If you wish to remove a LOOKFOR command that is already in place use the syntax LOOKFOR "prompt string" "". The null string in place of the "transmit string" tells 1stReader to remove the LOOKFOR command. Remember, the "prompt string" must match the original string. Up to 10 LOOKFORs may be active at any one time. You can also use the LOOKFOR statement "@HANGUP@" to have a script automatically terminated if a particular string is found. Example: LOOKFOR "search string" "@HANGUP@" MME <filespec> Type: command The MME command lets your scripts play .VOC, .CMF or .MME files through a Sound Blaster (or compatible) card. The Multimedia switch must be turned on in SETUP/SWITCHES in order to play <filespec>. NEWFILES <ON|OFF> Type: command The NEWFILES command tells 1stReader that the bulletin board system can use the NEWFILES.EXE program to display the list of new files. Otherwise, new files lists are displayed internally by the reader. Page 45 NEW_PASSWORD Type: command NEW_PASSWORD will generate a new password your user account that is eight characters of random letters. This command is used together with the SET_PASSWORD command to create a new password your bulletin board login account. Some systems (PCBoard 15.0 for example) can force you to change your password at different times. These two script commands let 1stReader changes your password for you automatically. The new password is assigned to the @PASSWORD@ variable. PAUSE [seconds] Type: command The PAUSE command will pause execution of the script for [seconds]. If you do not use a [seconds] argument then the script will pause until you press any key. PLAY "string" Type: command This command will play the ANSI music enclosed in "string" through the PC's internal speaker (if the MUSIC switch has been turned ON). PROMPT <text> Type: command This script command will display a boxed prompt for two seconds in the middle of the screen containing <text>. REQ_FILE <filespec> <conference> Type: command The REQ_FILE command will let a script add a file request to the current file request list. <filespec> is the name of the file to download and <conference> is the conference number where the file can be found. REQ_SETFILE <filespec> Type: command This command tells 1stReader to read <filespec> to find files requested from the NEWFILES.EXE program. REQ_NEXT Type: command REQ_NEXT reads <filespec> (used by REQ_SETFILE) to find the next file request in <filespec>. You can find out if a file was found by REQ_NEXT by using the REQ_DONE function. Page 46 REQ_DONE Type: function This function is set to TRUE if 1stReader cannot locate a file request in the file set by REQ_SETFILE. Use this function in a IF-THEN statement to stop reading the file. REQ_CONF Type: function This function is set to the conference number that contains the next file to download. If REQ_CONF is set to ZERO then the next file is located in the current subdirectory. REQ_SET Type: command The REQ_SET command will set a flag in <filespec> that tells 1stReader that @REQ_FILE@ has been downloaded successfully. REPLIES Type: function The REPLIES function will check to see if a @BBSID@.REP file exists in the packets subdirectory. Use this function with an IF statement to determine if replies are on file and should be uploaded. RETURN [label] Type: command The RETURN command returns execution of the 1stReader script to the next command after the calling GOSUB command. If you include the optional [label] then execution resumes at the statement following the label. RUN <script filespec> [label] Type: command The RUN command lets you load a new script into 1stReader. If you include the optional [label] then execution will begin at the label. SET_FLAG <filespec> <byte_num> <ON|OFF> Type: command This script command compliments the FLAG function described earlier, except this command will either turn the byte <byte_num> located in <filespec> to ZERO (for OFF) or to ONE (for ON). You can use this command to set a flag in an external file so scripts can branch depending on the value of <byte_num>. Page 47 SET_PASSWORD Type: command This command is to be used along with the NEW_PASSWORD command to generate a new password for your login account. The SET_PASSWORD command writes the new password created by the reader to your dialing directory entry. Otherwise, the password would NOT be saved by 1stReader. SHOW <filespec> Type: command The SHOW command will display a short text file on the screen. The difference between the SHOW and LIST commands is that the SHOW command loads the text into memory and displays it using the help screen while LIST will display any size file using the internal list routines. SWITCH <value> Type: function The SWITCH function lets you query the 1stReader switch settings. You can then use an IF statement to take action based on the way a particular switch is set. <value> corresponds to the following table: Value Switch description ----- ------------------ 1 Advanced features 2 Use bookmarks 3 External editor 4 Color monitor 5 Sound 6 Auto list messages 7 Sort systems 8 Random taglines 9 Music 10 MultiMedia 11 Use mouse 12 Auto position mouse 13 FIDO taglines 14 Use DTR to hangup 15 PostLink routing 16 Load 1STTEXT 17 Top of form on printer 18 Debug scripts 19 Log calls 20 Save new file lists 21 SuperShell to DISK 22 SuperShell to EMS 23 Skip messages you have read 24 Terminal alarms 25 Sort conferences 26 Large message screen Page 48 27 Using 4DOS 28 Lock serial port 29 Auto alias 30 Show packet names 31 Trim quotes 32 Disable ANSI messages 33 Quick scan messages 34 Clear input fields 35 Ask on ANSI messages 36 Skip messages from you Remember you may use the IF NOT condition to see if a particular switch has been turned OFF. TERMINAL Type: command The TERMINAL command does not have any arguments. It will send the user into an immediate terminal mode. To exit the terminal mode and return to the script press ALT+X. TERSE Type: command This script command has no parameters...it is used to switch PCBoard systems from the standard 'text' display mode to a 'terse' display mode. This makes it possible for 1stReader scripts to be 'language independent' and work on all PCBoard systems. The price you pay is that you also give up seeing the normal text prompts and instead see only TXTnnn prompts. TRANSMIT "string" Type: command The TRANSMIT command will transmit "string" to the remote system. TRANSMIT; "string" Type: command This command works just like the TRANSMIT command except that any embedded spaces are converted into semi-colons. For example, TRANSMIT; "Mark Herring" would be converted into "Mark;Herring". This command can be used to log into systems that require semi-colons for a single-line login. Page 49 TIMEOUT <seconds> Type: command The TIMEOUT command sets the number of seconds that must pass without receiving data from the remote system before the reader will transmit a carriage return. This command is used to catch situations where you might be sitting at the "Command?" prompt on PCBoard yet the script may not catch it. If you wish to disable the TIMEOUT completely use a value of 0 seconds. UPLOAD <filespec> Type: command The UPLOAD command will upload <filespec> using the Zmodem file transfer protocol. WAITFOR "prompt string" [seconds] Type: command The WAITFOR command scans incoming text for "prompt string". When "prompt string" has been found execution of the script continues. [seconds] is an optional value that can be added to the command so that WAITFOR only waits for [seconds] for "prompt string" to be found. If [seconds] pass with or without finding "prompt string" execution of the script continues. You can scan for more than one value by separating the values using "|" bar characters. For example, WAITFOR "Yes|No" would wait for either "Yes" or "No" to be received. You can later test which value was received by using the FOUND= function. WEEKDAY Type: function The WEEKDAY function returns the day of the week in numeric form. Sunday=1, Monday=2, Tuesday=3, Wednesday=4, Thursday=5, Friday=6, Saturday=7. You can use this function with the IF function to find out which day of the week today falls upon. Page 50 Special @variables 1stReader maintains special @variables that can be used by scripts. Here is a list of variables supported: @BBSNAME@ The name of the BBS. @USER@ The name of the LOGIN field in the BBS record. @PASSWORD@ The password field in the BBS record. @SYSTEMDIR@ Location of the 1stReader system subdirectory. @PACKETDIR@ Location of the mail packet subdirectory. @DLDIR@ Location of the file download subdirectory. @REPDIR@ Location of the replies subdirectory. @PROGDIR@ Location of the PROGRAMS subdirectory. @LANGAUGE@ The language version field from the BBS record. If the language value is set to "0" then this variable will be set to blank. @QMAIL@ This variable is set to the name of the door command for the BBS. @COMMAND@ This variable will check to see if a reply packet is available for uploading. If a packet is found then "U;D" is assigned to the variable. Otherwise, "D" is assigned. @CONFERENCE@ The conference number field from the BBS record. This value is used to join a conference before calling the mail door if it is to be called from another conference. @DATE@ Replaced with today's date. @TIME@ Replaced with the current time. Page 51 @GRAPHICS@ Set to "Y" if you have enabled graphics for this BBS. Otherwise, it is set to "N". @FIRST@ Set to the user's FIRST name. @REQ_FILE@ Filespec read from the file request file set by REQ_SETFILE command. Special characters ------------------ 1stReader interprets two special characters for values. The first character is a carat "^". 1stReader will convert the next character, if alphabetical, into a CONTROL sequence. For example, "^G" will ring a bell or "^M" is a carriage return. You can also use "X'" to convert any hexadecimal value into a single character. For example, "X'1B" converts into the ESC character. Page 52 Hints and Tips -------------- This section contains 1stReader features and hints that do not necessarily fit into any of the other areas discussed earlier. Support for .BIN and .B1N files ------------------------------- 1stReader can display .BIN files created by THEDRAW. 1st also supports what we call ".B1N" (Bee One Enn) files. A .B1N file contains TWO .BIN files copied together. The first 4000 bytes of the file (or the first .BIN file) is a monochrome version of the screen display. The second 4000 bytes (or the second .BIN file) contains the color version. You can create a .B1N file by creating two .BIN files inside THEDRAW and then copying them together at the DOS command prompt, like this: COPY TEST.B1N+MONO.BIN+COLOR.BIN 1stReader displays the monochrome version of the file if the color display switch is turned OFF. Otherwise, the color version of the file is displayed. 1stReader will find .BIN and .B1N files when looking for $$CALL files. The order of the search is: .ASC .ANS .B1N .BIN The WELCOME file ---------------- When you startup 1stReader it will look for a file named WELCOME in the system subdirectory. This can be a customized file created by the user. WELCOME.ASC, WELCOME.ANS, WELCOME.B1N, WELCOME.BIN and WELCOME.GIF are supported. Page 53 Using KEYBOARD.$$$ from the internal editor ------------------------------------------- If you shell to a program while inside 1stReader's internal editor and KEYBOARD.$$$ is created, then KEYBOARD.$$$ is pasted into the text at the current cursor location when control returns to 1stReader. This feature lets third-party developers create "Usenet address books" so they can pass back Usenet addresses into replies. Of course, there can be hundreds of uses for this feature too. Pre-Print and Post-Print strings -------------------------------- You can add pre- and post-printing initialization strings to 1stReader by using our 1STTEXT.EXE editing program. This program, which is available on our customer support system (you can use our DLXTEXT.EXE program too) lets you edit the 1STTEXT file. Record #282 is reserved for any printer initialization string you require. Record #283 is reserved for any post-printing string you require. If you need to send more than 78 characters to the printer you can tell 1stReader to read the characters from a file. Use "FILE=<filespec>" in record #282/#283 and 1stReader will read <filespec> for the strings. Printer definition ------------------ Record #273 in 1STTEXT is used to declare the name of the printer on your system. Currently, it defaults to "PRN" but you can send printer output anywhere you wish by changing record #273. Create your OWN help files -------------------------- You can "over-ride" the internal help screens we have provided in 1stReader by creating your own HELP.xxx files. "xxx" corresponds to the help record number. You can create custom help files for a BBS by storing them in the BBS subdirectory. Or, you can globally affect the files by storing them in the SYSTEM subdirectory. Page 54 1stReader is network ready -------------------------- You can run multiple users from one copy of 1stReader kept on a network. Or, you can let family members keep their own setups without requiring multiple copies of 1stReader. All you need to do is to create separate subdirectories for each user. You could name them C:\1ST\JOHN, C:\1ST\BILL, etc. You can even place them on separate drives if you wish. Each user subdirectory MUST have a copy of 1ST.SET and 1ST.KEY in order to work. 1stReader will create unique files and BBS subdirectories for each user. In order to find the 1stReader system files, you need to use the DOS environment variable "SET 1ST=C:\1ST\" (change this to point to your 1stReader SYSTEM location) in your AUTOEXEC.BAT file. This lets 1st find the files it needs to run over a networked system. Remember, you must still execute the program by typing C:\1ST\1ST from the DOS command line or a batch file. IMPORTANT NOTICE: YOU *MUST* PURCHASE MULTIPLE COPIES OF 1STREADER FOR EACH USER ON YOUR SYSTEM IF USED IN A BUSINESS. IT IS A VIOLATION OF OUR LICENSE AGREEMENT AND COPYRIGHTS IF YOU ALLOW MULTIPLE USERS TO OPERATE 1STREADER USING THE SAME 1ST.KEY FILE. Notice to families: We consider 1stReader to be 'marital property'. Any family member who lives under your roof may use your copy of 1stReader. GO.ASC, GO.ANS, GO.BIN, GO.B1N ------------------------------ In the file manager, after you select a subdirectory, if 1stReader finds any of these files in the current subdirectory they are immediately displayed to the user. The idea behind this feature is to allow archived programs and "services" that are sent by some mail systems to have their own "introduction" when used with 1stReader. A word about services and 1stReader. Offline games are now very easy to create using 1stReader's service capabilities. Your game can use one of these GO display files to welcome the user to the game. If a READ.ME file is found in the service then that file is automatically displayed to the user (game news or rules could be posted here). Finally, you can provide a GO.BAT file so all the user has to do to start Page 55 your game is to click on the "GO" button. Your game software can then write any files that are needed to be sent back up to the mail system by storing them inside the REP-WORK subdirectory. The contents of this subdirectory are compressed into the .REP mail packet and transmitted back to the mail system. If you are interested in creating offline games for use with mail systems that support services and 1stReader, please give our customer support system a call. We'll be happy to show you everything you need. Trivia games could be a good example of an offline game. Automatic DOORWAY ON and DOORWAY OFF modes ------------------------------------------ If you call a bulletin board system using Doorway 2.22 from Marshall Dudley then 1stReader can automatically switch into and out of 'Doorway mode' while connected to the system. Doorway 2.22 transmits codes that 1stReader watches for and when found, turns 'Doorway mode' ON or OFF for the user. Note: This feature requires use of Doorway 2.22 (or later). "Header" files -------------- 1stReader supports "Header" files that can be used in your editor whenever you enter a message. If the file "HEADER.HDR" is found in either the BBS or SYSTEM subdirectory, then 1stReader will read it and copy it into the "top" of your reply. You can use any @variable you wish in your header. 1stReader also looks for the text "∙HEADER:<name>" in a message. If this text is found and <name>.HDR exists in either the BBS or SYSTEM subdirectories, then 1stReader uses this header file instead to begin your replies. You can also have separate "Header" files for public and private messages. 1stReader will determine which file is used depending if you are replying to a public or private message. HEADER.PUB - Public messages HEADER.PRI - Private messages Sysops, this is a good candidate for your 1ST-TIME.ZIP files Page 56 Auto sensing dialog boxes ------------------------- If you have defined the dialog boxes to use the same color as the current background, 1stReader switches to a WHITE background in the dialog box automatically so the box will stand out. If your background is white (and you are using color) then light blue will be substituted. "Ok" and "Cancel" buttons ------------------------- If you are using a mouse then 1stReader will place these mouse buttons inside keyboard dialog boxes. They do not show up if you are not using a mouse. Attention John Hancock fans! ---------------------------- 1stReader always supports the famous "DOS:JH3" tagline. This allows you to call John Hancock from inside 1stReader. If you like to use a lot of taglines in the internal tagline manager, picking out that single "DOS:JH3" tagline could be a bear. Instead, create yourself a "picklist" for use at the tagline prompt when saving a message by arrowing into this field and pressing ALT+F8. Use this entry for your picklist: TITLE=Taglines DOS:JH3 Press [F8] to call up the picklist. When you select "DOS:JH3" from the list 1stReader will call John Hancock automatically and pass the tagline to you. 1stReader supports the "DOS:" command in taglines. If this string is found then 1stReader will shell to DOS and execute the command immediately after "DOS:". Page 57 Specialized conference .BAT, .BTM, .CMD and .LST files ------------------------------------------------------ If you create files using these extensions, but using the names of conferences, then these files are active when you press [F6] (for .BAT files), [F7] (or .CMD files) or [F8] (or .LST files). This lets you create specific files that only work when you have joined a particular conference. Support for DOOR.ID ------------------- If 1stReader finds a DOOR.ID inside the QWK mail packet and the entry "CONTROLTYPE =" is found inside, then, when you add or drop conferences using 1stReader, it reverts back to the "old" method of writing one message at a time to add or drop the conference. This method is provided for backwards compatibility with older mail systems. Downloading files ----------------- If you download files from 1stReader's internal terminal module or from your favorite terminal program, 1stReader will automatically invoke the file manager and take you to your download subdirectory when you exit the terminal mode. This feature lets you manage the files you just downloaded in the online session. Longer signatures ----------------- 1stReader provides you with a "signature" field that will automatically place your name on the bottom of messages you enter in the reader. However, you may find you need more lines in your signature or you might like to incorporate graphics. 1stReader lets you use "SIG=<filespec>" as a signature. This tells 1st to look for the file <filespec> in the BBS subdirectory or in the SYSTEM subdirectory. If found, the file is imported automatically into your replies. Page 58 Multiple signatures ------------------- Sometimes having only one signature can be a limitation. 1stReader lets you have up to 100 signatures per system if you need them. The trick is to use the Picklist system. Instead of entering your name in the signature field use the entry "NAMES.LST". Then, press the ALT+F8 key to create the picklist. Here is an example: TITLE=Signatures Sparky,Sparky Qmail Support,Qmail Support Long signature,SIG=NAME1 When you save the message you'll be asked to select the signature you wish to use. Notice the "SIG=NAME1" entry. If you pick that entry 1stReader will use the file "NAME1" as your signature. Support for the "1ST" file -------------------------- If 1stReader finds the file "1ST" inside a mail packet, it will display this file to the user immediately after the "Welcome" screen. This file is provided so sysops can pass information on to their offline mail users that might not apply to their regular "online" users. Automatic SuperShell -------------------- If you have not turned SuperShell ON in Setup's "Switches" section and you attempt to shell to DOS with less than 125k of memory available, 1stReader will automatically invoke SuperShell for you. Page 59 Nonstandard serial ports ------------------------ 1stReader will support nonstandard COM3 and COM4 setups as long as they do not use the "high" interrupts. 1stReader defaults COM3: and COM4: to use the industry standard addresses, but you can override this by using the format: Base Address,IRQ "Base Address" is the base address of the port, in hexadecimal. "IRQ" is the interrupt request line value. If your system uses the industry standard addresses simply use "3" or "4" in this field. Also note that 1stReader supports the "%4" parameter in the Zmodem upload and download commands too. This parameter is replaced with the Base Address,IRQ value so QSZ can use the "portx=" command line parameter. New commands supported in DOOR.ID --------------------------------- 1stReader will use these commands if found in a DOOR.ID file inserted into a QWK mail packet: MIXEDCASE = YES FIDOTAG = YES If "MIXEDCASE = YES" is found then the user will be allowed to address messages using upper and lower case. If the string "FIDOTAG = YES" is found then messages left by 1stReader will automatically use Fido-compliant taglines. You can use "Fido" taglines "on the fly" by including the string "@FIDO@" in your replies if you wish. 1stReader also automatically leaves Fido-compliant taglines if it finds a valid Fidonet address in the tagline of the original message. If you use a Fido-compatible tearline then 1stReader will search your tagline for any characters higher than ASCII 127 and if found, replace them with periods. LIST is restricted ------------------ You cannot list files that end with a .COM, .EXE, .OVL, .ZIP, .ARC, .ARJ, .LHA or .ZOO file extensions from within 1stReader. Page 60 Robocomm-named packets supported -------------------------------- 1stReader will automatically find mail packets that have been named using Robocomm's "nPACKET.QWK" format. "n" is the packet number received for the bulletin board system. QMAIL4 is assumed ----------------- If you forget to enter the DOOR command in the bulletin board's dialing entry then 1stReader will default to "QMAIL4". Three button mice users ----------------------- If you use a three button mouse you'll find that clicking on the middle mouse button will "ping pong" the mouse cursor between the upper screen and mouse buttons on the bottom of the screen. This feature works in the... File management screen List messages screen Mail packets screen Using SPACE BAR and SHIFT+ENTER ------------------------------- 1stReader supports use of the space bar as a method to move through a mail packet. You can use nothing but the space to read messages once you have selected the "Read" button from the "Read messages" screen. If you are using 1stReader on a laptop check out the SHIFT+ENTER key combo. On laptops it can be hard finding that PgDn key. If you hold down SHIFT while pressing the ENTER key 1stReader will think you pressed the PgDn key. Page 61 Protect those 'questionable' taglines ------------------------------------- If you place a question mark as the first character in a tagline, 1stReader will ask you to confirm use of the tagline in a message. This feature helps protect you from using 'questionable' taglines you might use in personal messages but not in public messages. 'Hotkey' your .CMD and .LST entries ----------------------------------- You can add 'hotkey' support for your .CMD and .LST files by placing the character "»" (ASCII 175) directly *IN FRONT* of the character you wish to use for the hotkey entry. 1stReader will strip the "»" character from the string when it is returned back to you. Entry fields are accessible --------------------------- Entry fields are accessible through the @API$(xxx) function. All field entries are numbered starting with field #1 at the top of your screen. The @API$(xxx) function lets you access the first field by using @API$(201). The second field entry is accessible by using @API$(202), etc. This feature lets you pass field entries that are on the current screen to a shelled application. Remember that these functions only return the field entries for the 'current' screen. If the current screen does not contain any field entries, the @API$(xxx) function returns a null string. Page 62 Sysops can use Qmail Door in DOS using 1stReader ------------------------------------------------ If you own a copy of our Qmail Door you can have 1stReader scan for new mail and upload replies by using the $$MAIL.BAT and $$REPLY.BAT files. Your $$MAIL.BAT file should read: @echo off cls c: cd \pcb PCBOARD /USERSYS;<first>;<last>;PWRD:<password>;TPA:QMAIL4 c:\pcb\qm4\qmail4 U;D;Y;G PCBOARD /READSYS Your $$REPLY.BAT file should read: @echo off cls c: cd \pcb PCBOARD /USERSYS;<first>;<last>;PWRD:<password>;TPA:QMAIL4 c:\pcb\qm4\qmail4 U;G PCBOARD /READSYS <first> is your first name used to log into your PCBoard system. <last> is your last name. <password> is the password you use to log into your PCBoard system. You might need to edit these batch files to change the location of your PCBoard subdirectory. These batch files only work with PCBoard 15.0. Simply copy these batch files into the 1stReader BBS subdirectory for your system and when you later select your system from 1stReader's menu, you'll go through DOS to transfer your mail packets instead of calling your system. Control characters in .LST files and KEYBOARD.$$$ ------------------------------------------------- 1stReader lets you use control characters in your picklists and in KEYBOARD.$$$. If you would like to force a carriage return you can use "^M" at the end of the entry. Remember that when you use picklists and KEYBOARD.$$$ from a keyboard entry field, the carriage return is automatically supplied by 1stReader. This feature lets you force control characters while in the internal editor. Page 63 $$DIAL.SCR supported -------------------- This script file can be used to dial a bulletin board system in place of 1stReader's internal dialer. The idea behind supporting this script file is to allow users to make long distance calls using SPRINT, MCI or other long distance carriers that require additional access codes. Placing $$DIAL.SCR inside the SCRIPTS subdirectory will force 1stReader to use the script file everytime it calls a system, regardless if it is long distance or not. We recommend that you place this file inside the individual BBS system subdirectory for better control. Addition bulletin board systems supported ----------------------------------------- 1stReader now has the ability to use different script files when calling bulletin board systems. This means that if you are calling a Wildcat! system you can tell 1stReader to use the Wildcat! scripts. By default, 1stReader uses the PCBoard/Qmail Door script files. Carriage returns in the modem initialization string --------------------------------------------------- You can use the character "{" in your modem init strings to indicate where a carriage return is to be inserted. SERVICES.NEW ------------ Sysops can include a file named SERVICES.NEW in the QWK mail packets and 1stReader will display it when the user selects the 'Services' button. This file is intended to give 1stReader users an introduction to the services provided. Page 64 Clear all entry fields with one keystroke ----------------------------------------- Sometimes it might handy to clear out ALL of the entry fields on a screen at one time. The ZIPPY scan screen is a good example - you might have saved default values but this time you want to search for totally different keywords. If you wish to clear out all of the entry fields at one time press the CTRL key and while holding it down also press the ESC key. All of the entry field values will be erased. QSZ supports 'crash-recovery' ----------------------------- If you were downloading a file from a bulletin board system and the download was interrupted before the transmission was completed, you can simply request that the BBS send you the file and 1stReader will resume the transmission where it left off. Note that 'crash recovery' is not supported while downloading QWK mail packets. Assign different dialing prefixes to telephone numbers ------------------------------------------------------ Some bulletin board systems use different 'hunt groups' where one group requires use of dialing prefix #1 and the other groups might require prefix #2. You can tell 1stReader which prefix to use by using "Px nnn-nnnn" as the telephone number. For example, "P2 555-1212" would tell 1stReader to use dialing prefix #2 for this telephone number even if you assigned prefix #1 to the system. If you wish you can also tell 1stReader to execute a script file for ONE particular number before dialing the number. To do this you need to enter the name of the script file (.SCR is assumed) in the phone entry field. Example: "SCRIPT|555-1212" This number would force 1stReader to execute "SCRIPT.SCR" (if it exists) before dialing "555-1212" every time. Page 65 Access interrupts from DOS command line functions ------------------------------------------------- You can tell 1stReader to access a system interrupt instead of a DOS command. The idea behind this feature is to support any future TSRs that might be written to help the way 1stReader operates. Essentially, this gives 1stReader a 'DLL' capability. For example, a TSR could be loaded before running 1stReader that lets the reader display a message in a totally different manner than the method built into 1stReader now. This is a feature that was available in our legendary 'QPro' offline mail reader we wrote back in 1989 (but never made it to market). We used it to add some rather interesting features to QPro later and we wanted to incorporate the same support for future use in 1stReader. Here's how you do it. If the DOS command starts with "INT:" then 1stReader knows we're going to call an interrupt instead of shelling to DOS. You can pass register data on the command line like this: INT:$80 AX:$0601 BX:$0700 CX:$0101 DX:$1950 Notice that "$" before a number indicates the number is a hexidecimal number. If the "$" is missing then the number is a decimal value. The reader will then execute the interrupt and return the value of register AL in API(234). Also, all register pairs are loaded into the API so they can be tested after execution of the interrupt. You can also access an interrupt from any batch file by using the command: :1ST: INT:$80 AX:$0601 BX:$0700 CX:$0101 DX:$1950 The interrupt will execute and then the batch file can perform any test on any of the register pairs (which are loaded back into the API). 1STTEXT record #350 has been reserved to hold an interrupt call that is executed immediately after loading a message. Record #351 has been reserved to hold an interrupt call that is executed just before a message is displayed on your screen. #351 can be used to display a message in a totally different manner from 1stReader. You can pass back a keyboard scan code in the AL register to the program. If AL=0 then the message is displayed normally. Otherwise, AL contains the scancode and the reader uses it as if you pressed the key in 1stReader. Page 66 You can ONLY address interrupts $80 through $E9. You cannot call any BIOS or DOS interrupt. Note that interrupts can ONLY be called from CMD and batch files (or recs #350/#351 in 1STTEXT) on YOUR system. NAPLPS support is now available ------------------------------- 1stReader can support practically *ANY* file type. To illustrate this feature, 1stReader now supports NAPLPS files. We've provided a NAPLPS kit on the distribution diskette (file named NAPLPS.ZIP) that easily installs into 1stReader and provides your system with the ability to display NAPLPS files from the file manager and *anywhere* a file is displayed. You can now include NAPLPS files in QWK mail packets too! NAPLPS is a graphics standard that was created 10 years ago. You see it used often on cable TV systems. It lets fairly complex graphics images be transmitted in very small files. While they do not have the resolution offered by GIF files they can occupy 1/10th the disk space, or even less. You can study the NAPLPS.ZIP kit to see how we installed NAPLPS support. It is VERY easy to add support into 1stReader for virtually any file type. Make temporary changes to your 1stReader setup ---------------------------------------------- If you have ADVANCED FEATURES turned ON then 1stReader will keep the changes you made 'in memory' and not reload the original settings if you decide you do not want to permanently save the changes. Tagline support from the terminal section ----------------------------------------- You can add this entry into your $$1ST.CMD file: Manual tag,MACRO=---^M ■ Manual tagline^M When you are in the terminal mode and press the F7 key and select "Manual tag" from the menu, presto! You get a tagline! Page 67 The 'CONFIRMATION' field ------------------------ This field is used for you to enter any information the BBS might require to confirm it is you who is calling. For example, WildCat systems will sometimes ask you to enter your birthday to confirm it is you. Other systems might ask for your mother's maiden name. This field is limited to 13 characters. 1stReader also supports the #CONFIRM@ script variable. This variable contains the information held in the confirmation screen so it can be transmitted back to the bulletin board system when requested. The .COPY command ----------------- Whenever long message replies are split up, sometimes it might be nice to have the beginning of the message copied into the extra messages created by 1stReader. For example, if your long message contains a Usenet address header, it would be nice to have 1stReader automatically copy the header into the extra messages it chops up for you. Place ".COPY" on a line by itself in your reply and 1stReader will copy any text above it into the 'split' messages automatically. The actual ".COPY" does not get saved with your reply, so if you later re-edit the message, you must add it back in yourself. A must-have for heavy Usenet users!!! NOTE! You may copy only up to 25 lines of your message. 1stReader automatically aborts a script... ------------------------------------------ If you are dialing a system and get three 'Call Failed' messages in a row without a 'Busy' being encountered, then 1stReader aborts calling the bulletin board system figuring that it is not answering. Picklist notices ---------------- 1stReader will only display the "F8 = Picklist" if you are in novice mode. It takes some disk accessing to figure out if a picklist exists and we reasoned that if you're an expert, you know where the picklists are anyhow. Page 68 Scroll quickly through large messages ------------------------------------- You can scroll 100 lines at a time (both up and down) within one message by holding down the CTRL key at the same time you press PgUp or PgDn. Restricting some .CMD functions ------------------------------- You can add the term <BBS> into any CMD command file and if you have not selected a BBS yet from the opening menu, 1stReader will not display the command in the command menu. Example: View capture file,#API$(28)#API$(10).CAP <BBS> This entry means that if you haven't selected a BBS yet then this command will not be displayed in the command menu. You can also use the term <ADV> in your CMD files. If the user has not turned on the "Advanced Features" switch then any commands that include <ADV> will not be displayed in the menu. Locate a file inside your system's PATH statement ------------------------------------------------- 1stReader supports the "<PATH>" variable in filespecs. This variable tells 1stReader to search the system's PATH variable until it locates the file. Example: "<PATH>COMMAND.COM" This entry would tell 1stReader to search all subdirectories in the "PATH" DOS environment variable until COMMAND.COM was found. 1stReader then sets the full filespec to this name. (C:\COMMAND.COM) 1st moves files automatically into the BBS subdirectory ------------------------------------------------------- 1stReader moves the WELCOME, BBS news and GOODBYE screens into the BBS subdirectories. This lets offline mail systems only send these files out when they are updated. This means a BBS does not need to send a WELCOME.GIF with every mail packet downloaded from a mail system. The file is transferred once and as long as it is not updated by the sysop, it never needs to be sent again. Page 69 Disconnect immediately after an upload or download -------------------------------------------------- 1stReader supports the CTRL+PGUP and CTRL+PGDN keystrokes while in the terminal mode. These keystrokes work just like PGUP and PGDN do (upload or download a file) but when you hold down the CTRL key at the same time it tells 1stReader to hangup the connection after returning from QSZ. How many times have you started a long file transfer to a bulletin board system and didn't want to have to wait for the transfer to be over in order to disconnect from the system? Just use this feature and after the file transfer is finished you will automatically be disconnected from the system. Modify the 1stReader API after a DOS shell ------------------------------------------ You could always read the 1stReader API from a DOS call or use the @variables to display contents of the API. Now you can also update the API in a DOS shell by creating a file named API-NEW.$$$. This file contains one entry per line, like this: @API$(nnn)="xxxxxxxxxxx" ' Strings @API&(nnn)=xxxx ' Long integer @API(nnn)=xxxx ' Integer 1stReader also adds support for the @PASS(nn) variable as well. The @PASS variables are setup to let 3rd party programmers pass info from one application to another through the 1stReader API itself. Up to 20 variables are allocated for use. Usenet message headers ---------------------- 1stReader will display up to 50 characters of the FROM and SUBJECT fields from a Usenet message header. If the fields are longer than 50 characters you can scroll the headers left or right with the message text. 1stReader now automatically detects a Usenet sourced message from any gateway (as long as a valid "Message-Id" field was found) and will use USENET.HDR in any new message or reply you enter automatically. Page 70 Alias signatures ---------------- If you do not use an alias name in your replies then API(195) is always set to "1". It can be set to "2" if the second alias entry was used to save the message or "3" if the third was used. You can use this variable in your signature filespec so you can have 1stReader point to different signatures based on the alias entry used to save the message. For example: SIG=NAME.#API(195) would let you use "NAME.1" for your normal signature, "NAME.2" for alias #2's signature and "NAME.3" for alias #3's signature. The virtual keyboard -------------------- If you click a mouse button and the mouse is positioned in the upper left corner of the screen, the virtual keyboard will appear. This was done to help disabled users with one finger select the virtual keyboard. You can also access the virtual keyboard by pressing the LEFT and RIGHT mouse buttons at the SAME time. The EXTRA FEATURE button ------------------------ 1stReader supports the $$EXTRA.CMD command menu. It would be nice to offer sysops a way to add extra commands to the reader to help further its functions. While pressing F7 is always available, novices might not know about it. So an "Extra features" mouse button has been added to the "Read Messages" menu. If you click on this button 1stReader will look for the $$EXTRA.CMD command menu file (which is designed just like any other command menu file). 1stReader will look in the BBS subdirectory first for the file, and if not found, 1st will look in the \1ST subdirectory. If $$EXTRA.CMD is not found then $$1ST.CMD is used instead. Using the additional add-in features found in 1stReader you can add just about anything to the system now. New features can look like they are an integrated part of 1stReader. Page 71 Display files directly from a .CMD file --------------------------------------- 1stReader supports the "DISPLAY=<filespec>" statement in .CMD menu files. If you use this command in place of a DOS command then 1stReader will display <filespec> on your screen and wait for you to press any key to continue. This feature supports .ASC, .ASC, .BIN, .B1N and .GIF files. This feature is ideal if you wish to add a 'boss screen' to 1stReader. '$<macro>' now available in ANSI files and messages --------------------------------------------------- 1stReader can now use the following commands from inside text files or messages to do the following commands. Use only one command per line. $BLINK ON/OFF $BLINK OFF will let 1stReader use high intensity backgrounds in ANSI messages. $BLINK ON turns this capability off and turns blinking back on. $MUSIC ON/OFF Turns music ON or OFF. Note that this switch DOS NOT change the switch in SETUP that controls ANSI music. That switch MUST be turned on for these commands to work. These commands reset the internal ANSI emulator's music flag so if the user pressed ESC to turn music off the file can reset the switch, or turn it off. $TOP xx These commands set the top, bottom, $BOTTOM xx left and right margins for ANSI $LEFT xx screens. Note that you must not $RIGHT xx exceed the margins for physical screen on your system. $LSET nn <text> These commands will take <text> and $RSET nn <text> set itinto a blank string that is $CENTER nn <text> "nn" characters long. $LSET will set <string> to the left side of the blank string. $RSET sets <string> to the right side of the blank string. $CENTER will center <string> into the blank string. $LOCATE row,col Positions the cursor to row,col on the screen. Page 72 $GIF <filespec> Displays a GIF file. $NAP <filespec> Displays a NAPLPS file (if NAPLPS is installed). $MME <filespec> Plays a .MME, .VOC or .CMF file through your sound card (if multimedia is turned ON). Sensing color attributes ------------------------ 1stReader support the "@x??" color code. If "??" is used then 1stReader uses the current color attribute on the screen at the point where the text is going to be displayed. The NEWS.LST file ----------------- After displaying the BBS news, 1stReader will look for this file and read it if found. The file contains other filenames that should be displayed to the user. It can also contain DOS commands if the entries begin with the string "DOS:". This file works well for new user setups - the sysop can even include programs that give the user a guided tour of their system automatically. The ATTACHED.LST file --------------------- 1stReader will look for an ATTACHED.LST file inside a QWK mail packet and moves the attached files from the WORK area into the DOWNLOADS subdirectory. Save some disk space -------------------- If you wish to save 124,504 bytes of disk space you can delete the 1ST.B&W file if you always have the "Color monitor" switch turned ON. If you always use monochrome screens then you can delete 1ST.CLR instead. Page 73 The INSTALL module ------------------ The 1stReader install program (INSTALL.EXE) is much more than just a simple installation program. It has its own 90 command script langague that lets you program interactive presentations, menus and all sorts of applications. Click on the "1stTutor" button from the opening menu to see a demonstration of INSTALL's capabilities. See "INSTALL.DOC" for a complete list of commands supported. Creating offline help for bulletin board systems ------------------------------------------------ 1stReader can access help for a bulletin board system while the user is in the terminal mode. If the user presses the [F10] key from the keyboard then the reader searches for the file <name>.INS or <name>.HLP (<name> is the name of the script used to call the bulletin board system). If <name>.INS is located then 1stReader shells to the INSTALL program to run the help file. Otherwise, <name>.HLP is displayed from within 1stReader. Sysops can create their own custom HELP files by copying them into their .BBS files. 1stReader will automatically install these files when reading the .BBS files. Page 74