Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / GAPCDR.ZIP / GAPCDR.TXT < prev next >

Wrap

Text File | 1989-03-17 | 130.1 KB | 3,367 lines

GAPCDR Door Interface Module - March 15, 1989 A Professional Development Kit For The Professional Programmer (C) Copyright 1989 The GAP Development Company ALL RIGHTS RESERVED TABLE OF CONTENTS Page DESCRIPTION 2 GETTING STARTED 3 COMPILING AND LINKING 6 SYSOP SETUP AND FUNCTIONS 8 GLOBAL VARIABLES 11 DEFINES 11 ANSI VARIABLES 11 DOOR.SYS VARIABLES 12 INTEGERS 12 LONGS 12 STRINGS 13 GAPCDR GLOBALS 13 CHARS 13 INTEGERS 13 LONGS 13 STRINGS 14 GAPDOS.DAT VARIABLES 14 USERS.DAT VARIABLES 15 PCBOARD.SYS VARIABLES 16 PCB USERS VARIABLES 17 GLOBAL VARIABLES - ALPHABETICALLY By Type 18 DEFINES 18 CHARS 18 DOUBLES 18 FLOATS 18 INTEGERS 19 LONGS 19 STRINGS 20 FUNCTIONS - QUICK REFERENCE 22 FUNCTIONS - REFERENCE 23 REGISTRATION INFORMATION 46 GAPCDR REGISTRATION 47 INDEX 48 GAPCDR (C) Copyright 1989 The GAP Development Company DESCRIPTION ----------- GAPCDR is a professional development kit for Bulletin Board Door programmers. Written in Microsoft C version 5.1 and MASM version 5.1, it is fast, reliable, easy to use, and easy to incorporate into the serious programmer's source code. It consists of a set of C and assembler library routines to allow for easy door programming and interfacing. The communications routines are moulded around GAPCDR and, as such, will work only within the GAPCDR environment. Features Include : o Interfaces with GAP Communications and pcboard. o Full communications support. o Supports CTS/RTS, automatically. o Does not require watchdog or CTTY. o Uses ANSI colors so the sysop sees what the caller sees. o High speed text file display. o Supports ANSI color and ASCII text files with no programming effort other than to make a single function 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 Full programmer control of whether or not to update the BBS system files. o Time calculations are not dependent on the "seconds since midnight" and are thus unsusceptible to the midnight roll over. o Timer routines are hardware independent. o Allows the sysop to override the "more" prompt during file shows. o Allows the sysop to "force" a file display. o Automatic detection of multi-user system. o Input routines are consistent throughout the program. o Uses the latest in Microsoft C features. o Extremely easy interfacing to door programs. Page 2 GAPCDR (C) Copyright 1989 The GAP Development Company GETTING STARTED --------------- GAPCDR is distributed in archived format. The contents of the archive should be as follows: GAPCDR.TXT - This documentation. GAPCDRS.LIB - Small model Library routines. GAPCDRL.LIB - Large model Library routines. GAPCDR.H - Door Interface include file. GAPSTRUC.H - Door Interface include file. CDOOR.ZIP - Sample program illustrating many of the features of GAPCDR. READ.ME - Any pertinent information which you should read. If you purchased the source code to GAPCDR, the following files are included in an archive called GAPCSRC: GAPCDR.C - C source. ANSI.H - Initialized ANSI strings. MAKECDR.BAT - Batch file for compiling the source modules and creating libraries. In addition, you will of course need a C environment set up on your hard disk. The following environment was used in the creation of GAPCDR: DIRECTORIES ----------- C:\MSC Parent Directory for Microsoft C. C:\MSC\BIN Holds all Microsoft Executable files. C:\MSC\INCLUDE Holds all header files for C. C:\MSC\LIB All completed libraries are placed here. C:\MSC\TMP For use by the compiler. C:\GAPCDR Work directory for compiling GAPCDR. C:\DOORS Directory for testing door programs. DOS ENVIRONMENT --------------- TMP=C:\MSC\TMP INCLUDE=C:\MSC\INCLUDE LIB=C:\MSC\LIB LINK=/E /F /PACKCODE DOS PATH --------- PATH=C:\;C:\DOS;C:\MSC\BIN The C compiler used is MSC 5.1. The Linker used is LINK.EXE version 4.06. (It comes with QC 2.0). Note that this linker has a bug in that you must spell out PACKCODE (previous versions Page 3 GAPCDR (C) Copyright 1989 The GAP Development Company allowed PACK, as per the manual). The linker supplied with MSC 5.x will do just fine. The C runtime libraries were set up to use the alternate floating point library, and the C modules in GAPCDRx.LIB were compiled with the /FPa switch. Place the GAPCDR files in your work directory. You may place the LIB files in the MSC\LIB directory. The text editor you use must allow control characters to be entered and displayed. The GAPCDR.C source module contains the declarations for the ANSI strings which are initialized with literal characters and if your editor removes the ESC character from the strings, your ANSI displays will be quite messy. At the very beginning of your program, you must include the GAPCDR.H file. Without this file, nothing will work. It is normally included after the C header files that your program may need. To include the file, you type the following after including the regular C header files: #include "gapcdr.h" GAPCDR.H contains the declarations for the external global variables. In addition, it includes GAPSTRUC.H which contains the structure declarations and the function prototypes. NOTE: any of your source modules that include GAPCDR.H, MUST have an include declaration for STDIO.H prior to including GAPCDR.H. It should be standard practice to include stdio.h in your source modules anyway, so this shouldn't present any problems. The first thing that must be done prior to using any of the door functions, is to initialize GAPCDR 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 two 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 The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. 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 3. Do not read your configuration options until after making a call to init_door (which should be the second function Page 4 GAPCDR (C) Copyright 1989 The GAP Development Company 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 pointer is returned by read_cnf. Normally, your program is invoked with a command line parameter giving the name of the configuration file to use: DOOR DOOR.CNF You would use the argv parameter to your main 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 stream, so using fgets or any of the stream input functions would be appropriate for reading the data. Remember that the file pointer is passed back to you after the call to read_cnf. An example of the first few "door" statements that might appear in a source file would be: FILE *cnf_file; // pointer to config file cnf_file = read_cnf(argv[1]); // read the cnf file init_door(); // init the door fclose(cnf_file); // close the cnf file 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 (GAP) or PCBOARD.SYS (PCB) as well as the BBS configuration file. In addition, init_door opens the communications port (if a remote user is on), initializes some global variables, and initializes the random number generator. 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 GAPCDR module. When your program ends, you should clean house if necessary and call leave. Leave closes the communications port and any open files, restores the ISR routines to their original state, sends a sign off message to the caller, and then exits to DOS. It is of vital importance to exit the door by making a call to leave. Failure to do so will leave communication interrupts active, the ctrl-break intercept active, and the BIOS intercept active. The vectors to these routines will be left in the vector table and your computer will surely lock up. Page 5 GAPCDR (C) Copyright 1989 The GAP Development Company Things to remember: To get the ball rolling, include GAPCDR.H after the C header files. 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. All input and output should be performed through the GAPCDR 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. The default mode of operation is GAP mode. This means that you should not use those functions which access PCB files. To determine if the BBS is a PCB system, check the variable dopcb. If this is set to 1, then the BBS is PCB and you should not access GAP files. The variable dopcb is set to 1 if the environment variable GAPCDR is set equal to PCB. To test your program, you will need a DOOR.SYS (GAP) or a PCBOARD.SYS (PCB) 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:. In addition, for a GAP BBS, the GAPBBS.CNF file must be accessible (PCBOARD.DAT and USERS for PCB). A complete set of sample files are provided for testing your program under local mode. COMPILING AND LINKING --------------------- GAPCDR has already been compiled with the necessary compile time switches. To compile your programs, use whatever switches are required with the following commands: cl /c doorname link doorname,,NUL.MAP,+GAPCDRx Where doorname is the name of your program and 'x' is 'S' for the small model library or 'L' for the large model library. As was mentioned previously, GAPCDR was compiled with the /FPa option. However, the door code uses no floating point functions so you are free to compile your modules with the emulator option Page 6 GAPCDR (C) Copyright 1989 The GAP Development Company (the default) if you prefer. The /FPa option produces smaller executable files. If you purchased the source code to GAPCDR, there are suplementary files to aid in re-compiling and librarying the source modules. GAPCDR has not been tested with Quick C, although there is no reason why it should not work with the QC 2.0 environment. GAPCDR uses the PASCAL function calling convention. If you are unfamiliar with this calling convention, in short it means that the parameters to a function are pushed onto the stack from left to right instead of right to left. In addition, the function being called is responsible for removing arguments from the stack. In the C calling convention, the function making the call is responsible for restoring the stack. What this means is if you make 10 calls to show_mess, there will be 10 instances where the stack must be restored upon return from show_mess. In the PASCAL convention, there will be only one instance where this will occur and it will be in show_mess just prior to the actual return from the function. The end result of using the PASCAL calling convention is smaller code size. It should be noted that the PASCAL convention cannot be used with functions that take a variable number of arguments. Using the PASCAL convention absolutely requires that ALL functions be prototyped. Otherwise the compiler will generate redeclaration errors and the linker will generate unresolved external reference errors. A word about using GOTO - If you purchased the source code to GAPCDR, you will find that we use the goto in several places. It should be pointed out that speed and compactness, combined with readability, are our number one concerns. Prior to actually using our first goto in GAP Communications, we performed several experiments. We took a very simple function that consisted of a while loop and a few statements embodied within the while loop. We took the same function and rewrote it using a counter variable and a goto and removed the while loop. The assembler output and resultant object code was 1/2 the size as that of the function that used the while loop. We are not proposing that anyone give up the fine structure of C and use gotos as a beginning programmer in Basic might do. In fact, if you are a beginning programmer in C, you should avoid using gotos altogether until you become more proficient. When GAP communications began to outgrow its britches we looked into alternative ways of coding. We found through careful analyses of the assembly output that the goto was a natural choice in many instances. Lest anyone shudder at the thought of using a goto in C, be reminded that a break or continue in a loop is the exact equivalent of using a goto. Page 7 GAPCDR (C) Copyright 1989 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 GAPCDR Door Interface Module will run on GAP Communications version 3 and greater and on PCB version 14 and greater. To configure the door for a particular BBS setup, a configuration file must be used. At the very minimum, this file will contain two lines. It may contain more than two, 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 The first line is the full path to your BBS default directory. For GAP, this is usually C:\GAP. For PCB, this is usually C:\PCB. The second line is the name of your BBS. GAPCDR 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\tourist tourist tourist.cnf cd \gap gap As you can see, the door is invoked by passing the configuration file name as a parameter. 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. Page 8 GAPCDR (C) Copyright 1989 The GAP Development Company 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: TOURIST1.CNF TOURIST2.CNF TOURIST.CNF The only difference between the three would be the 1st line which points to the default directory for the particular node. Multi-user operation is automatic. For GAP, the presence of DUMMYLOK.DAT in the MAIN directory triggers multi-user operation. For PCB, this information is derived from the PCBOARD.DAT file. The following files are read during door initialization. They must be present or the door will not operate. GAP PCB ---------------- ---------------- DOOR.SYS PCBOARD.SYS GAPBBS.CNF PCBOARD.DAT USERS In addition, a particular door may access the GAP USERS.DAT and GAPDOS.DAT files. The default mode of operation for any door that is developed with GAPCDR is the GAP mode. To run the door under a PCB BBS, you must set the following environment variable (in UPPERCASE): GAPCDR=PCB 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 Page 9 GAPCDR (C) Copyright 1989 The GAP Development Company 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. GAPCDR is smart enough to know which drive and directory the door program is in and will reset the defaults upon return from DOS. In addition, the status line will remain "glued" to the screen. It should be noted that the GAPCDR status line is protected by intercepting BIOS video calls. If you use ANSI.SYS replacements which write directly to the video, you will not have this protection and your status line will scroll off the screen. 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 10 GAPCDR (C) Copyright 1989 The GAP Development Company GLOBAL VARIABLES ---------------- DEFINES ------- The following defines are used when calling show_mess. NO Defined as 0 YES Defined as 1 ANSI VARIABLES -------------- ANSI strings 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 11 GAPCDR (C) Copyright 1989 The GAP Development Company DOOR.SYS VARIABLES ------------------ DOOR.SYS variables are initialized while reading the Door Interface Module, DOOR.SYS. (For PCB, PCBOARD.DAT and USERS must be read to initialize these variables). These variables are available from door start up to door end. The DOOR.SYS variables are the door programmer's connection to the BBS. Note that any PCB variables that are declared as SINGLE or DOUBLE are set to 0. This is because any attempt to convert these variables (which are in the long outdated MSB format) would drag in the floating point library (minimum of 10k memory will be taken up by the floating point functions). INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on baud DTE rate to open COMM port at bell Page Bell. 0 = off, 1 = on color Color toggle. 0 = no color, 1 = color ok expert Expert mode. 0 = non-expert, 1 = expert local 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 screen Screen display. 0 = off, 1 = on userbaud BPS rate of the remote user LONGS ----- 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 Page 12 GAPCDR (C) Copyright 1989 The GAP Development Company STRINGS ------- bphone User's business or data phone number city User's home town fname User's first name hphone User's home phone number lastdate Last date user was on lname User's last name password User's password. PASSWORD if sysop is on subscrip Date user's subscription expires username User's full name GAPCDR GLOBALS -------------- These variables are the documented, global variables (initialized and used by GAPCDR). They may be modified and/or used at the programmer's discretion. CHARS ----- chat True if chatting with caller clockon If 0, don't display status line clock dopcb If set to 1, the BBS is a PCB system endview True if caller doesn't want to view any more fileshow 1 if showing a file, 0 if not instatus Used by BIOS interceptor noup If set to 1, get_string will not uppercase NS True if in Continuous mode redisplay True if wants to see file from beginning view True if viewing a file INTEGERS --------- lines Number of lines currently displayed 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) Page 13 GAPCDR (C) Copyright 1989 The GAP Development Company STRINGS ------- anystring Global garbage collector bbs_dir Path to BBS default dir board_name Name of the BBS curtime Holds the current time as a string gendir Path to the gen directory maindir Path to the main directory strtime Holds the time as a string sysname Sysop's name GAPDOS.DAT VARIABLES -------------------- These variables are initialized by the programmer by making a call to read_gapdos. String variables should not be modified. Please see the GAPSTRUC.H header file for the actual definition of these variables. gapdos.baud DTE bps rate gapdos.callbytes Ttl bytes available for download gapdos.didnew 1 = did a new files scan gapdos.exitdos 1 = exit to DOS after call gapdos.forumnum Forum the user is in gapdos.givetime 1 = event pending, else extra time received gapdos.joined Bit flags of forums joined gapdos.local 0 = user, 1 = sysop, 2 = local user gapdos.minavail Total minutes available to user gapdos.port Port being used gapdos.starttime Time (in seconds) user logged on gapdos.timecredit Any time credits user may have gapdos.userbaud User's bps rate gapdos.userfirst User's first name gapdos.userindex User's index into user file gapdos.username User's full name Page 14 GAPCDR (C) Copyright 1989 The GAP Development Company USERS.DAT VARIABLES ------------------- These variables are initialized by the programmer by making a call to read.gapuser. Please see the GAPSTRUC.H header file for the actual definition of these variables. WARNING : STRING fields are fully padded with spaces and the last position of the string is and MUST be a 0! user.blts Total bulletins read user.bphone User's work or data phone number user.city City, state, and zip (padded) user.curbytes Total bytes downloaded this call user.curdown Total files dowloaded today user.doors Total doors opened user.downloads Total downloads user.expert Novice = N, expert = Y user.fname User's first name (padded) user.handle User's handle (padded) user.hphone User's home phone number user.joined Total forums joined user.lastdate Last date on - mm/dd/yy user.lastdir Date last looked at a directory listing user.lastfrm Last forum in user.lastmsg Last message read user.lasttime Last time on - hh:mm user.level Security Level user.lname User's last name (padded) user.mesleft Total messages left user.mesread Total messages read user.minutes Total minutes last call user.page Page length user.passwd User's password (padded) user.private Allow on private nodes? user.protocol Transfer protocol (padded) user.subscribe Date user's subscription expires user.sysop Sysop record, 1 = Y, 0 = N user.timeson Number of times on user.ttlbytes Total bytes downloaded user.ttlmins Total mins on user.upbytes Total bytes uploaded user.uploads Total uploads Page 15 GAPCDR (C) Copyright 1989 The GAP Development Company PCBOARD.SYS VARIABLES --------------------- These variables are initialized automatically by init_door if the BBS system is PCB (set by environment variable GAPCDR=PCB). pcbsys.baud Com port bps rate pcbsys.calleralarm Caller alarm -1=on,0=off pcbsys.color Color toggle Y,N,7 pcbsys.ctime Time user logged on as HH:MM pcbsys.display Display on/off -1=on,0=off pcbsys.event_active Event active -1=yes,0=no pcbsys.errcorrect ECC modem -1=yes,0=no pcbsys.event Event time as HH:MM pcbsys.forumnum Forum user was in "0" = main pcbsys.minsleft Minutes left for caller pcbsys.node Node number as short integer pcbsys.pagebell Page bell -1=on,0=off pcbsys.password User's password pcbsys.port Com port as "0","1", or "2" pcbsys.printer Printer on/off -1=on,0=off pcbsys.slide_event Slide event -1=yes,0=no pcbsys.sysopnext Sysop on next N,X,space pcbsys.timeallowed Allowed time in minutes pcbsys.timecredit Any time credits in minutes pcbsys.timegiven Highest forum time given pcbsys.timeon Time user logged on in minutes pcbsys.timeused Time user has used that day pcbsys.ttlbytes Total K bytes available pcbsys.userbaud Caller bps rate (Local if local mode) pcbsys.userfirst User's first name pcbsys.username Name of caller pcbsys.userrec User's record number Page 16 GAPCDR (C) Copyright 1989 The GAP Development Company PCB USERS VARIABLES ------------------- These variables are initialized automatically by init_door if the BBS system is PCB (set by environment variable GAPCDR=PCB). pcbuser.bphone User's work or data phone number pcbuser.city City, state, and zip (padded) pcbuser.forum_regis Forum registration pcbuser.delete Delete, Y=yes,N=no pcbuser.curdown Total download bytes. pcbuser.downbytes Total download bytes. pcbuser.downloads Number of downloads pcbuser.expert Expert mode Y=yes,N=no pcbuser.hphone User's home phone pcbuser.lastconf Last forum in pcbuser.lastdate Last date user was on pcbuser.lastdir Last New files scan pcbuser.lastime Last time user was on pcbuser.lastmsg Last message read in main. pcbuser.lastmsg1 Last message read in each forum pcbuser.level User's level as short integer pcbuser.name User's name pcbuser.page Page length pcbuser.passwd User's password pcbuser.protocol Protocol type pcbuser.regisdate Registration date pcbuser.timeson Number of times on pcbuser.upbytes Total upload bytes. pcbuser.uploads Number of uploads Page 17 GAPCDR (C) Copyright 1989 The GAP Development Company GLOBAL VARIABLES - ALPHABETICALLY By Type ----------------------------------------- DEFINES ------- NO Defined as 0 YES Defined as 1 CHARS ----- chat True if chatting with caller clockon If 0, don't display status line clock dopcb If set to 1, the BBS is a PCB system endview True if caller doesn't want to view any more fileshow 1 if showing a file, 0 if not gapdos.didnew 1 = did a new files scan gapdos.exitdos 1 = exit to DOS after call instatus Used by BIOS interceptor noup If set to 1, get_string will not uppercase NS True if in Continuous mode pcbsys.forumnum Forum user was in "0" = main pcbsys.node Node number as short integer pcbsys.port Com port as "0","1", or "2" pcbsys.sysopnext Sysop on next N,X,space pcbuser.delete Delete, Y=yes,N=no pcbuser.expert Expert mode Y=yes,N=no pcbuser.lastconf Last forum in pcbuser.level User's level as short integer pcbuser.page Page length pcbuser.protocol Protocol type redisplay True if wants to see file from beginning user.expert Novice = N, expert = Y user.sysop Sysop record, 1 = Y, 0 = N view True if viewing a file DOUBLES ------- pcbuser.curdown Total download bytes. pcbuser.downbytes Total download bytes. pcbuser.upbytes Total upload bytes. FLOATS ------ pcbuser.lastmsg1 Last message read in each forum pcbuser.lastmsg Last message read in main. Page 18 GAPCDR (C) Copyright 1989 The GAP Development Company INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on baud DTE rate to open COMM port at bell Page Bell. 0 = off, 1 = on color Color toggle. 0 = no color, 1 = color ok expert Expert mode. 0 = non-expert, 1 = expert gapdos.baud DTE bps rate gapdos.forumnum Forum the user is in gapdos.givetime 1 = event pending, else extra time received gapdos.local 0 = user, 1 = sysop, 2 = local user gapdos.minavail Total minutes available to user gapdos.port Port being used gapdos.timecredit Any time credits user may have gapdos.userbaud User's bps rate level User's security level lines Number of lines currently displayed local 0 = remote user, 1 = local 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 pcbsys.minsleft Minutes left for caller pcbsys.timeallowed Allowed time in minutes pcbsys.timecredit Any time credits in minutes pcbsys.timegiven Highest forum time given pcbsys.timeon Time user logged on in minutes pcbsys.timeused Time user has used that day pcbsys.ttlbytes Total K bytes available pcbsys.userrec User's record number pcbuser.downloads Number of downloads pcbuser.timeson Number of times on pcbuser.uploads Number of uploads port Communications port in use printer Printer Toggle. 0 = off, 1 = on screen Screen display. 0 = off, 1 = on timecredit Time credits for user (in minutes) timeleft Time user has left (in minutes) user.curdown Total files dowloaded today user.lastfrm Last forum in user.level Security Level user.minutes Total minutes last call user.page Page length userbaud BPS rate of the remote user LONGS ----- downbytes Total bytes downloaded downloads Number of downloads gapdos.callbytes Ttl bytes available for download gapdos.joined Bit flags of forums joined gapdos.starttime Time (in seconds) user logged on Page 19 GAPCDR (C) Copyright 1989 The GAP Development Company 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 user.blts Total bulletins read user.curbytes Total bytes downloaded this call user.doors Total doors opened user.downloads Total downloads user.joined Total forums joined user.lastmsg Last message read user.mesleft Total messages left user.mesread Total messages read user.timeson Number of times on user.ttlbytes Total bytes downloaded user.ttlmins Total mins on user.upbytes Total bytes uploaded user.uploads Total uploads STRINGS ------- anystring Global garbage collector BBLACK ANSI codes for Grey BBLUE ANSI codes for bright Blue bbs_dir Path to BBS default dir 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 board_name Name of the BBS bphone User's business or data phone number BRED ANSI codes for bright Red BROWN ANSI codes for Brown BWHITE ANSI codes for bright White city User's home town curtime Holds the current time as a string CYAN ANSI codes for Cyan fname User's first name gapdos.userfirst User's first name gapdos.userindex User's index into user file gapdos.username User's full name gendir Path to the gen directory GREEN ANSI codes for Green hphone User's home phone number lastdate Last date user was on lname User's last name MAGENTA ANSI codes for Magenta maindir Path to the main directory password User's password. PASSWORD if sysop is on Page 20 GAPCDR (C) Copyright 1989 The GAP Development Company pcbsys.baud Com port bps rate pcbsys.calleralarm Caller alarm -1=on,0=off pcbsys.color Color toggle Y,N,7 pcbsys.ctime Time user logged on as HH:MM pcbsys.display Display on/off -1=on,0=off pcbsys.errcorrect ECC modem -1=yes,0=no pcbsys.event Event time as HH:MM pcbsys.event_active Event active -1=yes,0=no pcbsys.pagebell Page bell -1=on,0=off pcbsys.password User's password pcbsys.printer Printer on/off -1=on,0=off pcbsys.slide_event Slide event -1=yes,0=no pcbsys.userbaud Caller bps rate (Local if local mode) pcbsys.userfirst User's first name pcbsys.username Name of caller pcbuser.bphone User's work or data phone number pcbuser.city City, state, and zip (padded) pcbuser.forum_regis Forum registration pcbuser.hphone User's home phone pcbuser.lastdate Last date user was on pcbuser.lastdir Last New files scan pcbuser.lastime Last time user was on pcbuser.name User's name pcbuser.passwd User's password pcbuser.regisdate Registration date RED ANSI codes for Red strtime Holds the time as a string subscrip Date user's subscription expires sysname Sysop's name user.bphone User's work or data phone number user.city City, state, and zip (padded) user.fname User's first name (padded) user.handle User's handle (padded) user.hphone User's home phone number user.lastdate Last date on - mm/dd/yy user.lastdir Date last looked at a directory listing user.lasttime Last time on - hh:mm user.lname User's last name (padded) user.passwd User's password (padded) user.private Allow on private nodes? user.protocol Transfer protocol (padded) user.subscribe Date user's subscription expires username User's full name WHITE ANSI codes for White YELLOW ANSI codes for Yellow Page 21 GAPCDR (C) Copyright 1989 The GAP Development Company FUNCTIONS - QUICK REFERENCE --------------------------- ansi Displays ANSI escape sequences. backspace Sends one or more backspaces. ckeypress Checks for a remote or local key press. clear_scrn 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. getakey Gets one key responses. get_random 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 Called by the Comm Routines if Carrier lost. open_gap Opens and reads GAPBBS.CNF. 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_gapdos Reads GAPDOS.DAT. read_gapuser Reads USERS.DAT. read_pcbsys Reads PCBOARD.SYS. read_pcbuser Reads PCB USERS file. read_score Reads and displays top 10 scores. 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. wait Pauses for x number of seconds. wrap_word Wraps a word. write_gapdos Writes GAPDOS.DAT. write_gapuser Writes USERS.DAT. write_pcbsys Writes PCBOARD.SYS. write_pcbuser Writes PCB USERS. write_score Creates and maintains top 10 scores file. Page 22 GAPCDR (C) Copyright 1989 The GAP Development Company FUNCTIONS - REFERENCE --------------------- Functions will return either a void (nothing), an integer value, or a character pointer. To retrieve the return value, either assign it to a variable of the same type, or use the function call in a test expression such as : intvar = getakey(); or if (ckeypress()) key = getakey(); Name : ansi Purpose : Displays ANSI escape sequences Parameters : ANSI color to display Return Value : None Convention : void ansi(color); char *color; 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 global variables. If the remote or local user is in non graphics mode, the function returns immediately. Example : ansi(BWHITE) Page 23 GAPCDR (C) Copyright 1989 The GAP Development Company Name : backspace Purpose : Sends one or more backspaces Parameters : Number of backspaces to send Return Value : None Convention : void backspace(num); int num; 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 char- acter sequences as you specify in the parameter list. Example : backspace(1) strcpy(anystring,"Press Any Key "); show_mess(anystring,NO,NO) // show string while (!ckeypress()) // wait for key ; getakey(); // get the key backspace(strlen(anystring)); // erase string Name : ckeypress Purpose : Checks for a remote or local key press Parameters : None Return Value : 0 = no key is waiting, 1 = a key is waiting Convention : int ckeypress(void); 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? while(!ckeypress()) // do something { | // until a key | // is pressed } Page 24 GAPCDR (C) Copyright 1989 The GAP Development Company Name : clear_scrn Purpose : Clears local and remote screens. Parameters : None Return Value : None Convention : void clear_scrn(void); Description : This routine will use the assembler routine cls to clear the first 23 lines of the local screen. If the remote caller is in non-color mode, it sends a CTRL-L to the remote screen, otherwise it sends the ANSI clear screen sequence. Example : clear_scrn(); // clear screen Name : do_chat Purpose : To allow sysop to chat with remote user Parameters : None Return Value : None Convention : void do_chat(void); 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 chat- ting 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 : do_chat(); empty(response,2); // initialize get_string(response); // get a string if (response[0] == 'P') // paging sysop do_chat(); // chat with sysop Page 25 GAPCDR (C) Copyright 1989 The GAP Development Company Name : elap_time Purpose : Computes elapsed time while waiting for keyboard input Parameters : None Return Value : None Convention : void elap_time(void); 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 : elap_time(); time (&temptime); // start timer // check activity while (!getakey()) // until a key is elap_time(); // pressed Name : get_string Purpose : Gets a string of characters Parameters : String to fill Return Value : None Convention : void get_string(string); char *string; 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. Before calling, you must initialize the passed string with spaces. The number of spaces in the string determines the number of characters al- lowed 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 empty function. 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 Page 26 GAPCDR (C) Copyright 1989 The GAP Development Company 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 : empty(instr,10); // initialize get_string(instr); // get string Name : getakey Purpose : Gets one key responses Parameters : None Return Value : ASCII code for the key pressed or 0 Convention : int getakey(void); 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 re- ceive 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 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 27 GAPCDR (C) Copyright 1989 The GAP Development Company Name : get_random Purpose : Gets a random number Parameters : Low number, high number Return Value : A random number Convention : int get_random(low,high); int low; int high; Description : This routine is provided because it is much easier to use and understand than the C library routine (which drags in the floating point library). 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 : rndnum = get_random(1,10); // get a random // number between // 1 and 10 Name : init_door Purpose : Initializes the GAPCDR functions Parameters : None Return Value : None Convention : void init_door(void); 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 : read_cnf("DOOR.CFG"); // read cnf file init_door(); // init the door Page 28 GAPCDR (C) Copyright 1989 The GAP Development Company Name : leave Purpose : Exits the program Parameters : The exit code you wish to terminate with Return Value : None Convention : void leave(code); int code; Description : When the program terminates, it must call this function to end. This is the ONLY proper exit from the door. It is of vital importance to end your program thru this function so that the interrupt service routines that are installed at door beginning can be removed. Example : leave(0); Name : more Purpose : Checks for a full screen and issues a More Prompt Parameters : None Return Value : None Convention : void more(void); Description : This is an internal routine that is called by the character output functions. Example : Name : 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 Convention : void nl(lines); int lines; Description : To send a blank line, call this routine with the number of blank lines you wish to send. Example : nl(2); // send two blank // lines Page 29 GAPCDR (C) Copyright 1989 The GAP Development Company Name : no_carrier Purpose : Used by the Comm functions. Parameters : None Return Value : None Convention : void no_carrier(void); 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. Example : Name : open_gap Purpose : Opens and reads the GAPBBS.CNF file Parameters : None Return Value : 0 = no error, 1 = error Convention : int open_gap(void); Description : This function is called by init_door. It opens and reads the configuration file for GAP. Note that only part of the CNF file is read. The main purpose for reading the file is to obtain the path to the BBS's main directory and get the sysop' name. Example : c = open_gap(); Name : pagesysop Purpose : Alerts sysop that user wants to chat Parameters : None Return Value : None Convention : void pagesysop(void); 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 : empty(response,2); // initialize var get_string(response); // get a response if (response[0] = 'P') // wants to chat pagesysop(); // tell sysop Page 30 GAPCDR (C) Copyright 1989 The GAP Development Company Name : pause Purpose : Sends a "Press [Any Key] To Continue" prompt Parameters : None Return Value : None Convention : void pause(void); Description : This function sends a pause prompt and waits for a key press. Example : nl(1); // send blank line pause(); // wait for a key Name : putachar Purpose : Send a single character to local and remote Parameters : Integer value of ASCII character to send Return Value : None Convention : void putachar(ch); int ch; Description : This routine is called a "semi-unfiltered" char- acter output routine because it allows for most ASCII characters to be output. Example : c = 65; // send an 'A' putachar(c); // to local and // remote screen c = getakey(); // get a keypress if (c != 0) // if we got a key putachar(c) // display the // character Name : putkey Purpose : Used by chat routines to keep track of word wrapping Parameters : Integer representing character to send Return Value : None Convention : void putkey(ch); int ch; 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 31 GAPCDR (C) Copyright 1989 The GAP Development Company Name : read_cnf Purpose : To read the door configuration file Parameters : Full path and file name to the configuration file. Return Value : FILE pointer Convention : FILE *read_cnf(path); char *path; 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. WARNING : The first two lines of this configura- tion file belong to the GAPCDR interface module. You are free to use the information, but the in- formation contained in the first two lines must conform exactly to the following specifications. The first line of this file is the full drive and path to the BBS default directory. This is the directory where the BBS system files can be found (IE, GAPDOS.DAT, DOOR.SYS, GAPBBS.CNF). The en- try on line 1 is not checked until init_door is called. The second line of this file is the name of the BBS. It is the responsibility of the door author to describe the format of these two lines to the end user. It is also the responsibility of the door author to insure that the end user have these two 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 two lines already in it. GAPCDR will NOT close this file (a FILE pointer to the file will be returned) after reading the first two 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 3. If you use a set up program, be sure that your set up program writes the first two lines as specified. After you have called read_cnf and init_door, if you have any configuration options in the "door".cnf file, you should use the stream input Page 32 GAPCDR (C) Copyright 1989 The GAP Development Company routines to read those options. Then fclose the file using the FILE pointer returned. Even if you have no options to read, close the file. WARNING : You MUST call this routine before using any of the GAPCDR functions. After calling this routine, you MUST call init_door. Example : FILE *fp; // File pointer fp = read_cnf("TOURIST.CNF"); // read cnf file fclose(fp); // close the file init_door(); // init the door Name : read_doorsys Purpose : Reads the DOOR.SYS universal door interface file Parameters : None Return Value : 0 = no error, 1 = error Convention : int read_doorsys(void); 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(); Name : read_gapdos Purpose : Reads the GAP Communications DOS file. Parameters : None Return Value : 0 = no error, 1 = error Convention : int read_gapdos(void); Description : GAPDOS.DATReads the GAPDOS.DAT remote exit to DOS file. If you have a need for the information in this file, or if you need to modify the record variables, this function will read the file for you. The record variables are contained in a variable called gapdos. WARNING : Do NOT modify the string fields in GAPDOS.DAT. If the gapdos.userindex field is changed, GAP will be unable to find the user in the userfile upon return from the door. The only proper way to update this file is to first read it. Make any changes to the variables themselves or use your own temporary variables. Then call write_gapdos to update the record. Example : c = read_gapdos() Page 33 GAPCDR (C) Copyright 1989 The GAP Development Company Name : read_gapuser Purpose : Reads the GAP Communications USERS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Convention : int read_gapuser(void); 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(); Name : read_pcbsys Purpose : Reads the PCBOARD.SYS file. Parameters : None Return Value : 0 = no error, 1 = error Convention : int read_pcbsys(void); Description : For a PCB setup, this function is automatically called by init_door. Do not use unless dopcb is set to 1. Example : c = read_pcbsys(); Name : read_pcbuser Purpose : Reads the PCB USERS file. Parameters : None Return Value : 0 = no error, 1 = error Convention : int read_pcbuser(void); Description : For a PCB setup, this function is automatically called by init_door. Do not use unless dopcb is set to 1. Note that to change the fields downbytes, upbytes, or lastmsg, you will need to use the C library routines designed specifically for converting MSB formatted numbers. Example : c = read_pcbuser(); Page 34 GAPCDR (C) Copyright 1989 The GAP Development Company Name : read_score Purpose : Reads the score file and displays the results. Parameters : data file to read, message to display Return Value : 0 = scores read, 1 = no scores to read Convention : int read_score(datfile,message); char *datfile; char *message; Description : This function will read the scoreboard data file for your door (if any) and display the results. You pass as parameters the name of the data file to read, and a message to display at the top of the scoreboard. The message could be something like "Top 10 Players". Example : if (read_score("TOURIST.DAT","Top 10 Tourists")) { nl(1); ansi(BWHITE); show_mess("No one's made it Yet!",NO,YES); } Name : 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 Convention : void set_status(how); int how; 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 : set_status(0); Page 35 GAPCDR (C) Copyright 1989 The GAP Development Company Name : show_file Purpose : To display a text file Parameters : The full path and file name to the file to be shown Return Value : None Convention : void show_file(filename); char *filename; 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, GAPCDR 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 normally have to edit the file with a text editor to insert the control character. 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 Page 36 GAPCDR (C) Copyright 1989 The GAP Development Company 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 : show_file("WELCOME"); show_file("C:\GAP\GEN\WELCOME"); Name : show_mess Purpose : Displays a message Parameters : Message, ring the bell, issue a New Line Return Value : None Convention : void show_mess(message,bell,newline); char *message; int bell; int newline; Description : Finally! After all of this, just how do you display a message to the user? Well, here it is. This is the string output function for GAPCDR. Under most circumstances, this is the one func- tion 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 inter- nal routines. 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. Example : // the first show_mess displays the string and // leaves the cursor on the same line. The // second displays the string, rings the remote // user's bell, and drops the cursor to the next // line. nl(1); show_mess("Are you ready? (Y/N) : ",NO,NO); empty(response,4); get_string(response); if (response[0] == 'Y') // begin whatever it is you want to begin else show_mess("Too Bad!",YES,YES); Page 37 GAPCDR (C) Copyright 1989 The GAP Development Company Name : time_credit Purpose : Keeps track of time and credits the user with time elapsed Parameters : 1 = start timer, 0 = end timer Return Value : None Convention : void time_credit(flag); int flag; 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 : time_credit(1); // start the timer do_chat(); // chat with user 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 38 GAPCDR (C) Copyright 1989 The GAP Development Company Name : time_left Purpose : To compute the user's time remaining Parameters : None Return Value : None Convention : void time_left(void); 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 GAPCDR library, the timeleft vari- able will always be current. Example : time_left(); Name : trim Purpose : Trims spaces from the end of NULL terminated strings Parameters : String containing the spaces. Return Value : Pointer to the string without the spaces. Convention : char *trim(string); char *string; Description : This function will remove any spaces from the end of a string. Example : trim(gapdos.username); Name : update_clock Purpose : Updates the status line clock Parameters : None Return Value : None Convention : void update_clock(void); Description : Internal routine to update the status line clock. Example : Page 39 GAPCDR (C) Copyright 1989 The GAP Development Company Name : wait Purpose : Pauses for the number of "ticks" specified. Parameters : Number of timer ticks to pause Return Value : None Convention : void wait(ticks); int ticks; Description : This function allows you to pause all processing for the specified number of ticks. It is in- sensitive to processor speed. The function simply delays the number of "ticks" indicated by the passed parameter. Each tick is 1/18 of a second. Example : wait(18); // pause for 1 sec Name : wrap_word Purpose : To wrap a word during sysop chats Parameters : None Return Value : None Convention : void wrap_word(void); Description : Internal function called by putkey to wrap words. Example : Page 40 GAPCDR (C) Copyright 1989 The GAP Development Company Name : write_gapdos Purpose : Updates the GAPDOS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Convention : int write_gapdos(void); Description : This function allows the programmer to update the GAP Communications remote exit to DOS system file. If the GAPDOS.DAT file is read at door be- ginning, the timecredit variable assigned to gapdos.timecredit, and the GAPDOS.DAT file writ- ten out at doors end, the user will be credited with any time spent during a sysop chat or shell to DOS. Example : c = read_gapdos(); // read the file if (c == 0) // if no error... { timecredit = gapdos.timecredit; // do some processing // give the user 20 more minutes timecredit += 20; gapdos.timecredit = timecredit c = write_gapdos(); // update the file } Page 41 GAPCDR (C) Copyright 1989 The GAP Development Company Name : write_gapuser Purpose : Updates the user record in GAP's USERS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Convention : int write_gapuser(void); 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 strings that are fully padded with spaces. If you modify any of these strings, you MUST make sure that the string is fully padded with spaces and that the NULL character is placed in the last string posi- tion. WARNING : The index for the user file consists of the user's last name and first name. Do not un- der any circumstances modify either of these two fields. Doing so will cause corruption of the Index file. Example : // give the user a level of 50 c = read_gapuser(); // 1st read record user.level = 50; c = write_gapuser(); // update the rec // allow user to change handle c = read_gapuser(); if (c == 0) { show_mess("Enter New Handle : ",NO,NO) empty(handle,16); get_string(handle) if (handle[0] != 0) { strcpy(user.handle,handle); pad(user.handle,16); // pad with spaces c = write_gapuser(); if (c == 0) show_mess("Saved new Handle",NO,YES); } } Page 42 GAPCDR (C) Copyright 1989 The GAP Development Company Name : write_pcbsys Purpose : Updates the PCBOARD.SYS file Parameters : None Return Value : 0 = no error, 1 = error Convention : int write_pcbsys(void); Description : This function allows the programmer to update the PCBOARD.SYS File. Do not use unless dopcb is set to 1. Example : c = write_pcbsys() // write the file Name : write_pcbuser Purpose : Updates the PCB USERS file Parameters : None Return Value : 0 = no error, 1 = error Convention : int write_pcbuser(void); Description : This function allows the programmer to update the PCB USERS File. Do not use unless dopcb is set to 1. Note that you will need to use the C library routines to convert IEEE formatted numbers to the MSB format that pcb uses if you change any of the DOUBLE or SINGLE fields in the user file. Example : c = write_pcbuser(); // write the file Page 43 GAPCDR (C) Copyright 1989 The GAP Development Company Name : write_score Purpose : Creates and maintains a scoreboard Parameters : data file to write, score to write Return Value : None Convention : void write_score(filename,score); char *filename; unsigned long score; Description : This function will create and maintain a scoreboard of the top ten players. You pass it two parameters. The first is a string containing the name of the data file to create/maintain. The second is a long unsigned integer containing the score to write. The user's name and the current date are already known. If the sysop is in the door at the time, the function will simply return and not write a score. The scores will automatically be sorted in decreasing order by the highest score. If you wish to use this routine but your points are kept as integers instead of longs, simply cast the second parameter to a long unsigned integer. Example : int points; points = 1000; write_score("TOURIST.DAT,(unsigned long) points); Page 44 GAPCDR LICENSE AGREEMENT ------------------------- This legal document is an agree- GAP Development Company consents ment between you, the end user, in writing, in advance. and GAP Development Company. By using the GAPCDR software Registration of the SOFTWARE is (the "SOFTWARE") provided by GAP REQUIRED as a condition of use. Development Company, you agree to become bound by the terms of You are granted a royalty-free this agreement, which includes right to distribute executable the software license and the files created using the SOFT- disclaimer of warranty. WARE. You may not, under any circumstances distribute any This agreement constitutes the part of the SOFTWARE with your complete agreement between you executable files. and GAP Development Company. If you do not agree to the terms of If you purchased the SOFTWARE this agreement, promptly return SOURCE CODE, you are granted a the disks and other items that nonexclusive, personal, non- are part of this product. transferable, nonassignable li- cense to use and modify the The SOFTWARE may not be copied, SOURCE CODE and to distribute reproduced, disclosed, trans- your programs. You may not re- ferred, or reduced to any form, produce or distribute the SOURCE including electronic medium or CODE except in executable form machine readable form, or trans- as part of your executable file. mitted or publicly performed by If you distribute your source any means, electronic or other- code, you may not include the wise, unless GAP Development SOFTWARE SOURCE CODE as part of Company consents in writing, in your product. advance. This License is effective until The SOFTWARE contains valuable terminated. This License will trade secrets and proprietary terminate automatically if you information and is protected by fail to comply with any provi- federal copyright laws. Unautho- sion of this License. rized use of the software can result in civil damages and SUMMARY OF LIMITED WARRANTY: criminal prosecution. In summary, the SOFTWARE is li- You may use the SOFTWARE on a censed AS IS. THERE ARE NO single computer only. You may WARRANTEES, EXPRESS OR IMPLIED, not network the SOFTWARE or oth- INCLUDING BUT NOT LIMITED TO THE erwise use it on more than one IMPLIED WARRANTIES OF MER- computer or terminal at the same CHANTABILITY AND FITNESS FOR A time. PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND YOU MAY NOT COPY the SOFTWARE SPECIFICALLY DISCLAIMED. IN NO except to place the programs EVENT SHALL GAP DEVELOPMENT COM- onto your hard disk and to make PANY BE RESPONSIBLE FOR ANY IN- archival backup copies onto DIRECT, SPECIAL, INCIDENTAL OR floppy disks for your personal CONSEQUENTIAL DAMAGES OR LOST use as permitted by this Li- PROFITS TO YOU OR ANY OTHER PER- cense. You may not copy the SON OR ENTITY REGARDLESS OF THE written materials accompanying LEGAL THEORY, EVEN IF WE HAVE the software. You may not grant BEEN ADVISED OF THE POSSIBILITY sublicenses nor transfer the OF SUCH DAMAGE. SOFTWARE or related materials in any form to any person unless REGISTRATION INFORMATION ------------------------ GAPCDR is a user-supported program, also known as 'shareware'. Shareware is a means by which users may 'test- drive' software before purchasing. Generally, it allows the user to evaluate the software for a period of 30 days. After the evaluation period the user must either register the product or cease using it. You are permitted under the terms of the above License Agreement to use GAPCDR for a period of 30 days without payment. If you continue to use the product past the 30 day evaluation period, you must register your copy as described below. Commercial use of this software absolutely requires a registration within the 30 day period. Commercial use includes any software written by you which utilizes GAPCDR and which you charge any sum of money for the use of your software. This includes shareware registration, donations, registration fees, or any method you use or devise to solicit funds from the users of your software. Commercial use also includes bundling GAPCDR with other software even if that other software does not utilize any of the GAPCDR functions. This type of commercial use is strictly prohibited. A great deal of time, money, and effort went into creating GAPCDR. In order for us to continue to provide quality software at reasonable prices, we need your support. Registration of GAPCDR is a one time fee of $25.00. Payment of this fee entitles you to one year of free upgrades, product support, the right to use GAPCDR in any executable program you sell or distribute, and a good conscience. Source code is available to registered users for a one time license fee of $25.00. The source code is fully commented and well structured. GAPCDR Support Board : The Crow's Nest BBS (714)493-3819 Node 1 (714)493-9851 Node 2 GAPCDR REGISTRATION -------------------- Please fill in and detach the following sheet and mail it to GAP Development Company. ------------------------------------------------------------ I understand and accept the GAPCDR License Agreement. Accepted By : ____________________________________ (signature) Accepted By : ____________________________________ (printed name) Date : ____________ Product : GAPCDR Licensee Information : Name : ___________________________________________ Address : ___________________________________________ Address : ___________________________________________ City,State,Zip : ___________________________________________ Voice Phone : ________________________ ------------------------------------------------------------ # Description Price ------------------------------------------------------------ 3001 GAPCDR Run Time Library 25.00 __________ 3002 GAPCDR Source Code License 25.00 __________ Total Due __________ Less Credit(s) __________ Total Amount Enclosed __________ ------------------------------------------------------------ Payment may be made by check or money order ------------------------------------------------------------ GAP Development Company 24242 Porto Fino RT 7715 Laguna Niguel, CA 92677-3844 INDEX ----- @ 36 GREEN 11 ANSI 2, 4, 11, 20, 23, 36 MAGENTA 11 argv 5 RED 11 backspace 24 WHITE 11 bell 37 YELLOW 11 chat 2, 25, 30, 31, 38, 40, Chars 41 GAPDOS ckeypress 24 gapdos.didnew 14 clear_scrn 25 gapdos.exitdos 14 communications port 5 General configuration file 5 chat 13 CTS 2 clockon 13 DEFINES 11 dopcb 13 do_chat 25 endview 13 DOOR.SYS 5, 6, 9, 12, 22, 32, fileshow 13 33 instatus 13 dopcb 6, 34, 43 noup 13 elap_time 26 NS 13 empty 26 redisplay 13 error 5, 28, 32 view 13 exit code 29 PCBSYS Files pcbsys.forumnum 16 Aborting 36 pcbsys.node 16 Color 36 pcbsys.port 16 Configuration 30, 32 pcbsys.sysopnext 16 DOOR.SYS 33 PCBUSERS GAPDOS.DAT 33, 41 pcbuser.delete 17 Header 4, 6 pcbuser.expert 17 PCB USERS 34, 43 pcbuser.lastconf 17 PCBOARD.SYS 34, 43 pcbuser.level 17 Showing 36 pcbuser.page 17 System 25, 28 pcbuser.protocol 17 USERS.DAT 34, 42 USERS Functions 23 user.expert 15 GAPBBS.CNF 32 user.sysop 15 GAPDOS.DAT 9, 14, 22, 32, 33, Defines 41 General get_random 28 NO 11 get_string 13, 25, 26, 27, YES 11 30, 37, 42 Doubles getakey 27 PCBUSERS Global Variables pcbuser.curdown 17 ANSI pcbuser.downbytes 17 BBLACK 11 pcbuser.upbytes 17 BBLUE 11 Floats BCYAN 11 PCBUSERS BGREEN 11 pcbuser.lastmsg 17 BLACK 11 pcbuser.lastmsg1 17 BLUE 11 Integers BMAGENTA 11 DOOR.SYS BRED 11 alarm 12 BROWN 11 baud 12 BWHITE 11 bell 12 CYAN 11 color 12 Page 48 INDEX ----- expert 12 gapdos.joined 14 level 12 gapdos.starttime 14 local 12 General minsleft 12 starttime 13 node 12 temptime 13 page 12 timenow 13 parity 12 USERS port 12 user.blts 15 printer 12 user.curbytes 15 screen 12 user.doors 15 userbaud 12 user.downloads 15 GAPDOS user.joined 15 gapdos.baud 14 user.lastmsg 15 gapdos.forumnum 14 user.mesleft 15 gapdos.givetime 14 user.mesread 15 gapdos.local 14 user.timeson 15 gapdos.minavail 14 user.ttlbytes 15 gapdos.port 14 user.ttlmins 15 gapdos.timecredit 14 user.upbytes 15 gapdos.userbaud 14 user.uploads 15 General Strings lines 13 DOOR.SYS timecredit 13 bphone 13 timeleft 13 city 13 PCBSYS fname 13 pcbsys.minsleft 16 hphone 13 pcbsys.timeallowed 16 lastdate 13 pcbsys.timecredit 16 lname 13 pcbsys.timegiven 16 password 13 pcbsys.timeon 16 subscrip 13 pcbsys.timeused 16 username 13 pcbsys.ttlbytes 16 GAPDOS pcbsys.userrec 16 gapdos.userfirst 14 PCBUSERS gapdos.userindex 14 pcbuser.downloads 17 gapdos.username 14 pcbuser.timeson 17 General pcbuser.uploads 17 anystring 14 USERS bbs_dir 14 user.curdown 15 board_name 14 user.lastfrm 15 curtime 14 user.level 15 gendir 14 user.minutes 15 maindir 14 user.page 15 strtime 14 Longs sysname 14 DOOR.SYS PCBSYS downbytes 12 pcbsys.baud 16 downloads 12 pcbsys.calleralarm 16 maxbytes 12 pcbsys.color 16 recnum 12 pcbsys.ctime 16 timeson 12 pcbsys.display 16 upbytes 12 pcbsys.errcorrect 16 uploads 12 pcbsys.event 16 GAPDOS pcbsys.event_active 16 gapdos.callbytes 14 pcbsys.pagebell 16 Page 49 INDEX ----- pcbsys.password 16 read_pcbuser 34 pcbsys.printer 16 read_score 35 pcbsys.slide_event 16 RTS 2 pcbsys.userbaud 16 set_status 35 pcbsys.userfirst 16 show_file 36 pcbsys.username 16 show_mess 11, 24, 37, 42 PCBUSERS Spaces pcbuser.bphone 17 Trimming 39 pcbuser.city 17 USERS.DAT 42 pcbuser.forum_regis 17 Status Line 2, 35, 39 pcbuser.hphone 17 string output 37 pcbuser.lastdate 17 time_credit 38 pcbuser.lastdir 17 time_left 39 pcbuser.lastime 17 timecredit 38, 41 pcbuser.name 17 timeleft 27, 39 pcbuser.passwd 17 trim 39 pcbuser.regisdate 17 Trimming Spaces 39 USERS update_clock 39 user.bphone 15 USERS.DAT 9, 15, 22 user.city 15 wait 40 user.fname 15 wrap_word 40 user.handle 15 write_gapdos 33, 41 user.hphone 15 write_gapuser 42 user.lastdate 15 write_pcbsys 43 user.lastdir 15 write_pcbuser 43 user.lasttime 15 write_score 44 user.lname 15 { 36 user.passwd 15 user.private 15 user.protocol 15 user.subscribe 15 IEEE 43 init_door 4, 5, 6, 16, 17, 28, 30, 32, 33, 34 leave 5, 6, 29 more 29 MSB 12, 34, 43 New Line 29, 37 nl 29 no_carrier 30 node 6 noup 27 open_gap 30 pagesysop 30 pause 31, 40 PCB USERS 17, 22 PCBOARD.SYS 5, 6, 16, 22 putachar 31, 37 putkey 31, 37 read_cnf 4, 5, 6, 32 read_doorsys 33 read_gapdos 33 read_gapuser 34 read_pcbsys 34 Page 50