The Datafile PD-CD 5

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

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / n / newsflash / !FileBase / !NewsFlash / Docs / Manual < prev next >

Wrap

Text File | 1996-09-16 | 13.4 KB | 439 lines

User guide for NewsFlash BBS software ===================================== Contents: Last update: 1. Introduction 7/5/95 2. Setting up 7/5/95 3. General usage 7/5/95 4. NewsFlash script language and compiler 2/8/95 5. Writing doors 7/5/95 6. Using doors from other systems 7/5/95 Appendix: A. Credits 16/9/96 B: Contacts 24/7/95 C: License 19/7/95 D: Software used 16/9/96 E: Boring specs. 16/9/96 Additional data sheets: SWI's : List of all NewsFlash SWI's Messages : List of all NewsFlash WIMP messages FileArea : Details of the File Areas file structure FileBase : Details of the File Base file structure UserFile : Details of the user file and user record structure Commands : Brief list of script commands Chapter 1 : Introduction ------------------------ NewsFlash is a multi line BBS package for use with Acorn 32 bit machines. There was no real need for another BBS package on the Arc but I thought I'd write one for fun anyway.. :-)... Also, I wanted a BBS package that would offer sysop's a bit of extra control over the way their BBS looked. For that reason NewsFlash script files may be a bit more compilcated than other types of scripts. However, scripts to peform most of the common functions have been written already so Sysop's can look at these and modify them or re-write their own versions if they wish. Chapter 2 : Setting Up ---------------------- NewsFlash is very simple to set up, with all configuration done via the WIMP. NewsFlash is initially set up as a 3 line BBS with line 1 using the Internal driver, line 2 using the pipe driver and line 3 for local logons only. Chapter 3 : General usage ------------------------- Chapter 4 : NewsFlash script language and compiler -------------------------------------------------- This chapter is split up into several parts: 4/1. Introduction 2/6/95 4/2. Description of commands 2/6/95 4/3. Using the file base facilities 2/6/95 4/4. Using the message base facilities 2/6/95 4/1. Introduction -=-=-=-=-=-=-=-=- 4/2. Description of commands -=-=-=-=-=-=-=-=-=-=-=-=-=-= IO Device commands: NewsFlash allows you to setup several In/Out devices, meaning that data can be sent from one serial port to another, or to a telnet port, etc. Every device has a unique handle so that it can be identified. You can output to, or read from, a device using the standard IO commands (print,input,etc.), or by using commands to control a specific device. You use the standard commands by setting changing the currently selected output device. ============================================================================ OPENDEVICE <DeviceType$>,(Parameters vary) TO handle% Current devices are: SERIAL, TELNET and WINDOW. Examples: OPENDEVICE "SERIAL","INTERNAL",0,19200 TO handle% OPENDEVICE "TELNET","armadilo.demon.co.uk",80 TO handle% OPENDEVICE "WINDOW",open% TO handle% The handle returned is an integer. The SERIAL device takes the parameters: Serial Driver Name (String) Serial Driver Port (Integer) Serial Driver Baud Rate (Integer) OPENDEVICE "SERIAL",<Driver>,<Port>,<Baud Rate> TO handle% The TELNET device takes the parameters: Telnet Address (String) Telnet Port (Integer) OPENDEVICE "TELNET",<Address>,<Port> TO handle% The OS device takes the parameter: Clear flag <Boolean Integer> OPENDEVICE "WINDOW",<Title>,<Open> The open flag states whether the window should be opened immediately or when the first input/output is made. ============================================================================ CLOSEDEVICE <Handle> Closes a specific output device (must be done before the same (not same type) device can be opened again. ============================================================================ SETDEVICE <Handle> Sets the current input/output device (for use with PRINT, INPUT, etc.) ============================================================================ RESETDEVICE Sets the current input/output device to the original/default device. ============================================================================ OUTPUTBYTE <Handle>,<Byte> TO <Failed> Attempts to output a byte (passed as an integer) to a specific IO device. A boolean integer is returned indicating failure (non zero if not sent). ============================================================================ INPUTBYTE <Handle> TO <Byte> Attempts to read a byte from a specific IO device. -1 is returned if no byte was read. ============================================================================ 4/3. Using the file base facilities -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- File base commands: ============================================================================ FILESEARCH This command will perform a search through the file base for a file using a search string. It is used as follows: FILESEARCH fa%,searchcode%,max%,searchstring,type% TO searched%,result%,searchcode% it should be called repeatedly until the search has finished. It will set 'searchcode%' to 0 if the search has finished. Where: fa% - file area to search (or 0 for all file areas) searchcode% - code to allow multiple calls (set to 0 for first call) max% - maximum number of files to search on this call searchstring - string to search for type% - zero to indicate 'searchstring' is a filename, otherwise 'searchstring' is a keyword. searched% - number of files that were searched result% - filenumber of a matching file or 0 if no match was found searchcode% - code to pass on next call (or 0 if search has finished) Example: SUB filesearch OPENFILEBASE | fa% contains area to search (0 for all) STD FG 2} Search by filename or keyword? (N/K){GET searchtype,NK" NL IF st="N" THEN FG 3}Enter filename : {INPUT searchstring ELSE FG 3}Enter keyword : {INPUT searchstring ENDIF NL totalsearched%=0 | Total number of files searched searchcode%=0 | First call FG 4 REPEAT FILESEARCH fa%,searchcode%,100,searchstring,searchtype="N" TO searched%,result%,searchcode% totalsearched%=totalsearched%+searched% TAB 0 PRINT "Searched "+totalsearched%+" files" CLL IF result% THEN | At this point 'result%' contains the file number of a matching file. NL PRINT "File #"+result% NL ENDIF UNTIL searchcode%=0 FG 5} Search finished { GOSUB anykey CLOSEFILEBASE ENDSUB 4/4. Using the message base facilities -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Chapter 5 : Writing doors ------------------------- There can be two types of doors for NewsFlash. There can be doors which are simply run when they are needed and one of each is needed for each line that runs the door. These will be referred to type 1 doors. There can be doors which are running permanantly and are called up by the BBS via a WIMP message. These doors must be able to handle a request for connection from each line. These will be referred to type 2 doors. Doors may also force a connection. To do this a door just claims a line without warning and then releases it when finished.. Type 1 doors are (usually) run by the script command RUNAPPa. This command will run the door and pass the line number for it to start on on the command line string. For example.. RUNAPPA "<NewsFlash$BBS>BBS.Chats.!AIChat" from line 1 will perform.. SYS "Wimp_StartTask","<NewsFlash$BBS>BBS.Chats.!AIChat 0" (line numbers start from 0 for doors!) The 'A' flag must be present if the door is to start in a 'controlled' way. It stands for Acknowledge. If it is not present the BBS may be half redrawing the menu before the door starts...which will look messy! :-) Type 2 doors are started by the NewsFlash message NewsFlash_StartDoor which is triggered by the script command STARTDOOR. For example.. STARTDOOR 0 will request the NewsFlash supervisor door to start. Once the door has been started their is very little difference between type 1 and type 2 doors. Once a door has been called to start NewsFlash will wait for an Acknowledgement that the door has claimed the line. It will wait 5 seconds before timing out and continuing with the script as normal. Once the door has started as a WIMP task it must claim the line it is to control to stop take control from the script file. The script will be paused until the line is released. To claim a line a door must perform.. SYS "NewsFlash_ClaimLine",line%,grabscreen%,bufferblock%,taskhandle% where line% is the line number of the door is running on, grabscreen% is non-zero to request the screen to be grabbed (so it may be redraw when the door releases), bufferblock% is a pointer to a block containing details of the buffers to be used (or 0 for default) and taskhandle% is the WIMP task handle of the door (must be non-zero). Once a door has claimed a line (and it has not forced a connection) it must acknowledge that it has claimed the line succesfully. To acknowledge to NewsFlash a door must perform.. SYS "NewsFlash_Acknowledge",line%,1 where line% is the line number the door is running on. The '1' in R1 can be any non-zero word but use 1 for future compatability. A door may now use the following SWI's to send and receive data: NewsFlash_SendByte NewsFlash_SendMany NewsFlash_GetByte NewsFlash_GetMany NewsFlash_VDU (not implemented) The data passed to and from the door is buffered between WIMP polls so a door should take this into account and not assume that all the data it tries to send will be sent! It must keep trying to send the data whilst WIMP polling until all the data has been sent. Once the door has finished it should release the line using.. SYS "NewsFlash_ReleaseLine",line%,redrawscreen% where line% is the line number the door is running on and redrawscreen% is non-zero to redraw the screen as it was before the door claimed the line (the screen must have been grabbed first). A door may easily obtain information on the line it has claimed using the SWI's listed in the SWI's file. If a door is to be 100% 'legal' it should listen to all the NewsFlash WIMP messages. It will be informed if a user has disconnected unexpectedly or if the BBS is being quit..and many other things too. Refer to the Messages file for more information. Chapter 6 : Using doors from other systems ------------------------------------------ NewsFlash will run most ArcBBS and RiscBBS doors. However, RiscBBS doors are not guaranteed to run reliably on multi-line setups. The doors will run without any modification.. To run RiscBBS doors use the command STARTRISCBBSDOOR For example.. (to start the Tetris door) STARTRISCBBSDOOR "<NewsFlash$BBS>Games.!Tetris 0" Use a task handle of 0 in place of the RiscBBS task handle. I have had no problems with it. Note: To run RiscBBS doors you will need the RiscBBS door emulator loaded. To run ArcBBS doors you will need to refer to the help file supplied with the door but here are a few conversions for commands.. ArcBBS NewsFlash OSCLI "WimpTask ..." RUNTASK "..." DOOR ... STARTARCBBSDOOR ... This should be all you need to know. Note: To run ArcBBS doors you will need the ArcBBS emulator modules loaded. Appendix: ========= A: Credits ---------- NewsFlash was written by Chris Davis. Demo BBS by Alex Howarth A lot of thanks must go to Alex Howarth for testing, spreading the word, designing some decent app. sprites, giving me plenty of encouragement and coming up with a more original name than 'ArcHost' :-).. Thanks also to Niall Douglas for providing some helpful pointers and mod's for getting NF to run under RO2. B: Contacting me ---------------- If anyone wishes to contact me please send e-mail to: Chris Davis.. Fidonet 2:253/417.6 or 2:257/501.7 Internet chris@armadilo.demon.co.uk Highlander BBS 01452 384557/384702 Phone 01242 244227 C: License ---------- This software is shareware and copyright Chris Davis 1995 To register this software send 10 ukp to: Chris Davis 234 Prestbury Road, Cheltenham, Glos. GL52 3EY D: Software used ---------------- All sources written using !Zap 1.10 by Dominic Symes All sources assembled using BBC BASIC V (with BAX) Templates created using !TemplEd 1.27 by Dick Alstein Iconsprites create using !Paint (AFAIK) Some testing done using !FeedBack by Chris Davis (quick plug there! :-) ) All system operating done by Risc OS 3.10 ! :-) All reminders of TV progs starting provided by !Alarm 2.37 All free memory shown by Free Memory Display 1.03 by Liquid Silicon E: Boring specs --------------- Source size and assembly time details: Source Size Assembly time Lines Size ~Lines/Instructions (Input) (ARM 2 A3000) (Source) (Output) (Output) NewsFlash !RunImage 150K 5.09 8607 25K 6000 NewsFlash (MOD) 500K 17.76 28232 79K 17500 Server (MOD) 103K 2.55 5725 15K 3750 Compiler (MOD) 113K 3.14 6581 20K 5000 Compiler !RunImage 36K 0.72 2139 5K 1000 ArcBBSFl 5K ?.?? 228 652 150 ArcBBSEm 14K ?.?? 784 1900 500 RBBSEm 11K ?.?? 630 1436 350 NFCache 8K ?.?? 487 1304 300 Well. That was fascinating wasn't it!! :-)