ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / PASCAL / AVDOOR11.ZIP / AVDOOR.DOC next >

Wrap

Text File | 1991-12-10 | 29.1 KB | 755 lines

AVDOOR - Avatar's Generic Door Toolkit Created 3/12/90 by Avatar Sysop of S.I.G. BBS +61 3 888-8846 Copyright (c) 1991 Serious Cybernetics | Version 1.10 documentation | Last updated 10/12/91 by Avatar | Lines marked with a vertical bar "|" in the left margin have been updated | since the previous version. If you have any comments or suggestions, | please contact me as Avatar on S.I.G. BBS +61 3 888-8846 or via netmail at | 199:4242/1@RainbowNet, 3:632/358@FidoNet or 58:4100/32@INTLnet. You can also reach me as avatar@csource.oz.au on the Internet or by mail at: Serious Cybernetics P.O. Box 409 Canterbury 3126 Australia Introduction ------------ | AvDoor evolved from another program of mine called AIchat, and later | closed the circle by being used to implement further releases of that | program. However, I needed to write a number of other online programs, | and thus AvDoor was born. Pretty soon people were asking me if they | could use my routines and I decided to release this unit as shareware. AvDoor provides most of the underlying infrastructure needed by almost every online program, including: * FOSSIL detection (but will work without one) * ANSI emulation (doesn't need ANSI.SYS installed!) * Local console screen I/O and status line (using only BIOS calls) * Built-in chat mode with word-wrap and logging (and optional shell-to-DOS) * BBS interfaces, command-line mode and local operation * Timeout, time used and hangup detection (very important!) * Software registration keys (with registered copies of AvDoor only) Legal Notice ------------ This program is Shareware. You may distribute it as widely as you wish. You may not modify AVDOOR55.TPU, AVDOOR60.TPU or this file AVDOOR.DOC in any way, nor may you omit any of them. You may not include any other files as part of the AvDoor distribution package, and you may not charge more than a fair and reasonable copying fee. If you continue using this program on an ongoing basis after having tested it, you must send $25 (A$30 or equivalent in foreign currency if outside Australia) or more to the address at the end of this documentation with your name and (optionally) the business name you would like AvDoor registered to. You will receive a disk containing the latest version of the program registered in your name and a selection of other Freeware and Shareware software from Serious Cybernetics. Please specify the size and shape of disk you require when ordering. No warranty of any kind is expressed or implied, and the author will not be held liable for any damages, consequential or otherwise, caused by the use, misuse or abuse of this program. We told you the rules, now don't forget them! Failure to abide by these terms constitutes a breach of copyright law. Nyaah! Installation ------------ You will need to rename AVDOOR55.TPU to AVDOOR.TPU if you are using Turbo Pascal 5.5, or rename AVDOOR60.TPU to AVDOOR.TPU if you are using Turbo Pascal 6.0. If you are using any other programming language, please contact me to find out if a version of AvDoor to suit | you is planned. Source code for parts of AvDoor may be available in | later releases if requested - contact the author for pricing. Contents -------- | This manual is gradually being expanded with every release of AvDoor. | At present it consists of the following information: A summary of the | types, constants and variables (in that order) defined by AvDoor, an | explanation of the ShellProc variable with a sample DosShell function, | a brief summary of the functions and procedures provided by AvDoor, a | longer explanation of each of the procedures and functions, and a | (very simple!) sample program. Hopefully that should be enough to get | you started, but if you have any further questions feel free to | contact me by any of the means listed at the beginning of this | documentation. Priority will obviously be given to registered users. Types ----- | Effects = (Normal, Highlight, Underline, Blink, Reverse, Hidden); | CurrencyFmt = (Before, After, BeforeSp, AfterSp, DecimalPlace); | DateFmt = (MDY, DMY, YMD); | TimeFmt = (Time12, Time24); Constants --------- | DoorVers = '1.10'; Current version of AvDoor | Black = 0; DkGrey = 8; BlackBg = 0; | Blue = 1; LtBlue = 9; BlueBg = 16; | Green = 2; LtGreen = 10; GreenBg = 32; | Cyan = 3; LtCyan = 11; CyanBg = 48; | Red = 4; LtRed = 12; RedBg = 64; | Purple = 5; LtPurple = 13; PurpleBg = 80; | Brown = 6; Yellow = 14; BrownBg = 96; | LtGrey = 7; White = 15; GreyBg = 112; | Bright = 8; | Blinking = 128; MsgColour = White; Colour of system messages SysColour = Yellow; Colour of Sysop's text UsrColour = Cyan; Colour of User's text MorColour = Purple; Colour of [ENTER] message ErrColour = LtRed; Colour of error messages | FldColour = LtGrey + BlueBg; Colour of string input fields Zero = Ord('0'); ASCII code for '0' Etx = #3; ASCII code for End of Text (^C) Esc = #27; ASCII code for Escape Del = #127; ASCII code for Delete Variables --------- ShellProc: Function(Command: String): Integer; | Option: Array['A'..'Z'] of String[40]; | Options: Set of 'A'..'Z'; EXEpath: String; Path of .EXE file (if >= DOS 3.0) Desqview: Word; Desqview version number or zero | Process: Byte; Current process number (0 = single-tasking) | DateFormat: DateFmt; Format of dates in current country | Currency: String[4]; Currency symbol in current country | Thousand: Char; Thousand separator in current country | Decimal: Char; Decimal point or comma in current country | DateSep: Char; Date separator in current country | TimeSep: Char; Time separator in current country | CurrencyFormat: CurrencyFmt; Currency symbol format in current country | CurrencyPlaces: Byte; Currency decimal places in current country | TimeFormat: TimeFmt; Time format in current country | ListSep: Char; List separator in current country Author: String[60]; Name & details of author ProgDesc: String[60]; Brief description of program Written: String[9]; Date program was written Version: String[4]; Current version number of program Baud: String; Baud rate (0 = local) | Port: Byte; Port number minus 1 | Lines: Byte; Number of lines on remote screen Username: String; Full username or 'UNKNOWN' FirstName: String; User's first name ('' if unknown) BBSName: String; Name of BBS ('' if unknown) SysopName: String; Name of Sysop ('' if unknown) Graphics: Boolean; True if ANSI supported Online: Boolean; True if user has not hung up or timed out Fossil: Boolean; True if a FOSSIL is in use WordWrap: Boolean; True if AvDoor is performing word wrapping Registered: Boolean; True if program is registered KeyCh: Byte; Scan code of local key pressed MaxTime: Byte; Maximum time permitted in program (minutes) TimeLeft: LongInt; Time left in program (seconds) Functions and Procedures ------------------------ | function UpCase(Ch: Char): Char; Convert character to uppercase | function LoCase(Ch: Char): Char; Convert character to lowercase function Upper(S: String): String; Convert string to uppercase function Lower(S: String): String; Convert string to lowercase function Mixed(S: String): String; Convert string to mixed case function RepChr(Ch: Char; N: Byte): String; Create string of repeated chars function Time: LongInt; Current time (seconds past midnight) | function DateStamp: String; Current time and date string procedure StatLine; Display status line procedure UndoStat; Remove status line procedure Update; Update time display on status line | procedure Beep; Ring user's console bell | procedure Newline; Perform CRLF procedure PutCh(Ch: Char); Output a character procedure Put(S: String); Output a string procedure PutLn(S: String); Output a string with CRLF procedure PutTab(C: Byte); Move cursor to specified column procedure PutNum(N: Longint; W: Byte); Output a number right-justified | procedure PutMenu(Ch: Char); Output a menu choice procedure PutANSI(Ch: Char); Output a character with ANSI * procedure ClrEol; Clear to end of line * procedure ClrScr; Clear entire screen procedure GotoXY(X, Y: Byte); Move cursor to (X,Y) * function GotCh: Boolean; True if character ready function RawCh: Char; Input raw character function GetCh: Char; Input a character function WaitCh(csecs: Word): Char; Input a character with timeout function Fetch(Valid: String): Char; Input a character with validation | function GetField(Mask: String): String; | Input a string field with mask procedure Flush; Flush input buffers procedure Purge; Purge output buffers procedure Pause; Display [ENTER] and wait for key procedure Delay(csecs: Word); Delay a number of centiseconds | procedure Colour(C: Byte); Change colour * | procedure Effect(E: Effects); Select display effects * procedure Error(Msg: String); Display error message on console procedure Initialise(PN: String); Initialise AvDoor NOTE: The procedures marked with an asterisk "*" above require ANSI graphics to be enabled (indicated by Graphics = TRUE). PutANSI and | GotoXY will still send the ANSI characters and operate correctly on the | local console, but the remote user will get meaningless junk. ClrEol, | Colour and Effect will NOT send any characters to the remote user if ANSI | graphics is disabled (Graphics = FALSE). Colour will also set the local | colour to light grey on black to simulate what the remote user is seeing. | The ShellProc variable ---------------------- | This variable contains the address of a function which will attempt to | shell to DOS and execute a given command. By default, ShellProc | contains the address of a function which will immediately return -8 as | an error code. An example function using the Turbo Pascal DOS unit: | (* Set 8K stack and 10K heap to leave room for shell *) | {$M 8192, 0, 10240} | uses Dos; | {$F+} (* Function must be defined as FAR! *) | function DosShell(Command: String): Integer; begin | SwapVectors; | if Command = '' then | Exec(GetEnv('COMSPEC'), '') | else | Exec(GetEnv('COMSPEC'), '/C ' + Command); | SwapVectors; | DosShell := DosError; end; | {$F-} | You can then assign ShellProc := DosShell to enable the Alt-J (shell to | DOS) key in AvDoor. String functions ---------------- | function UpCase(Ch: Char): Char; | This function will convert any lowercase letters (including accented | letters in the IBM graphic character set) into the corresponding | uppercase letters. Any other characters will be returned unmodified. | function LoCase(Ch: Char): Char; | This function will convert any uppercase letters (including accented | letters in the IBM graphic character set) into the corresponding | lowercase letters. Any other characters will be returned unmodified. function Upper(S: String): String; | This function will convert any lowercase letters in the string S | (including accented letters in the IBM graphic character set) into the | corresponding uppercase letters. It will also change any underscores | '_' into spaces. All other characters in the string S will be returned unmodified. function Lower(S: String): String; This function will convert any uppercase letters in the string S | (including accented letters in the IBM graphic character set) into the | corresponding lowercase letters. All other characters in the string S | will be returned unmodified. function Mixed(S: String): String; This function will convert any uppercase letters in the string S | (including accented letters in the IBM graphic character set) into the | corresponding lowercase letters. The first letter of each word, | however, and the first letter following the 'c' in any word starting | with either 'Mc' or 'Mac', will be converted to uppercase. A word is | defined as any sequence of alphanumeric characters. function RepChr(Ch: Char; N: Byte): String; This function will return a string consisting of N repetitions of the character Ch. | Time and date functions ----------------------- function Time: LongInt; This function will return the current system time in seconds past midnight. Accuracy is to the nearest BIOS timer tick. | function DateStamp: String; | This function will return the current system time, day of the week and | date as a string formatted correctly for the current country. Note | that the day of the week is always in English in the current release. Status Line procedures ---------------------- procedure StatLine; This procedure clears the status line (the bottom line of the local console) to black text on light grey, and displays (from left to right) the name and version number (if any) of the current program, the current baud rate or 'LOCAL', the current user's full name, 'LOG' if a chat is currently being logged, and the amount of time the user has remaining in this program or '[CHATTING]' if in chat mode. procedure UndoStat; This procedure clears the status line to black spaces, thus erasing it. procedure Update; | This procedure updates the amount of time remaining, displayed on the | right hand side of the status line, and should therefore be called | occasionally during lengthy operations without user input (it is | automatically called while waiting for a keystroke). This procedure | should never be called before StatLine or after UndoStat, so you should | also never request user input before calling StatLine or after calling | UndoStat. If called more often than once a second while running under | DesqView, it will relinquish excess time slices to increase efficiency. Output procedures ----------------- procedure Beep; | This procedure will ring the bell on the remote console. It will not | ring the local console bell unless the current user is logged on | locally (indicated by Baud = 0), or the last key pressed on the local | console was G (indicated by KeyCh = 34, since the scan code for the G | key will be returned irrespective of the Shift, Control and Alt keys). | procedure Newline; | This procedure will output a carriage return and linefeed (^M and ^J). procedure PutCh(Ch: Char); This procedure will output the character Ch to the local console and (if a remote user is online) to the remote console and (if logging) to a disk file. Word-wrapping will be performed if the global variable Wordwrap is True. The following characters will be handled specially: | ^G (control-G or bell) will call Beep as above. ^H (control-H or backspace) will move the cursor left one column if it is not already at the left margin. ^I (control-I or tab) will move the cursor right to the next column which is a multiple of eight; if the cursor is already past the last | such column, it will perform a Newline instead. ^J (control-J or linefeed) will move the cursor down one line, or scroll the entire screen up one line if already on the last line. ^K (control-K or reverse linefeed) will move the cursor up one line if | not already on the top line and if ANSI graphics are available. | ^L (control-L or formfeed) will reset the colour to light grey on | black, clear the entire screen, and home the cursor to the top left | corner. ^M (control-M or return) will move the cursor to the left margin of the current line. ^N (control-N or home) will home the cursor to the top left corner of the screen if ANSI graphics are available. | ^U (control-U) will move the cursor right one column if it is not | already at the rightmost column. This will work regardless of whether | ANSI graphics are available. ^X (control-X or cancel) will clear the current line and return the cursor to the left margin. | Del (character 127) will move the cursor to the left one column if it | is not already at the left margin, erasing the character now under the | cursor. procedure Put(S: String); This procedure will output the string S using the PutCh procedure. procedure PutLn(S: String); This procedure will output the string S using the PutCh procedure | followed by a Newline. procedure PutTab(C: Byte); This procedure will move the cursor to column C on the current line, whether or not ANSI graphics are available. procedure PutNum(N: Longint; W: Byte); This procedure will output the numeric variable N (of any scalar type | including Longint, Integer, Word, and Byte) right-padded with spaces to | a width of W characters using the PutCh procedure. If the value of N | (including a minus sign if necessary) will not fit into W characters, a | row of asterisks will be output instead. If W is zero, the value of N | will be output regardless of size and without any padding. | procedure PutMenu(Ch: Char); | This procedure will output two spaces and a left square bracket "[" in | light grey, the character Ch in yellow (or light grey if ANSI graphics | are not available), and a right square bracket "]" and a space in light | grey. This is intended to standardise the way menu choices are | presented to users in programs written with AvDoor. procedure PutANSI(Ch: Char); This procedure will output the character Ch using the PutCh procedure, but interpreting any of the following ANSI X.364 escape sequences: Esc [ A will move the cursor up one line Esc [ <n> A will move the cursor up <n> lines Esc [ B will move the cursor down one line Esc [ <n> B will move the cursor down <n> lines Esc [ C will move the cursor right one column Esc [ <n> C will move the cursor right <n> columns Esc [ D will move the cursor left one column Esc [ <n> D will move the cursor left <n> columns Esc [ H or Esc [ f will home the cursor (like ^N) Esc [ <n> H or Esc [ <n> f will move the cursor to row <n> - 1 Esc [ ; <n> H or Esc [ ; <n> f will move the cursor to column <n> - 1 on the top row Esc [ <r> ; <c> H or Esc [ <r> ; <c> f will move the cursor to row <r> - 1 and column <c> - 1 Esc [ J or Esc [ <n> J will clear the screen (like ^L) Esc [ K or Esc [ <n> K will clear to the end of the current row Esc [ <n>... m will change the current colour as follows: 0 = light grey on black 1 = bright foreground 2 = dim foreground 3 = blue foreground (italics on some terminals) 4 = blue foreground (underlined on some monochrome displays) 5 = blinking 6 = blinking (fast blinking on some terminals) 7 = black on light grey (reversed) 8 = black on black (hidden) 30 = black or dark grey foreground 31 = red foreground 32 = green foreground 33 = yellow or brown foreground 34 = blue foreground 35 = purple foreground 36 = cyan foreground 37 = white or light grey foreground 40 = black background 41 = red background 42 = green background 43 = brown background 44 = blue background 45 = purple background 46 = cyan background 47 = light grey background Esc [ s will save the current cursor position Esc [ u will restore the saved cursor position procedure ClrEol; This procedure will clear to the end of the current row (like Esc [ K) procedure ClrScr; | This procedure will set the colour to light grey and clear the entire | screen (like ^L or Esc [ J) procedure GotoXY(X, Y: Byte); This procedure will move the cursor to row Y column X, numbered from zero (unlike the ANSI X.364 numbering which starts from one). This procedure should NOT be called if ANSI graphics is not available since it will still send the ANSI escape sequences anyway! Input functions and procedures ------------------------------ function GotCh: Boolean; This function will return True if a character is ready for input. function RawCh: Char; This function will wait for a character to be input, calling Update regularly to keep the timer on the status line ticking. It will also check for time up, timeout (no response after two minutes) and carrier | loss. If there is no response after one minute it will output a Beep | to warn the user that they only have one more minute to respond before | being logged off. This timeout checking will not occur during chat | mode. KeyCh will be set to the scan code of the key pressed, AltPad if | the Alt-numeric keypad was used, or zero if the keystroke came from a | remote console. If a ^R character is received from a remote | console, the entire screen is immediately retransmitted. function GetCh: Char; This function will call RawCh and process incoming characters by | converting ^H into Del characters, converting ANSI X.364/VT100/VT52 | cursor sequences into control characters, moving the cursor | immediately after the last printable character on the current line | if the "End" key or ^O was pressed, echoing printable characters in | the appropriate colour, echoing received carriage returns (^M) as | newlines (^M plus ^J) and handling local Sysop commands as follows: Alt-C will enter chat mode (suspending the timer) Alt-G will send a random string of garbage (fake line noise) Alt-J will shell to DOS (if implemented in your program) Alt-L will toggle logging if in chat mode PgUp will increase the user's time left by one minute (max. 59) PgDn will decrease the user's time left by one minute (min. 1) function WaitCh(csecs: Word): Char; This function will wait up to csecs centi-seconds (hundredths of a second) for an input character, calling Update regularly to keep the timer on the status line ticking. If a character is ready before the delay is over it will be input using the GetCh function, otherwise character zero will be returned. function Fetch(Valid: String): Char; | This function will repeatedly input characters using the RawCh function | until one occuring within the string Valid is found (case independent). | If printable, it will then be echoed using the PutCh procedure. All | invalid characters input will merely cause a Beep to be output. A | Purge will be performed when a valid key is input, which will provide | "hot-key" support if a FOSSIL is installed. | function GetField(Mask: String): String; | This function will display the Mask in FldColour (light grey on blue) | and then allow input of as many printable characters as the length of | the Mask. Attempting to input characters beyond the end of the mask | will merely cause a Beep to be output. Backspaces will reveal the | underlying mask characters, and the cancel key (^X) will clear the | entire field and redisplay the mask. Carriage return (^M) or escape | will terminate the field entry, restoring the original colour and | outputting a Newline. procedure Flush; | This procedure will flush the FOSSIL output buffer (if any) and purge | all input buffers. When the procedure returns, all pending output | characters will have been sent, and any pending input characters will | have been ignored. procedure Purge; | This procedure will purge the FOSSIL output buffer, causing any pending | output characters to be thrown away immediately rather than sent. | There will be no effect at all if no FOSSIL is installed. Miscellaneous procedures ------------------------ procedure Pause; | This procedure will output '[ENTER]' in MorColour and then call Flush and GetCh. Once a character has been input it will erase the message. procedure Delay(csecs: Word); This procedure will delay up to csecs centi-seconds, calling Update | regularly to keep the timer on the status line ticking. Local sysop | keys will be processed during the delay. | procedure Colour(C: Byte); This procedure will change the current text colour to C unless ANSI graphics is not available, in which case it will merely change the current text colour to light grey on black. | procedure Effect(E: Effects); | This procedure will change the current effect (and hence colour) to one | of the following if ANSI graphics is available: | Normal (light grey on black) | Highlight (bright foreground) | Underline (blue foreground on colour displays, underlined on monochrome) | Blink (blinking foreground) | Reverse (black on light grey) | Hidden (black on black!) procedure Error(Msg: String); This procedure will change the current text colour to ErrColour and | display the error message string Msg on the local console. The Initialise procedure ------------------------ procedure Initialise(PN: String); This procedure is crucial. It MUST be called before any other AvDoor procedure or function can be used. It may only be called once. The string PN must contain the name of your program (max. 8 characters). It will parse the command line parameters (if any), read the BBS interface file (if requested), check for a registration key file (in | registered copies of AvDoor!), detect and initialise the FOSSIL (if any) | and display the copyright notice and (if necessary) a usage guide. | For example, when the sample program below is run: | MYPROG - Do something clever | Written 7 Feb 91 by Avatar of S.I.G. BBS | Ver 0.01 Copyright (c) 1991 Serious Cybernetics | Registered to Avatar, S.I.G. | Developed using AvDoor v1.10 Copyright (c) 1991 Serious Cybernetics | Running under Desqview(tm) v2.31 | Usage: MYPROG {options...} {username} {options...} | Options: /<baud> where <baud> = 0 for local | /<port> where <port> = 1 to 4 | /G<ANSI> where <ANSI> = 0 to 3 | /L<rows> where <rows> = length of user's screen (12 to 60) | /N<line> where <line> = BBS line number (1 to 99) | /T<time> where <time> = max time in MyProg (minutes) | /W<name> where <name> = filename of WWIV style chain file | /D => read GAP style DOOR.SYS file | /R => read RBBS style DORINFOn.DEF file | /W => read Wildcat style CALLINFO.BBS file | Other command line parameters not mentioned in the usage guide are: | /N without a line number will set the Process variable to the | current Desqview window number, or if not running under | Desqview, to the number of the serial port specified (one more | than the Port variable) which defaults to 1. | /R will read DORINFO1.DEF unless preceded by the /N parameter. | /R0 will read DOORINFO.DEF and set Process to 0 (single-tasking). | /R<line> will set Process to <line> and read DORINFOn.DEF where n | is the last digit of the BBS line number, exactly the same as | preceding the /R parameter with a /N parameter. Sample program skeleton ----------------------- program MyProg; uses AvDoor; begin Author := 'Avatar of S.I.G. BBS'; {Optional} ProgDesc := 'Do something clever'; {Optional} Written := '7 Feb 91'; {Optional} Version := '0.01'; {Optional} Initialise('MyProg'); {Essential!} StatLine; Colour(LtBlue); PutLn('Check this amazingly clever program - chat mode and all!'); Pause; UndoStat; end.