ftp.wwiv.com

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

/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / GAPQBDR.ZIP / GAPQBDR.TXT < prev next >

Wrap

Text File | 1994-01-05 | 100KB | 3,080 lines

GAP Communications Online Software GAPQBDR Door Interface Library For Quick Basic Programmers Copyright (C) 1987-1993 by GAP Development Company. ALL RIGHTS RESERVED. No part of this manual shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from GAP Development Company. While every precaution has been taken in the preparation of this manual, GAP Development Company assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. GAPQBDR is the sole and exclusive property of GAP Development Company. It is licensed and not sold to the end user with restrictions placed upon its use. GAPQBDR is copyrighted by GAP Development Company. DESQview is a trademark of Quarterdeck. PCBoard is a trademark of Clark Development Corporation. WildCat! is copyrighted by Mustang Software. DigiBoard is a trademark of DigiBoard Incorporated. TABLE OF CONTENTS Page DESCRIPTION 5 GETTING STARTED 6 COMPILING AND LINKING 12 SYSOP SETUP AND FUNCTIONS 13 GLOBAL VARIABLES 17 CONSTANTS 17 ANSI CONSTANTS 17 DOOR.SYS VARIABLES 18 INTEGERS 18 LONGS 18 STRINGS 18 GAPQBDR GLOBALS 19 INTEGERS 19 LONGS 19 STRINGS 19 GLOBAL VARIABLES - ALPHABETICALLY By Type 20 CONSTANTS 20 INTEGERS 20 LONGS 21 STRINGS 21 Page 3 FUNCTIONS AND SUBROUTINES - QUICK REFERENCE 22 FUNCTIONS AND SUBROUTINES - REFERENCE 23 INDEX 51 Page 4 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company DESCRIPTION ----------- GAPQBDR is a professional development kit for Bulletin Board Door programmers. It can also be used to facilitate the writing of stand alone communications programs. Written entirely in Quick Basic (with a little help from some Assembler support routines), it is fast, reliable, easy to use, and easy to incorporate into the serious programmer's source code. Features Include : o Interfaces with GAP Communications, PCBoard, WildCat or any BBS capable of writing a DOOR.SYS file. o Complete interrupt driven communications which does not require a DTR patched BRUNxx.EXE run time library. o Supports the DigiBoard COM/Xi Intelligent Serial Port Boards. o Supports the FIFO buffers of the 16550 UART. o Speeds to 57,600 bps. o Supports all communications ports. o Does not require watchdog or CTTY. o Uses ANSI colors instead of Basic's color statements so the sysop sees what the caller sees. o Maintains a scoreboard of the top 10 players. o High speed text file display. o Supports ANSI color and ASCII text files with no programming effort other than to make a single subroutine call. o Easy to use Random Number Generator. o Informative Status Line display. o Monitors keyboard activity and caller time remaining. o Easy interfacing to BBS system and user files. o Sysop chat with full word wrapping. o Allows the sysop to shell to DOS. o "Remembers" the default drive and directory which prevents file access errors. o Credits caller with time spent chatting or while sysop is in a DOS shell. o Sysop can twit caller without caller ever knowing the sysop is watching. o Caller time can be increased or decreased. o Time calculations are not dependent on the "seconds since midnight" and are thus unsusceptible to the midnight roll over. o Allows the sysop to "force" a file display. o Automatic detection of multi-user system. o Extremely easy interfacing to door programs. Page 5 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company GETTING STARTED --------------- GAPQBDR is distributed in archived format. The contents of the archive should be as follows: QBORDER.FRM - Registration Info and Order Form. GAPQBDR.TXT - This documentation. GAPQBDR.QLB - Library routines for QB 4.5 environment. GAPQBDR.LIB - Library routines for QB 4.5. GAPQBDR7.LIB - Library routines for Basic 7.x. GAPQBDR.BI - Door Interface include file. GAPQBERR.BI - Error Handling routines. DOOR.ZIP - Sample program illustrating many of the features of GAPQBDR. READ.ME - Any pertinent information which you should read. LIBLIB - Library Response File for QB 4.5. LIBLIB7 - Library Response File for Basic 7.x QLBLIB - Linker Response File for QB 4.5 QLBLIB7 - Linker Response File for Basic 7.x MAKE7QLB - Batch File to build Basic 7.x QLB file. MAKEBAS7.BAT - Batch File to build Basic 7.x LIB file. MAKESRC.BAT - Batch File to build 4.5 LIB & QLB files. If you licensed the source code to GAPQBDR, the following files are included in an archive called GAPQBSRC: ACCESS.BAS - Basic source for file access. CARRIER.BAS - Basic source for no carrier routines. DOCHAT.BAS - Basic source for sysop chat. GAPDOS.BAS - Basic source to read/write GAPDOS.DAT. GAPQBDR.BAS - Basic source for main GAPQBDR functions. GAPUSER.BAS - Basic source to read/write GAP USERS. GETRAND.BAS - Basic source for random number routines. INITDOOR.BAS - Basic source for door initialization. LEAVE.BAS - Basic source for closing the door. PCBSYS.BAS - Basic source to read/write PCBOARD.SYS. PCBUSER.BAS - Basic source to read/write PCB USERS. PUTCHAR.BAS - Basic source for character output. SCOREBRD.BAS - Basic source for scoreboard routines. SHOWFILE.BAS - Basic source for file display. STATUS.BAS - Basic source for the status line. SYSPAGE.BAS - Basic source for page sysop routines. TIMCRED.BAS - Basic source for time credits. WAIT.BAS - Basic source for time pauses. ATSAY.ASM - Assembler source for screen positioning. Page 6 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company CLS.ASM - Assembler source for clear screen. CTRLC.ASM - Assembler source for CTRL-C handler. CURSOR.ASM - Assembler code for cursor positioning. DOSPRINT.ASM - Assembler source for BIOS string output. GAPPUTS.ASM - Assembler source for string output. GETKEYC.ASM - Assembler source for keyboard input. KEYBRD.ASM - Assembler source for keyboard function. GAPQBSRC.BI - Global declarations for source files. LIBLIB - Library Response File for QB 4.5. LIBLIB7 - Library Response File for Basic 7.x QLBLIB - Linker Response File for QB 4.5 QLBLIB7 - Linker Response File for Basic 7.x MAKE7QLB - Batch File to build Basic 7.x QLB file. MAKEBAS7.BAT - Batch File to build Basic 7.x LIB file. MAKESRC.BAT - Batch File to build 4.5 LIB & QLB files. SRCREAD.ME - Any pertinent information which you should read. In addition, all the object modules for the private GAPQBDR functions are provided so that you may create the quick library. You will also need the file QB.BI which is distributed with the Microsoft QB disks. A DTR patched BRUN45.EXE is not needed since GAPQBDR uses its own communications routines. Place the files in your QB work directory. Make sure that QB.BI is accessible to the compiler. The source files should be placed in a directory called SOURCE (off of your QB directory). Throughout this document, the terms function, routine, procedure and subroutine are used interchangeably. However, pay close attention to the return value and the examples. In QB, a function returns a value, where as a sub program does not. If you use an external editor to write your programs, the editor must allow control characters to be entered and displayed. The ANSI constants are initialized by literal characters and if your editor removes the ESC character from the constants, your ANSI displays will be quite messy. If you are using the QB environment, you will need to load the door module along with your source program. To do so, type the following : QB door /L GAPQBDR (where door is the name of your basic source program) Page 7 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company If you fail to load the quick library along with your program, you will receive a great many "subprogram not defined" errors when you try to compile or run your program. We are a firm supporter of declaring all variables prior to their use. Not only does it make your programs easier to debug, it makes them easier to read and follow. We recommend that you follow our guidelines and declare all of your global variables at the beginning of your program, after including GAPQBDR.BI. At the very beginning of your program, you must include the GAPQBDR.BI file. Without this file, nothing will work. It must be the first directive in your source file. To include the file, you type the following at the beginning of your source program: '$INCLUDE: 'GAPQBDR.BI' Do not under any circumstances use the DEF type statements (I.E., DEFINT A-Z). This is the lazy persons method of programming. Typedef your variables by either declaring them ahead of time, or by appending the type after the name (i.e., A$, I%). If you need to use your own On Error routines, you should modify the supplied error handler rather than simply ignore it or replace it. If you subsequently change the Error Trap address, it is your responsibility to deal with any run time errors. After declaring any variables and functions, you must include the error handling file. The error handler is included in your source module so that it can be globally accessible by all routines in the GAPQBDR library. To include the file, type the following immediately AFTER declaring your global variables and BEFORE any executable statements: '$INCLUDE: 'GAPQBERR.BI' It is important that the error handling file be inserted at the proper place in your program. The file may not be included before your variable declarations and it MUST be included prior to your first executable statement. Please see the example program for a sample of how to include this file. Remember that a variable assignment is not a variable declaration but an actual executable statement. You are now ready to begin your program. You may now initialize your variables and start your program. Page 8 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company The first thing that must be done prior to using any of the door functions, is to initialize GAPQBDR itself. This is done by making a call to read.cnf. Read.cnf opens the configuration file (the name of which you pass as a parameter) and reads the first eight lines of the file. If the configuration file cannot be found, the program will end. The format of the configuration file is as follows: ----------------------------------------- C:\GAP The Crow's Nest BBS 4 03F8 STANDARD D000 320 4 The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The third line is the Port IRQ and the 4th line is the Port Base Address. If the sysop running your program has his BBS configured to use Com Ports other than 1 or 2, he would then enter the IRQ and Base address for his Com Port on lines 3 and 4. GAPQBDR derives the Port Number from the DOOR.SYS file. Lines five through eight are for the Intelligent DigiBoard multi- port Communications Card. The DigiBoard routines specifically support the COM/Xi series. All four of these lines are required even if your end users are using the Standard Interface. Line five is the Communications Port Interface. It must be one of the following: STANDARD DIGIBOARD INT14/EBIOS The Standard interface is the one that will normally be used. If an end user is using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most sysops will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (available from DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. GAPQBDR talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the DigiBoard once when the computer is first booted. If the end user does not have Page 9 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company this program (it is a part of the GAP Communications BBS package) then the Int14/EBIOS interface must be used. If the Interface is other than STANDARD, then lines 6 through 8 will be ignored. If the Interface is INT14/EBIOS, then lines 6 and 7 will be ignored. Line 6 is the DigiBoard Memory Window, or the address the board uses as a communications area between itself and the Host Computer. This line is used only if the Interface is set to DIGIBOARD. It can be set to 0 if the Interface is STANDARD or INT14/EBIOS. Line 7 is the DigiBoard I/O Port Address. This line is used only if the Interface is set to DIGIBOARD and can be set to 0 otherwise. Line 8 is the DigiBoard Channel Number. This line is required for the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8 for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS Interface. The Channel Number is similar to a Port Number. It tells the program which of the DigiBoard Communications ports to use. The configuration file is usually given a name similar to the name of your door program, with a CNF extension. Read.cnf will leave this file open for your use. If you have any configuration options of your own, you may place them in this file beginning with line 9. Do not read your configuration options until after making a call to init.door (which should be the second function call in your program). Upon return from init.door, you are free to read your configuration options (if any). At this time, you should close the configuration file. Its file number is #1. Normally, your program is invoked with a command line parameter giving the name of the configuration file to use: (I.E., DOOR DOOR.CNF). You would use the COMMAND$ function to extract the configuration parameter and then pass this parameter on to read.cnf. This allows the end user to use a single program (your program) with multiple configuration files. This is especially important under multi-user systems where separate configuration files are needed. The configuration file is opened as a sequential file so using Line Input #1 would be appropriate for reading any data. Page 10 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company If there were no errors, read.cnf will return. You must now make a call to init.door. Init.door uses the information derived from line 1 of the configuration file to open and read DOOR.SYS. In addition, init.door opens the communications port (if a remote user is on), initializes some global variables, initializes the random number generator, and installs the CTRL-C interrupt handler. If there is an error, init.door will not return. Instead it will end the program. That is basically all you have to do to initialize the GAPQBDR module. When your program ends, you should clean house if necessary and call leave. Leave closes the communications port and any open files, sends a sign off message to the caller, and then exits to DOS. Things to remember: To get the ball rolling, include GAPQBDR.BI as the first directive in your source program. Include GAPQBERR.BI after declaring any global variables and prior to your first executable statement. To initialize the door, call read.cnf with the name of your programs configuration file. Call init.door. Call leave when your program is finished. With the exception of file #1 which is used to read the configuration file and which YOU should close, there are no other files left open. GAPQBDR uses good programming practice by asking Basic for a file number rather than telling Basic which number to use. All input and output should be performed through the GAPQBDR functions. The sample program gives good examples on how to accomplish this. To determine if the BBS is a single or multi user system, check the variable called node. If it is anything other than 0, then the BBS is multi-user and you should read/write your data files with sharing attributes. To test your program, you will need a DOOR.SYS file that was written for local exit. Of course, you can always modify any DOOR.SYS file and change the first line so that it reads COM0:. A Page 11 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company complete set of sample files are provided for testing your program under local mode. Experience has shown that although the QB environment editor makes for a cumbersome programmers editor, testing programs inside QB is perhaps the easiest and most efficient way to test. The environment is wonderful for catching syntax errors and even more fantastic at allowing the programmer to correct those errors and continue to run the program. Do not use any of the Basic input/output or screen positioning functions. If you do, you will find that if you attempt to "print" a string, the string will not appear on the screen where you might think it should. This is because Basic maintains its own cursor location, and GAPQBDR does NOT update this information. All input/output should take place using the functions provided by GAPQBDR. Not only are they more efficient than Basics, they are faster as well! COMPILING AND LINKING --------------------- GAPQBDR has already been compiled with the necessary compile time switches. To compile your programs, use whatever switches are required by your program along with the /x (on error) switch which is needed for the error handling routine. Use the following commands: bc /x doorname; link doorname,,NUL.MAP,+gapqbdr Where doorname is the name of your program. Page 12 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company SYSOP SETUP AND FUNCTIONS ------------------------- These sysop setup and function descriptions should be placed in the documentation of your door program. You should, of course change the setup information to fit your particular needs. Door programs written with the GAPQBDR Door Interface Module will run on any BBS System that supports DOOR.SYS. To configure the door for a particular BBS setup, a configuration file must be used. At the very minimum, this file will contain eight lines. It may contain more than eight, depending upon a particular doors configuration requirements. The name of the file is usually the same as that of the door program but with a CNF extension. The minimum requirements for the file are as follows: C:\GAP The Crow's Nest BBS 4 03F8 STANDARD D000 320 4 The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The third line is the Port IRQ and the 4th line is the Port Base Address. If you have your BBS configured to use Com Ports other than 1 or 2, you would enter the IRQ and Base address for your Com Port on lines 3 and 4. GAPQBDR derives the Port Number from the DOOR.SYS file. Lines five through eight are for the Intelligent DigiBoard multi- port Communications Card. The DigiBoard routines specifically support the COM/Xi series. All four of these lines are required even if you are using the Standard Interface. Line five is the Communications Port Interface. It must be one of the following: STANDARD DIGIBOARD INT14/EBIOS The Standard interface is the one that will normally be used. If you are using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most sysops will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (available Page 13 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company from DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. GAPQBDR talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the DigiBoard once when the computer is first booted. If you do not have this program (it is a part of the GAP Communications BBS package) then the Int14/EBIOS interface must be used. If the Interface is other than STANDARD, then lines 6 through 8 will be ignored. If the Interface is INT14/EBIOS, then lines 6 and 7 will be ignored. Line 6 is the DigiBoard Memory Window, or the address the board uses as a communications area between itself and the Host Computer. This line is used only if the Interface is set to DIGIBOARD. It can be set to 0 if the Interface is STANDARD or INT14/EBIOS. Line 7 is the DigiBoard I/O Port Address. This line is used only if the Interface is set to DIGIBOARD and can be set to 0 otherwise. Line 8 is the DigiBoard Channel Number. This line is required for the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8 for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS Interface. The Channel Number is similar to a Port Number. It tells the program which of the DigiBoard Communications ports to use. GAPQBDR will obtain the sysop's name from the BBS configuration file. You must now create a batch file to invoke the door. This batch file is placed in your BBS default directory. Such a batch file might look like this: @echo off cd \gap\doors\tl tl tl.cfg cd \gap As you can see, the door is invoked by passing the configuration file name as a parameter. Page 14 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company You will also need to modify your doors menu files and the data file that tells the BBS what your doors are and the security level needed to access them. For GAP, these are respectively: DOORM DOORMG DOORS.DAT Please refer to your BBS documentation for details on setting these files up. If you are running multi-nodes, simply create a separate door configuration file for each node, and number them. For instance, for a 3 node system, you might have the following configuration files: TL1.CFG TL2.CFG TL3.CFG The only difference between the three would be the 1st line which points to the default directory for the particular node. The following sysop functions are available while awaiting keyboard input : F5 - Shell to DOS. F8 - Twit user and return to BBS. F10 - Initiate chat with user. CF10 - Answer user page bell. Home - Main user stats. End - Displays sysop keys available. PgDn - Secondary user stats. Up Arrow - Increase user's time remaining. Dn Arrow - Decrease user's time remaining. One of the nicer features about using the TWIT key, is the user is not told that "the sysop wants them to return to the BBS". Instead, a very plain and simple message of "returning you to the BBS" is displayed. This way, the user is given no indication that the sysop is hovering about. When using the F5 shell to DOS key, to return to the door program, simply type EXIT at the DOS command prompt. It is not necessary to change directories back to the door directory. GAPQBDR is smart enough to know which drive and directory the Page 15 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company door program is in and will reset the defaults upon return from DOS. The Up and Down Arrow keys increase and decrease the user's time respectively by 5 minutes for each press of the key. There is no indication of what is occurring (except by the fact the user's time remaining will change), so the sysop should try not to have a lead finger. The increase or decrease is effective only while the user is in the door. Since we are firm believers that the BBS system files belong to the BBS and should not be altered by any door program, updating the BBS system file is NOT automatic. If you wish that any decrease or increase in the user's time be made permanent, you may, after initializing the door, call the function that opens the system file. Keep track of any time credits during the door programs operation, then call the function that updates the BBS system file. Examples of how to do this are included in the sample program. Page 16 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company GLOBAL VARIABLES ---------------- All global variables (except for constants) are defined as COMMON SHARED. They are included in your program by including the file GAPQBDR.BI at the top of your source file. CONSTANTS --------- Constants are defined as - CONST name = constant value. NO Defined as 0 YES Defined as 1 ANSI CONSTANTS -------------- ANSI constants contain the actual ANSI color sequences. BLACK ANSI codes for Black BLUE ANSI codes for Blue BROWN ANSI codes for Brown CYAN ANSI codes for Cyan GREEN ANSI codes for Green MAGENTA ANSI codes for Magenta RED ANSI codes for Red WHITE ANSI codes for White BBLACK ANSI codes for Grey BBLUE ANSI codes for bright Blue BCYAN ANSI codes for bright Cyan BGREEN ANSI codes for bright Green BMAGENTA ANSI codes for bright Magenta BRED ANSI codes for bright Red BWHITE ANSI codes for bright White YELLOW ANSI codes for Yellow Page 17 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company DOOR.SYS VARIABLES ------------------ DOOR.SYS variables are initialized while reading the Door Interface Module, DOOR.SYS. These variables are available from door start up to door end. The DOOR.SYS variables are the door programmer's connection to the BBS. INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on bell Page Bell. 0 = off, 1 = on c.olor Color toggle. 0 = no color, 1 = color ok expert Expert mode. 0 = non-expert, 1 = expert l.ocal 0 = remote user, 1 = local level User's security level minsleft Number of minutes user has left at door start node Node number. 0 = single user page User's page length parity Should actually be data bits and is not used port Communications port in use printer Printer Toggle. 0 = off, 1 = on s.creen Screen display. 0 = off, 1 = on LONGS ----- baud DTE rate to open COMM port at downbytes Total bytes downloaded downloads Number of downloads maxbytes Maximum number of bytes allowed to download recnum User's record number in USER file timeson Number of times user has been on upbytes Total bytes uploaded uploads Number of uploads userbaud BPS rate of the remote user STRINGS ------- bphone User's business or data phone number city User's home town first User's first name hphone User's home phone number last User's last name lastdate Last date user was on Page 18 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company password User's password. PASSWORD if sysop is on subscrip Date user's subscription expires username User's full name GAPQBDR GLOBALS -------------- These variables are the documented, global variables (initialized and used by GAPQBDR). They may be modified and/or used at the programmer's discretion. INTEGERS --------- noup If set to 1, get.string will not uppercase timecredit Time credits for user (in minutes) timeleft Time user has left (in minutes) LONGS ----- starttime Time the user logged on (in seconds) temptime For calculating keyboard time out timenow Time it is now (in seconds) STRINGS ------- anystring1 Global garbage collector bbs.dir Path to BBS default dir birthday Callers birth date board.name Name of the BBS gendir Path to the gen directory maindir Path to the main directory sysname Sysop's name Page 19 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company GLOBAL VARIABLES - ALPHABETICALLY By Type ----------------------------------------- CONSTANTS --------- BBLACK ANSI codes for Grey BBLUE ANSI codes for bright Blue BCYAN ANSI codes for bright Cyan BGREEN ANSI codes for bright Green BLACK ANSI codes for Black BLUE ANSI codes for Blue BMAGENTA ANSI codes for bright Magenta BRED ANSI codes for bright Red BROWN ANSI codes for Brown BWHITE ANSI codes for bright White CYAN ANSI codes for Cyan GREEN ANSI codes for Green MAGENTA ANSI codes for Magenta NO Defined as 0 RED ANSI codes for Red WHITE ANSI codes for White YELLOW ANSI codes for Yellow YES Defined as 1 INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on bell Page Bell. 0 = off, 1 = on c.olor Color toggle. 0 = no color, 1 = color ok expert Expert mode. 0 = non-expert, 1 = expert l.ocal 0 = remote user, 1 = local level User's security level minsleft Number of minutes user has left at door start node Node number. 0 = single user noup 1 = get.string will not uppercase page User's page length parity Should actually be data bits and is not used port Communications port in use printer Printer Toggle. 0 = off, 1 = on s.creen Screen display. 0 = off, 1 = on timecredit Time credits for user (in minutes) timeleft Time user has left (in minutes) Page 20 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company LONGS ----- baud DTE rate to open COMM port at downbytes Total bytes downloaded downloads Number of downloads maxbytes Maximum number of bytes allowed to download recnum User's record number in USER file starttime Time the user logged on (in seconds) temptime For calculating keyboard time out timenow Time it is now (in seconds) timeson Number of times user has been on upbytes Total bytes uploaded uploads Number of uploads userbaud BPS rate of the remote user STRINGS ------- anystring1 garbage collector bbs.dir Path to BBS default dir birthday Callers birth date board.name Name of the BBS bphone User's business or data phone number city User's home town first User's first name gendir Path to the gen directory hphone User's home phone number last User's last name lastdate Last date user was on maindir Path to the main directory password User's password. PASSWORD if sysop is on subscrip Date user's subscription expires sysname Sysop's name username User's full name Page 21 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company FUNCTIONS AND SUBROUTINES - QUICK REFERENCE ------------------------------------------- a.ccess% Checks for the existence of a file. ansi Displays ANSI escape sequences. backspace Sends one or more backspaces. ckeypress% Checks for a remote or local key press. clear.scr Clears the local and remote screens do.chat To allow sysop to chat with remote user. elap.time Computes elapsed time. get.string Gets a string of characters. get.time& Returns number of seconds since 01/01/70. getakey% Gets one key responses. getrand% Returns a random number. init.door Initializes the Door. leave Shuts down door and returns to the BBS. more Checks for a full screen. nl Sends a CR/LF to local and remote. no.carrier Prints a message if carrier lost. pagesysop Alerts sysop that the user wants to chat. pause Sends a "Press [Any Key] To Continue" prompt. putachar Sends a single character. putkey Used by chat for word wrapping. read.cnf Reads the door configuration file. read.doorsys% Reads DOOR.SYS. read.gapuser% Reads USERS.DAT. read.pcbuser% Reads PCB USERS file. read.score% Reads and displays the scoreboard. right.trim$ Trims spaces from string. set.status Displays status line. show.file Displays text files. show.mess Displays a message. time.credit Gives credits for time used. time.left Computes time remaining. update.clock Updates status line clock. waitasec Pauses for x number of seconds. wrap.word Wraps a word. write.gapuser% Writes USERS.DAT. write.pcbuser% Writes PCB USERS. write.score Creates and maintains the scoreboard. Page 22 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company FUNCTIONS AND SUBROUTINES - REFERENCE ------------------------------------- Functions always return a value. The type of the return value is denoted by the type modifier after a function name. The return value should be assigned to a variable of the same type. For instance, the function get.time& returns a long integer. To re- trieve the return value, assign it to an long integer as : long.int& = get.time& Subroutines do not return a value. To call a subroutine, use the Basic CALL function : call get.string a.ccess% ----------------------------------------------------------------- Purpose Checks for the existence of a file. Parameters Full path and name of file Return Value 0 = file was found, 1 = file not found Description In order to avoid Basic errors that occur when trying to open a file that does not exist, this function should be used prior to opening any file. Example r% = access%("GAPQBDR.DOC") if r% <> 0 then call show.mess("Can't Find GAPQBDR.DOC",NO,YES) end if Page 23 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company ansi ----------------------------------------------------------------- Purpose Displays ANSI escape sequences Parameters ANSI color to display Return Value None Description This function will send a string of ANSI escape sequences to the remote user and to the local console. The ANSI codes for the various colors are defined as constants in the GAPQBDR.BI file. If the remote or local user is in non graphics mode, the function returns immediately. Example call ansi(BWHITE) backspace ----------------------------------------------------------------- Purpose Sends one or more backspaces Parameters Number of backspaces to send Return Value None Description In order to actually erase a character on the screen, you must send a 3 character sequence which consists of backspace, space, backspace. This function will send as many of these 3 character sequences as you specify in the parameter list. Example call backspace(1) str$ = "Press Any Key " ' set up string call show.mess(str$,NO,NO) ' show string c% = getkeyc% ' get a key call backspace(len(str$)) ' erase string Page 24 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company ckeypress% ----------------------------------------------------------------- Purpose Checks for a remote or local key press Parameters None Return Value 0 = no key is waiting, 1 = a key is waiting Description This function will check the local keyboard as well as the communications receive buffer to see if a key is waiting to be read. It is most often used in loops that need to receive a 1 character keystroke. Example c% = ckeypress% ' key pressed? c% = 0 ' initialize do | ' do something | c% = ckeypress% ' key pressed? until c% <> 0 ' key pressed,exit clear.scr ----------------------------------------------------------------- Purpose Clears local and remote screens. Parameters None Return Value None Description This routine will call CLS23 to clear the local screen. If the remote caller is in non-color mode, it sends a CHR$(12) to the remote screen, otherwise it sends the ANSI clear screen sequence. Example call clear.scr ' clear screen Page 25 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company do.chat ----------------------------------------------------------------- Purpose To allow sysop to chat with remote user Parameters None Return Value None Description This function allows a one on one chat with a re- mote user. If the caller is in graphics mode, the sysop's key presses will be displayed in green and the remote user's key presses will be displayed in white. Text will automatically wrap at column 76. To exit chat, press either the ESC key or type a CTRL-X. Note that the user may also send these characters to end chat. The user will receive full credit for the time spent chatting with the sysop. However, this function will not update the BBS system file so it is possible that the user may be logged off (with an out of time message) when he/she returns to the BBS. Example call do.chat response$ = " " ' initialize call get.string(response$) ' get a string if response$ = "P" then ' paging sysop call do.chat ' chat with sysop end if Page 26 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company elap.time ----------------------------------------------------------------- Purpose Computes elapsed time while waiting for keyboard input Parameters None Return Value None Description This function is used in loops that await a key- board response. Prior to entering the loop, the variable called temptime should be initialized with the current time. Once inside the loop, this function should be called to keep track of the elapsed time. If there is no keyboard response within 4 minutes, the user will be logged off. Example call elap.time temptime& = get.time& ' start timer do gc = getakey% ' get a key if gc <> 0 then ' key pressed exit do ' exit and process end if call elap.time ' activity? loop ' continue Page 27 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company get.string ----------------------------------------------------------------- Purpose Gets a string of characters Parameters String to fill Return Value None Description This is the main input routine. It will get a string from either the remote user or the local keyboard. The string passed will be set to the characters received. The length of the input string is determined by the length of the string passed. Do not pass a fixed length string to this routine. Before calling, you must initialize the passed string with spaces. The number of spaces in the string determines the number of characters allowed to be input. If a user attempts to type more characters than allowed, the cursor will not move pass the end of the string. Input ends when the Enter key is pressed. To initialize the string, use the Basic space$ function (IE, input$ = space$(10) - initializes input$ to 10 spaces). WARNING : It is extremely important that the passed string be initialized. Failure to set the string to spaces, will cause unpredictable results! This function does not return a new string con- taining the keyboard input. Instead, it modifies the string you pass to it in the parameter list. The string will be stripped of any trailing spaces. get.string automatically uppercases the string. If you wish to disable this feature, set the variable noup to 1. get.string will automatically check for keyboard activity so it is not necessary for you to do so. Example instr$ = space$(10) ' initialize call get.string(instr$) ' get string Page 28 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company get.time& ----------------------------------------------------------------- Purpose Gets the number of seconds elapsed since 01/01/70 Parameters None Return Value Number of seconds since 01/01/70 Description This routine is equivalent to the C time() func- tion. It is used throughout the GAPQBDR module to compute various times. This function is not sus- ceptible to the midnight roll over problem so prevalent in Basic communications programs. Note that the Return Value is of type LONG. You must cast the Return Value to a LONG INTEGER or loss of significant digits will result. Example dim ltime as long ' declare as long ltime = get.time& ' get the time ' if you don't like declaring variables, you can ' do it the old fashioned way longtime& = get.time& ' get the time Page 29 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company getakey% ----------------------------------------------------------------- Purpose Gets one key responses Parameters None Return Value ASCII code for the key pressed or 0 Description This is the main keyboard input routine (internal). It is called by get.string as well as any keyboard polling loops. It checks the receive buffer as well as the local keyboard for a key press. If one is not found it returns 0. The character input is not echoed. Since 99% of all keyboard input comes from this routine, it checks for carrier, time remaining, keyboard time-out, as well as special sysop function keys. The "timeleft" variable is updated via this routine. This is the variable you would normally use in a prompt such as, [20 mins left] Main Command : Example c% = getakey Page 30 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company getrand% ----------------------------------------------------------------- Purpose Gets a random number Parameters Low number, high number Return Value A random number Description This routine is provided because it is much easier to use and understand than Basic's random function. Provide as parameters two integers. The first parameter is the lowest number you will accept as a random number, and the second parameter is the highest random number you will accept. The function will return a random integer between the range specified (low and high are included in the range of numbers). It is not necessary to seed the random number generator as this is done automatically for you during program initialization. Example ' get a random number between 1 and 10 rndnum% = getrand% (1,10) Page 31 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company init.door ----------------------------------------------------------------- Purpose Initializes the GAPQBDR functions Parameters None Return Value None Description This routine must be called immediately after calling read.cnf. It initializes the door, opens and reads system files, initializes the comm port, initializes global variables and in general, makes sure that all of the files required for operation are present. There is no Return Value. If an error occurs while trying to initialize, the function will display an error message and end the program. Example call read.cnf("DOOR.CFG") ' read config file call init.door ' init the door leave ----------------------------------------------------------------- Purpose Exits the program Parameters None Return Value None Description When the program terminates, it must call this function to end. This is the ONLY proper exit from the door. Example call leave Page 32 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company more ----------------------------------------------------------------- Purpose Checks for a full screen and issues a More Prompt Parameters None Return Value None Description This is an internal routine that is called by the character output functions. Example nl ----------------------------------------------------------------- Purpose To send a Carriage Return and Line Feed to local and remote Parameters Number of New Line's to send Return Value None Description To send a blank line, call this routine with the number of blank lines you wish to send. Example call nl(2) ' send two blank lines Page 33 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company no.carrier ----------------------------------------------------------------- Purpose Prints a message and calls leave() Parameters None Return Value None Description Internal routine that is called when there is a loss of carrier. Displays a message to the local screen and then calls leave to terminate the program. If you have a routine that checks for carrier and you wish to display the standard "No Carrier" message and log the user off, call this function. Example call no.carrier pagesysop ----------------------------------------------------------------- Purpose Alerts sysop that user wants to chat Parameters None Return Value None Description Allows the programer to provide the user with a Page Sysop command. The page lasts for 30 seconds and can be aborted by typing CTRL K. If the sysop's page bell is on, the sysop's speaker will also sound. To answer the page, the sysop should press CTRL F10. Example response$ = " " ' initialize var call get.string(response$) ' wait for a key if response$ = "P" then ' wants to chat call pagesysop ' tell sysop end if Page 34 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company pause ----------------------------------------------------------------- Purpose Sends a "Press [Any Key] To Continue" prompt Parameters None Return Value None Description This function sends a pause prompt and waits for a key press. Example call nl(1) ' send blank line call pause ' wait for a key putachar ----------------------------------------------------------------- Purpose Send a single character to local and remote Parameters ASCII character to send Return Value None Description This routine is called a "semi-unfiltered" char- acter output routine because it allows for most ASCII characters to be output. Example c% = ASC("A") ' send an 'A' call putachar(c%) ' to local and remote screen c% = getakey% ' get a keypress if (c% <> 0 then ' if we got a key call putachar(c%) ' display the end if ' character Page 35 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company putkey ----------------------------------------------------------------- Purpose Used by chat routines to keep track of word wrapping Parameters Character to send Return Value None Description This is the main output routine for the chat functions. It keeps track of the current column, and decides when it is time to wrap a word. It should not be called by the programmer's routines since putachar is faster and more efficient. Example Page 36 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company read.cnf ----------------------------------------------------------------- Purpose To read the door configuration file Parameters Full path and file name to the configuration file. Return Value None Description Opens the configuration file for the current door. Normally the passed parameter is the name of the door with a .CNF extension (it is assumed that the file is in the same directory as the door program). If an error occurs, the program ends immediately. The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The third line is the Port IRQ and the 4th line is the Port Base Address. If the sysop running your program has his BBS configured to use Com Ports other than 1 or 2, he would then enter the IRQ and Base address for his Com Port on lines 3 and 4. GAPQBDR derives the Port Number from the DOOR.SYS file. Lines five through eight are for the Intelligent DigiBoard multi-port Communications Card. The DigiBoard routines specifically support the COM/Xi series. All four of these lines are required even if your end users are using the Standard Interface. Line five is the Communications Port Interface. It must be one of the following: STANDARD DIGIBOARD INT14/EBIOS The Standard interface is the one that will normally be used. If an end user is using a DigiBoard then either the DigiBoard or Int14/EBIOS interface may be selected. Most sysops will use the Int14/EBIOS interface. All input/output to the DigiBoard is performed via Interrupt 14 calls and a Device Driver (available from DigiBoard) handles the interface between the program and the board. The DigiBoard interface uses Direct Programming. GAPQBDR talks to the board directly without the need for a Device Driver. In order to use this interface, a program called RESETDIG.EXE must be used in the AUTOEXEC.BAT file to reset the Page 37 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company DigiBoard once when the computer is first booted. If the end user does not have this program (it is a part of the GAP Communications BBS package) then the Int14/EBIOS interface must be used. If the Interface is other than STANDARD, then lines 6 through 8 will be ignored. If the Interface is INT14/EBIOS, then lines 6 and 7 will be ignored. Line 6 is the DigiBoard Memory Window, or the address the board uses as a communications area between itself and the Host Computer. This line is used only if the Interface is set to DIGIBOARD. It can be set to 0 if the Interface is STANDARD or INT14/EBIOS. Line 7 is the DigiBoard I/O Port Address. This line is used only if the Interface is set to DIGIBOARD and can be set to 0 otherwise. Line 8 is the DigiBoard Channel Number. This line is required for the DIGIBOARD and INT14/EBIOS Interfaces. It is normally 1 - 8 for the DIGIBOARD Interface and 4 - 11 for the INT14/EBIOS Interface. The Channel Number is similar to a Port Number. It tells the program which of the DigiBoard Communications ports to use. It is the responsibility of the door author to describe the format of these eight lines to the end user. It is also the responsibility of the door author to insure that the end user have these eight lines in the door configuration file. If your door program requires no configuration parameters of its own, you can simply distribute a sample "door".cnf file with these eight lines already in it. GAPQBDR will NOT close this file (file #1) after reading the first eight lines. It leaves the file open for the programmer's use. If your door does require certain configuration parameters, have your users place the parameters in the file starting with line 9. If you use a set up program, be sure that your set up program writes the first eight lines as specified. After you have called read.cnf and init.door, if you have any configuration options in the Page 38 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company "door".cnf file, you should line input those op- tions. Then close file #1. Even if you have no options to read, close the file. WARNING : You MUST call this routine before using any of the GAPQBDR functions. After calling this routine, you MUST call init.door. Example call read.cnf("TOURIST.CNF") call init.door read.doorsys% ----------------------------------------------------------------- Purpose Reads the DOOR.SYS universal door interface file Parameters None Return Value 0 = no error, 1 = error Description Internal routine called by init.door. Reads the DOOR.SYS file and initializes any global variables that depend on the information in that file. Example c% = read.doorsys% read.gapuser% ----------------------------------------------------------------- Purpose Reads the GAP Communications USERS.DAT file Parameters None Return Value 0 = no error, 1 = error Description Reads the user record of the current user in the GAP USERS.DAT file. The record variables are contained in a variable called user. Example c% = read.gapuser% Page 39 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company read.pcbuser% ----------------------------------------------------------------- Purpose Reads the PCB USERS file. Parameters None Return Value 0 = no error, 1 = error Description This function will read the PCB Users record for the user currently in the door. Example c% = read.pcbuser% read.score% ----------------------------------------------------------------- Purpose Reads and displays the top 10 player file. Parameters Filename to read, message to display. Return Value 0 = ok, 1 = file not found Description This function reads the scoreboard file and displays it to the caller. Pass as the first parameter, the name of the scoreboard file. The second parameter is a string to display prior to showing the actual scores. Example c% = read.score% ("SCORE.DAT","Top 10 Players") if c% = 1 then call show_mess("No winners yet!",NO,YES) end if Page 40 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company right.trim$ ----------------------------------------------------------------- Purpose Trims spaces from the end of NULL terminated strings Parameters String containing the spaces. Return Value String without the spaces. Description This function will remove the NULL and trim any spaces from the right end of any 'C' string. Example username$ = right.trim$(user.fname) set.status ----------------------------------------------------------------- Purpose To display and update the sysop status line Parameters 0 = set the status line, 1 = update the status line, 4 = show other user stats Return Value None Description This routine is used internally. There should be no reason to call it unless you have modified a user's stats and you need to update those stats on the status line. In this case, you should use option 0. Example call set.status(0) Page 41 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company show.file ----------------------------------------------------------------- Purpose To display a text file Parameters The full path and file name to the file to be shown Return Value None Description Many door programs have welcome, news, exit, help and other files to show to the user at various points in the program. This is the function that allows you to do that. This function tries to be as intelligent as it possibly can in determining the sysop's wishes. To display a file to the user, call the function with the full drive\path\filename of the file to display. If you have color and non-color versions of files pass the name of the non-color version as this function will automatically append a "G" to the filename if the user is in color mode. In fact, this function will ALWAYS try to find a file with a "G" appended to the end of the name (if the user is in color mode) before it looks for the actual file by the name you specified. If you pass "WELCOMEG" to this function and the user is in color mode, it will first try to find a file with the name of "WELCOMEGG". As with GAP Communications, your text files can have certain control characters as the first character in the file. A "{" signals that the more prompt should never display. In other words, GAPQBDR will not keep track of the number of lines displayed and will never issue a more prompt. This is useful for very long ANSI files. A "@" signals that the pause prompt should be displayed when the screen is full instead of a more prompt. This is very handy when you want the user to see the file in its entirety. The user will not be allowed to break out of the file read. WARNING : The "{" or "@" MUST appear as the VERY first character in the file. If you use an ANSI editor, be aware that the first few characters in a file will usually be an ANSI color sequence. You Page 42 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company normally have to edit the file with a text editor to insert the control character. Because QB 4.x is EXTREMELY slow when it comes to function calls, all input and output is done "in line". Despite QB's high overhead, this function is pretty fast. GAPQBDR does not have the ability to protect the status line. Because of this, it is possible for an ANSI file that contains clear screen codes to erase the status line. At the end of the function, the status line will be re-drawn just in case. Since most ANSI files contain the clear screen codes at the beginning of the file, show.file will remove any such codes during the first read of the file. Pressing CTRL K or CTRL X will abort any file display if the file does not begin with a "@". REMEMBER : If you have both color and non-color versions of the same files, pass the name of the non-color version. Also, the actual disk files must be named in such a way that they have no file extension and the color version ends with a "G". Example call show.file("WELCOME") call show.file("C:\GAP\GEN\WELCOME") Page 43 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company show.mess ----------------------------------------------------------------- Purpose Displays a message Parameters Message, ring the bell, issue a New Line Return Value None Description Finally! After all of this, just how do you dis- play a message to the user? Well, here it is. This is the string output function for GAPQBDR. Under most circumstances, this is the one function that you would call to display output to the user. There should be no reason to ever call putkey or putachar, as they are basically internal routines. There should be no reason to EVER use the Basic print statement unless you need to display a mes- sage to the local screen that you do not want the remote user to see. In other words, ALL string output should be done through this function. If there is a reason to display information locally it would be much easier and more efficient to keep track of the l.ocal variable, set it to 1, call show.mess with the strings to be displayed, then restore the l.ocal variable to what it was before, instead of using the print function which cannot display ANSI sequences (forcing you to translate ANSI codes to color statements). The three parameters are : 1 - the string to display 2 - YES or NO if you want to sound the remote user's bell. 3 - YES or NO if you want to issue a CR/LF after displaying the string. Page 44 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company Example ' the first show.mess displays the string and leaves the ' cursor on the same line. The second show.mess displays ' the string, rings the remote user's bell, and drops the ' cursor to the next line. call nl(1) call show.mess("Are you ready? (Y/N) : ",NO,NO) a$ = space$(3) call get.string(a$) if left$(a$,1) = "Y" then ' begin whatever it is you want to begin else call nl(1) call show.mess("Too Bad!",YES,YES) end if Page 45 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company time.credit ----------------------------------------------------------------- Purpose Keeps track of time and credits the user with time elapsed Parameters 1 = start timer, 0 = end timer Return Value None Description This is basically an internal routine called by chat and sysop shell to DOS so that the user is not penalized for time used. It updates a global variable called timecredit. Timecredit is used in the calculations that determine the user's time remaining. If you wish to use this feature in your own rou- tines, prior to entering your routine, call time.credit with a 1 and it will start the timer. When your routine is finished, call time.credit with a 0 and the timer will stop. The variable timecredit will be updated with the elapsed time. Example call time.credit(1) ' start the timer call do.chat ' chat with user call time.credit(0) ' stop the timer ' Note that this is simply an example. do.chat ' calls time.credit on its own. In the above ' example, if the sysop chat with the user took ' 10 minutes, the user will be credited with ' that 10 minutes as will be reflected in the ' timecredit variable. Page 46 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company time.left ----------------------------------------------------------------- Purpose To compute the user's time remaining Parameters None Return Value None Description This is the routine that is called by the input and output routines to compute the user's time remaining. It is not necessary for the programmer to call this routine directly. A global variable called timeleft will be updated with each call. This variable may be used in prompts that display the user's remaining time. As long as all input/output is performed thru calls to the GAPQBDR library, the timeleft variable will always be current. Example call time.left update.clock ----------------------------------------------------------------- Purpose Updates the status line clock Parameters None Return Value None Description Internal routine to update the status line clock. Example Page 47 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company waitasec ----------------------------------------------------------------- Purpose Pauses for the number of seconds specified. Parameters Number of seconds to pause Return Value None Description This function allows you to pause all processing for the specified number of seconds. It is in- sensitive to processor speed and is immune to the midnight rollover problem. Example call waitasec(10) ' pause for 10 sec wrap.word ----------------------------------------------------------------- Purpose To wrap a word during sysop chats Parameters None Return Value None Description Internal function called by putkey to wrap words. Example Page 48 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company write.gapuser% ----------------------------------------------------------------- Purpose Updates the user record in GAP's USERS.DAT file Parameters None Return Value 0 = no error, 1 = error Description This function allows you to update any variables in the GAP USERS.DAT file for the current user. WARNING : The GAP USERS.DAT file contains C char- acter arrays. These are equivalent to Basic's fixed length strings with the exception that the C strings have a NULL character (chr$(0)) in the last position. If you modify any of these fixed length strings, you MUST make sure that the string is fully padded with spaces and that the NULL character is placed in the last string position. When assigning a value to a fixed length string, Basic will automatically pad the fixed length string with spaces. All the programmer need to is insure that the NULL is inserted at the end of the string. WARNING : The indexes for the user file consists of the user's last name, first name, level, and handle. Do not under any circumstances modify either of these four fields. Doing so will cause corruption of the Index file. Example ' Increase # of Files User has downloaded c% = read.gapuser% ' 1st read record user.downloads = user.downloads + 2 c% = write.gapuser% ' update the record Page 49 GAPQBDR (C) Copyright 1988-1993 The GAP Development Company write.pcbuser% ----------------------------------------------------------------- Purpose Updates the PCB USERS file Parameters None Return Value 0 = no error, 1 = error Description This function allows the programmer to update the PCB USERS File. Note that you will need to use MKSMBF on the field lastmsg, and MKDMBF on the fields downbytes and upbytes, if you modified these fields since reading the file. Example c% = write.pcbuser% ' write the file write.score ----------------------------------------------------------------- Purpose Creates and maintains the scoreboard file. Parameters Filename to write, score to write. Return Value None Description This function will create and maintain a data file of the top 10 scores. You pass as parameters, the name of the file to use as the scoreboard file, and the score to write. The score is a long integer. The name and date are already known. If the file does not exist, it will be created. Example DIM score AS LONG score = 45600 write.score("SCORE.DAT",score) Page 50 INDEX ----- @ 42 { 42 A.ccess% 23 ANSI 5, 7, 17, 20, 24, 42, 44 Backspace 24 Base address 9, 13, 37 Bell 44 Chat 5, 26, 34, 36, 46, 48 Ckeypress% 25 Clear.scr 25 COMMAND$ 10 Communications base address 9, 13, 37 configuration file 9, 13, 37 IRQ 9, 13, 37 Communications port 11 Configuration file 10, 11 Do.chat 26 DOOR.SYS 9, 11, 13, 18, 22, 37 Elap.time 27 Error 8, 11, 23, 32, 37 Files Aborting 43 Color 42 Configuration 11, 37 DOOR.SYS 9, 13, 37, 39 Errors 23 Include 8, 11 Opening 23 PCB USERS 40 Showing 42 System 26, 32 USERS.DAT 39, 49 Functions 23 Get.string 19, 26, 28, 30, 34, 45 Get.time& 29 Getakey% 30 Getrand% 31 Global Variables Constants ANSI BBLACK 17 BBLUE 17 BCYAN 17 BGREEN 17 BLACK 17 BLUE 17 BMAGENTA 17 Page 51 INDEX ----- BRED 17 BROWN 17 BWHITE 17 CYAN 17 GREEN 17 MAGENTA 17 RED 17 WHITE 17 YELLOW 17 General NO 17 YES 17 Integers DOOR.SYS alarm 18 bell 18 c.olor 18 expert 18 l.ocal 18 level 18 minsleft 18 node 18 page 18 parity 18 port 18 printer 18 s.creen 18 General noup 19 timecredit 19 timeleft 19 Longs DOOR.SYS baud 18 downbytes 18 downloads 18 maxbytes 18 recnum 18 timeson 18 upbytes 18 uploads 18 userbaud 18 General starttime 19 temptime 19 timenow 19 Strings DOOR.SYS Page 52 INDEX ----- bphone 18 city 18 first 18 hphone 18 last 18 lastdate 18 password 19 subscrip 19 username 19 General anystring1 19 bbs.dir 19 board.name 19 gendir 19 maindir 19 sysname 19 Init.door 10, 11, 32, 39 IRQ 9, 13, 37 Leave 11, 32 MKDMBF 50 MKSMBF 50 More 33 New Line 33, 44 Nl 33 No.carrier 34 Node 11 Noup 28 Pagesysop 34 Pause 35, 48 PCB USERS 22 Putachar 35, 44 Putkey 36, 44 Read.cnf 9, 10, 11, 37 Read.doorsys% 39 Read.gapuser% 39 Read.pcbuser% 40 Read.score% 40 Right.trim$ 41 Set.status 41 Show.file 42 Show.mess 24, 44 Spaces Trimming 41 USERS.DAT 49 Status Line 5, 41, 43, 47 String output 44 Subroutines 23 Time.credit 46 Page 53 INDEX ----- Time.left 47 Timecredit 46 Timeleft 30, 47 Trimming Spaces 41 Update.clock 47 USERS.DAT 22 Waitasec 48 Wrap.word 48 Write.gapuser% 49 Write.pcbuser% 50 Write.score 50 Page 54