home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / BASIC / SDOOR100.ZIP / SDOOR.DOC < prev    next >
Encoding:
Text File  |  1992-03-25  |  19.0 KB  |  551 lines
  1.                              Simple Door v1.0b
  2.  
  3.                             by SumWare Software
  4.                            Programmer: Roy Hooper
  5.                         Beta Basher: Rick Chartrand
  6.                      Documentation : Michelle Chartrand
  7.  
  8.                  Simple Door can be registered for $35 Cdn.
  9.  
  10.  
  11.         Simple Door was written for the use of anyone wishing to make a
  12.         door in QuickBasic 4.5.  Simple Door's main purpose was to create a
  13.         good, easy way to make good doors.
  14.  
  15.         Simple Door is a collection of routines that handle communications
  16.         through a FOSSIL driver and manage the user's time limit, and
  17.         carrier.  There are routines ranging from sending a string to
  18.         sending a file, getting a character and getting a string.
  19.  
  20.         Simple Door has many things to make your door look nice, including
  21.         only using ANSI routines if the user supports ANSI, and a status bar
  22.         with plenty of bits of information on it.  The status bar also has a
  23.         few controls on it which allow you to chat with the user, and
  24.         increase or decrease the user's time.  You can shell to DOS, boot
  25.         the user out of the door, or even turn off snoop.
  26.  
  27.         Simple Door is multi-node compatible, as it does no disk I/O and
  28.         relies on the door file for information on where to do its
  29.         communications I/O.  If you wish to support multi node, then your
  30.         door must support multinode internally.
  31.  
  32.         Simple Door does error handling for any error that might occur
  33.         internally.  If an error that it cannot handle occurs, then it will
  34.         just state it and exit.  Simple Door does not do error handling for
  35.         your program, only errors internal to Simple Door.  If you wish to
  36.         learn more about error handling for your program, take a look at ON
  37.         ERROR in your QuickBasic 4.5 manual.
  38.  
  39. - Using Simple Door -
  40.  
  41.         To use Simple Door inside one of your program, you need to include
  42.         the SDOOR.BI file.  SDOOR.BI can be located in your INCLUDE
  43.         directory, or in your QuickBasic program directory, or the current
  44.         directory.  SDOOR.QLB and SDOOR.LIB has to be located in a place
  45.         that QuickBasic can find then when it loads  up (usually your
  46.         LIBRARY directory or the QuickBasic program directory, or the
  47.         current directory).
  48.  
  49.         When loading QuickBasic, you need to tell QuickBasic about the
  50.         library.  To do this, you need to specify the library on the command
  51.         line.  Example:
  52.  
  53.         QB /LSDoor
  54.  
  55.         Inside your program, after your DECLARE SUB/FUNCTION lines, if any,
  56.         you need to place the following line:
  57.  
  58.         '$INCLUDE: 'SDOOR.BI'
  59.  
  60.         And then you are ready to program with Simple Door. (Don't forget to
  61.         initialize Simple Door).  One thing to keep in mind is Simple Door
  62.         has a 4 minute timeout limit.  After 3 minutes 30 seconds of no
  63.         keypresses, SDoor warns you with a beep that you have 30 seconds to
  64.         do something.
  65.  
  66.  
  67. - What Simple Door Can Do -
  68.  
  69.  
  70.                                  FUNCTIONS
  71.  
  72.    AColor$ (Fore%, Back%)
  73.         Makes an optimized ANSI color string
  74.         Fore% = Foreground color to use
  75.         Back% = Background color to use
  76.  
  77.         EXAMPLE:
  78.                 Send AColor$(7,1)+"White on blue"
  79.  
  80.        (q.v. SetColor for a complete list of colors)
  81.  
  82.    CtrlCK% ()
  83.         Checks if Control C/K have been checked.  Also enables Control C/K
  84.         checking.  Returns -1 if true, 0 if not true.
  85.  
  86.         EXAMPLE:
  87.                 IF CtrlCK% THEN
  88.                         FlushOut
  89.                         SendCr "Aborted."
  90.                 END IF
  91.  
  92.    Exist% (FileName$)
  93.         Returns a non-zero value if the file exists.
  94.  
  95.         EXAMPLE:
  96.                 IF Exist%("TEST.TTT") THEN Send "File FOUND"
  97.  
  98.    GetAnsi% ()
  99.         Gets the current ANSI setting.  Returns -1 if true, 0 if not true.
  100.  
  101.         EXAMPLE:
  102.                 AnsiMode%=GetAnsi%
  103.                 IF AnsiMode% THEN
  104.                         SendCr "Ansi is active"
  105.                 ELSE
  106.                         SendCr "Ansi is not active"
  107.                 END IF
  108.  
  109.    GetBBSName$ ()
  110.         Gets the bbs's name,  in all uppercase.
  111.  
  112.         EXAMPLE:
  113.                 Send "This program is registered to : " + GetBbsname$
  114.  
  115.    GetBaudRate& ()
  116.         Gets the current baud rate of the user (Door Info).  0 if local.
  117.  
  118.         EXAMPLE:
  119.                 Send "You are running at" + STR$(GetBaudRate&)
  120.  
  121.    GetCarrier% ()
  122.         Gets the current carrier state.  Non-zero if there is a carrier.
  123.         The user's carrier is automatically managed.  This is not really
  124.         needed.
  125.  
  126.         EXAMPLE:
  127.                 IF GetCarrier% THEN Send "YOU ARE STILL CONNECTED"
  128.  
  129.    GetPort% ()
  130.         Gets the current serial port setting.  -1 if local
  131.  
  132.         EXAMPLE:
  133.                 Send "You are on com port" + STR$(GetPort%)
  134.  
  135.    GetSecLevel& ()
  136.         Gets the user's security level.
  137.  
  138.         EXAMPLE:
  139.                 Send "Your security Level is" + STR$(GetSecLevel&)
  140.  
  141.    GetSnoopState% ()
  142.         Gets the status of the snoop setting on the SysOp's side.
  143.         Returns -1 if true, 0 if not.
  144.  
  145.         EXAMPLE:
  146.                 IF GetSnoopState% THEN
  147.                         Send "Snoop is ON"
  148.                 ELSE
  149.                         Send "Snoop is OFF"
  150.                 ENDIF
  151.  
  152.    GetSysopName$ ()
  153.         Gets the sysop's name,  in all uppercase.
  154.  
  155.         EXAMPLE:
  156.                 Send "Your sysop is: " + GetSysopname$
  157.  
  158.    GetTimeLeft% ()
  159.         Gets the amount of time the user has left in minutes.
  160.  
  161.         EXAMPLE:
  162.                 Send "You have" + STR$(GetTimeLeft%)+" minutes left."
  163.  
  164.    GetUserLocation$ ()
  165.         Gets the user's location (DOOR INFO) in all uppercase.
  166.  
  167.         EXAMPLE:
  168.                 Send "Your location is: " + GetUserLocation$
  169.  
  170.    GetUserName$ ()
  171.         Gets the user's name (DOOR INFO) in all uppercase.
  172.  
  173.         EXAMPLE:
  174.                 Send "Your name is: " + GetUserName$
  175.  
  176.  
  177.  
  178.                                 SUBROUTINES
  179.  
  180.    Center (St$)
  181.         Centers the specified text and stays on the same line.
  182.  
  183.         EXAMPLE:
  184.                 Center "Testing the centering routine"
  185.  
  186.    CenterCr (St$)
  187.         Centers the specified text and creates a new line.
  188.  
  189.         EXAMPLE:
  190.                 CenterCr "Testing the centering routine"
  191.  
  192.    Chat ()
  193.         Starts a chat mode with the user.  Restores the colors to normal
  194.         afterwards.
  195.  
  196.         EXAMPLE:
  197.                 SendCr "Forced CHAT:"
  198.                 Chat
  199.  
  200.  
  201.    ClearScreen ()
  202.         Clears the screen
  203.  
  204.         EXAMPLE:
  205.                 ClearScreen
  206.  
  207.   ComParms (BaudRate&, Flag$)
  208.         Sets the communications parameters.  These are already set upon
  209.         initialization.  There should be no need to play with them.
  210.  
  211.         BaudRate& can be:  300, 600, 1200, 2400, 4800, 9600, 19200, 38400
  212.         Flag$ takes the form of: "8N1" where the 8 can be replaced by:
  213.                                         5, 6, 7, 8   (Data bits)
  214.                                  and the N can be replaced by:
  215.                                         N, O, E      (Parity)
  216.                                  and the 1 can be replaced by:
  217.                                         1, 2         (Stop bits)
  218.  
  219.         EXAMPLE:
  220.                 ComParms 2400, "8N1"
  221.  
  222.    CtrlCKOn ()
  223.         Turns on Control-C/K checking.
  224.  
  225.         EXAMPLE:
  226.                 CtrlCKOn
  227.  
  228.    CtrlCKOff ()
  229.         Turns off Control-C/K checking.
  230.  
  231.         EXAMPLE:
  232.                 CtrlCKOff
  233.  
  234.    DeInitialize ()
  235.         Turns off the status bar and removes it from the screen.  Disables
  236.         the door driver and turns off the door driver's internal error
  237.         checking.  Also causes Send, SendCr, and all other routines to
  238.         malfunction.  DO NOT DO ANY OTHER DOOR DRIVER CALLS AFTER
  239.         DE INITIALIZING!  DOES NOT TERMINATE THE PROGRAM.
  240.  
  241.         EXAMPLE:
  242.                 DeInitialize
  243.                 Print "Cleaning up after door"
  244.                 END
  245.  
  246.    DetectAnsi (Ansi%)
  247.         Detects Ansi (Remote user)
  248.         Returns -1 or 0 into Ansi% (or any other variable of your choice)
  249.  
  250.         EXAMPLE:
  251.                 DetectAnsi Ansi%
  252.                 SetAnsi Ansi%
  253.  
  254.    FlushIn ()
  255.         Flushes the inbound modem buffer.  Wipes all user keystrokes.
  256.  
  257.         EXAMPLE:
  258.                 FlushIn
  259.                 Send "What now sire? "
  260.                 GetChar ToDoThis$
  261.                 SendCr ToDoThis$
  262.  
  263.    FlushOut ()
  264.         Flushes the outbound modem buffer.  Usefull for stopping screens
  265.         when Control-C/K have been pressed.
  266.  
  267.         EXAMPLE:
  268.                 SendCr "Press Control-C/K to stop this mess"
  269.                 CtrlCKOn
  270.                 DO
  271.                         SendCr "Testing 1234567890..."
  272.                        I$ = Inkey$
  273.                LOOP UNTIL I$ = CHR$(3) OR I$ = CHR$(11) OR CtrlCK%
  274.                SendCr "Aborted."
  275.  
  276.    GetChar (Ch$)
  277.        Gets a character from the modem into Ch$.  (Ch$ can be any
  278.        variable)
  279.  
  280.        EXAMPLE:
  281.                SendCr "Yo there dude!  Press any key please!"
  282.                GetChar Test$
  283.                SendCr "Thanks!"
  284.  
  285.    GetColor (Fore%, Back%)
  286.        Gets the current foreground and background colors.
  287.  
  288.        EXAMPLE:
  289.                GetColor ForeGround%, BackGround%
  290.                SendCr "The foreground color is: " + STR$(ForeGround%)
  291.                SendCr "The background color is: " + STR$(BackGround%)
  292.  
  293.    GetCurPos (X%, Y%)
  294.        Gets the cursor position.
  295.        X% = The Current Row
  296.        Y% = The Current Column
  297.  
  298.        EXAMPLE:
  299.                GetCurPos X%, Y%
  300.                SendCr "The row is: " + STR$(X%)
  301.                SendCr "The column is: " + STR$(Y%)
  302.         
  303.    GetString (St$, Max%, Mode%)
  304.        Gets a string from the modem/console.
  305.        St$ = The returned string.
  306.        Max% = The max width/value.
  307.        Mode% = Input mode:
  308.                0  :-   Normal Input, exactly as entered.
  309.                        Max% = Maximum length in characters.
  310.                1  :-   UserName Input, Every first character of a word is
  311.                        converted to uppercase.  Uppercase characters after
  312.                        the first letter of each word are accepted.
  313.                        Max% = Maximum length in characters.
  314.                2  :-   Numeric input.  Allows from 0 to the number specified.
  315.                        Allows blank strings for 0.  Returned value is a
  316.                        string.
  317.                        Max% = Maximum value (Integer value; 0 - 32767)
  318.                3  :-   Password input.  Outputs dots (.) instead of entered
  319.                        characters.  Case insensitive.
  320.                4  :-   Telephone number.  Allows all numbers, brackets ()
  321.                        and the dash.
  322.  
  323.        EXAMPLES:
  324.                GetString Test$, 20, 0  'Gets a string of 20 characters long
  325.                                        'into Test$ with no restrictions.
  326.                GetString Test$, 20, 1  'Gets a string of 20 characters long
  327.                                        'into Test$, with username style
  328.                                        'input.
  329.                GetString Test$, 128, 2 'Gets a number into Test$.  Max 128
  330.                GetString Test$, 20, 3  'Gets a password of 20 chars max.
  331.                GetString Test$, 14, 4  'Gets a telephone number of 14 chars
  332.                                        'maximum.
  333.  
  334.    Hangup ()
  335.        Hangs up the user.
  336.  
  337.        EXAMPLE:
  338.                Hangup
  339.  
  340.    Initialize (DOORFile$, ProgName$)
  341.        Initializes the door driver routines.
  342.        DOORFile$ = The path and filename of the DORINFOx.DEF file
  343.        ProgName$ = The name of the door.  Only for registered versions.
  344.  
  345.        EXAMPLES:
  346.                DoorFile$ = "\BBS\DORINFO1.DEF"
  347.                Initialize DoorFile$,"Test Door"
  348.  
  349.  
  350.    LineFeed (Lines%)
  351.        Sends (Lines%) CR/LF pairs.
  352.  
  353.        EXAMPLE:
  354.                LineFeed 20
  355.  
  356.    OfficePhone (Duration!)
  357.        Makes a sound similar to an office phone until any key is pressed
  358.        or the number of seconds specified in Duration! has elapsed!
  359.  
  360.        EXAMPLE:
  361.                OfficePhone 30
  362.  
  363.    ReInitPort ()
  364.        ReInitializes the com port.  Not needed, but here anyways.
  365.  
  366.        EXAMPLE:
  367.                ReInitPort
  368.  
  369.    ResetIdle ()
  370.        Resets the idle time counter to zero.
  371.        Is called upon every Send, SendCr, GetChar (after key press),
  372.        GetString, SendFile, SetColor, Center, CenterCr.
  373.  
  374.        EXAMPLE:
  375.                ResetIdle
  376.  
  377.    Send (St$)
  378.        Sends the specified string to the modem/screen if snoop is on.
  379.        St$ = The string to send.
  380.  
  381.        EXAMPLE:
  382.                Send "Testing 123"
  383.  
  384.    SendCr (St$)
  385.        Sends the specified string to the modem/screen and appends a CR/LF
  386.        pair at the end of it.
  387.        St$ = The string to send.
  388.  
  389.        EXAMPLE:
  390.                SendCr "This is on the line above the line below."
  391.                SendCr "This is on the line below the line above."
  392.  
  393.    SendFile (FileName$, More%, Ck%, Er%)
  394.        Sends a file to the modem/screen.
  395.        FileName$ is the full path/filename of a file to display.  Defaults
  396.         to the current directory.
  397.         If the extension is supplied, your program must determine itself if
  398.         the user supports ANSI or not.  If you do not supply an extension,
  399.         the door driver will attempt to locate a .ANS file if the user has
  400.         ANSI active, if not, it will resort to ASCII (.ASC) and if that
  401.         fails, it will then assume "File not found".
  402.        More% is the toggle for the More prompt.  A non-zero value will
  403.         activate it.  A user can use Ctrl-C/K as a "NO" at the More prompt.
  404.        Ck% is the toggle for Control-C/K aborting.  If this value is
  405.         non-zero, then Ctrl-K/C from either side will stop the file from
  406.         being displayed.  If you want the user to be forced to see the
  407.         whole file, then I recommend making your own sendfile routine and
  408.         making it ask for any key to continue once per x lines.
  409.        Er% is set to a non-zero value if the file isn't found.
  410.        This routine cannot handle disk IO errors, so the Simple Door error
  411.        handler is called upon to do the dirty work.  This means the game
  412.        will terminate.
  413.  
  414.        EXAMPLE:
  415.                SendFile "TEST",0,1,Er%
  416.                IF Er% THEN SendCr "Hey, where'd my file go?"
  417.  
  418.    SetAnsi (AnsiState%)
  419.        Sets the user's ANSI state.  Not recommended unless the user changes
  420.        it himself.
  421.  
  422.        EXAMPLE:
  423.                Send "You have ANSI "
  424.                AnsiMode%=GetAnsi%
  425.                IF AnsiMode% THEN
  426.                        SendCr "enabled"
  427.                ELSE
  428.                        SendCr "disabled"
  429.                ENDIF
  430.  
  431.    SetColor (Fore%, Back%)
  432.        Sets the color.
  433.        Fore% = Foreground color
  434.  
  435.         Color systems------------------------- Monochrome systems-------
  436.  
  437.         0  - Black        1  - Blue            0 -  Black
  438.         2  - Green        3  - Cyan            1 -  Underline
  439.         4  - Red          5  - Magenta         2 to 7 -  Normal
  440.         6  - Brown        7  - White           8 -  Black
  441.         8  - Gray         9  - Light Blue      9 -  Intense Underline
  442.         10 - Light Green  11 - Light Cyan      10 to 15 -  Intense
  443.         12 - Light Red    13 - Light Magenta
  444.         14 - Yellow       15 - Light White
  445.  
  446.        Back% = Background color
  447.  
  448.        Color systems-------------------------- Monochrome systems-------
  449.  
  450.         0  - Black        1  - Blue            0 to 6 -  Black
  451.         2  - Green        3  - Cyan            7 -  White (Only with 0 as
  452.         4  - Red          5  - Magenta              foreground)
  453.         6  - Brown        7  - White
  454.  
  455.        EXAMPLE:
  456.                SetColor 7,1            'White on blue
  457.  
  458.    SetCurPos (X%, Y%)
  459.        Sets the cursor position (ONLY WHEN ANSI IS ACTIVE)
  460.        X% = Row%
  461.        Y% = Col%
  462.        WARNING: No internal checking for the Row% is done.  It must not
  463.        exceed 24 if you want to maintain compatibility with old ANSI
  464.        terminals.
  465.  
  466.        EXAMPLE:
  467.                SetCurPos 9, 1
  468.  
  469.    SetIdle (IdleTim%)
  470.        Sets the idle timeout value (defaults to 240 seconds on startup)
  471.        IdleTim% = number of seconds before idle timeout.  Gives idle
  472.         warning at 30 seconds left.
  473.  
  474.        EXAMPLE:
  475.                SetIdle 250
  476.  
  477.    SetSnoopState (SnSt%)
  478.        Sets the Snoop state.
  479.        SnSt% - The snoop state flag.  Any non-zero value turns on snoop.
  480.        Zero turns it off.
  481.  
  482.        EXAMPLE:
  483.                SetSnoopState -1
  484.  
  485.    StatBarOff ()
  486.        Turns off status bar updates (and disables carrier/time limit
  487.        checking)
  488.        GOOD FOR DISK I/O WHEN REWRITING DATA FILES!
  489.  
  490.        EXAMPLE:
  491.                SendCr "Updating Data file"
  492.                StatBarOff
  493.                .
  494.                .
  495.                .
  496.                StatBarOn
  497.  
  498.    StatBarOn ()
  499.        Turns on the status bar.  (and enables carrier/TIME LIMIT checking)
  500.  
  501.        EXAMPLE:
  502.                [See Previous Command]
  503.  
  504.    StatusBar ()
  505.        Forces an update of the status bar.
  506.  
  507.        EXAMPLE:
  508.                StatusBar
  509.  
  510.    ToggleSnoop ()
  511.        Toggles the snoop setting.
  512.  
  513.        EXAMPLE:
  514.                ToggleSnoop
  515.  
  516.  
  517.                            - License Agreement -
  518.  
  519.         Roy Hooper and the SumWare group do not make any warranties on this
  520. product.  We are not responsible for damage caused by the use or inability
  521. to use this software.  Use of this software constitutes agreements to these
  522. terms. In order for you to release your own programs using Simple Door, you
  523. must register it at $35 Cdn.  Registering this software will provide you
  524. with a registered version 1.00 on a diskette.  Future versions will be
  525. available at a cost of $10 Cdn upgrade fee (mailed on a disk) to registered
  526. users . Updates will be posted in the QUIK_BAS echo and a few others that
  527. are appropriate. Or if you run a bulletin board we will send netmail to
  528. notify you of impending releases. You can contact either Roy Hooper or Rick
  529. Chartrand in the QUIK_BAS echo or by netmail to their node numbers for any
  530. questions relating to Simple Door.
  531.  
  532. Please see the registration form for complete details.
  533.  
  534. Our Netmail Addresses are the following.
  535.  
  536.                Roy Hooper                      Rick Chartrand
  537.                1:243/30@Fidonet.org            1:243/26@Fidonet.org
  538.                50:5613/265@EchoNet.org         50:5613/234@Echonet.org
  539.                100:649/40@Rfn.org              Echo Valley
  540.                18:613/106@SbNet.org            Phone # 613-749-1016
  541.                Parity Error BBS                2400 bps
  542.                Phone # 613-737-0966
  543.                2400Bps
  544.  
  545. Other SumWare Software products are available at at the following BBS'es
  546.  
  547. Echo Valley              613-749-1016 1:243/26 2400bps
  548. Parity Error             613-737-0966 1:243/30 2400bps
  549. The Land Of The Cult BBS 613-830-0706 1:243/31 14.4 DS HST
  550.  
  551.