OS/2 Shareware BBS: 2 BBS/02-BBS.zip/v612docs.zip/VAC

Text File | 1993-12-17 | 13KB | 370 lines

.TOPIC:
Virtual Developer's ToolKit
                                    VBBS 6.12 Documentation--C-1

       ╔═════════════════════════════════════════════════════════════╗
       ║   APPENDIX C         VIRTUAL DEVELOPERS TOOLKIT             ║
       ╚═════════════════════════════════════════════════════════════╝

       The Virtual Developer's Toolkit is a set of files that enable
       you to create doors for VBBS systems quickly and easily. The
       "toolkit" enables you to write multi-user serial port-based
       programs, using serial port access methods similar to that used
       by VBBS. It is designed for writing doors (games, utilities,
       etc) for VBBS specifically.

       It is assumed that you know how to program in QuickBASIC. The
       toolkit gives competent BASIC programmers an easy interface for
       writing VBBS doors by taking care of serial port access, user
       data loading, and VBBS specifics automatically.

       Your programs will essentially act as "extensions" to the main
       VBBS program -- accessing the same user data -- using the same
       serial port access methods (via internal routines, or FOSSIL,
       depnding on VCONFIG switch). Think of the toolkit as being a
       quick and easy way to build auxillary modules for your VBBS
       System.

       The routines included in the Virtual Developer's TookKit are
       listed below.  The VDTK is available for $49 from Virtual
       Technologies.  Documentation includes examples on how to use
       each routine, what variable is called, what is returned, and
       a complete example of a game written using the toolkit.

       Routines Descriptions
       ═════════════════════

       DECLARE SUB openport ALIAS "OPENPORT" (PORT%, PORTX%, IRQ%, FLOW%)
       Function:
       This statement opens up the serial port at the
       hardware level. The appropriate INT vector is captured, with the
       old value being saved. The appropriate IRQ is enabled. The
       UART's IRQs are enabled for "interrupt on character received."

       DECLARE SUB closeport ALIAS "CLOSEPORT" ()
       Function:
       This statement closes the serial port at the hardware
       level. The old INT vector is restored. The appropriate IRQ is
       disabled. The UART's IRQs are disabled.

       DECLARE SUB outline ALIAS "XMIT" (x$)
       Function:
       This statement sends a string through the serial port.
       (at lightening speed)

       DECLARE SUB cdcheckz ALIAS "CDCHECKZ" (x%)
       Function:
       This statement checks the carrier status.
                                         VBBS 6.12 Documentation--C-2

       DECLARE SUB comhitz ALIAS "COMHITZ" (x%)
       Function:
       Checks the status of the serial input buffer.

       DECLARE SUB readport ALIAS "RDPORT" (a%)
       Function:
       This statement retrieves a character from the serial
       input buffer. This statement should only be called after first
       calling "comhitz" to make sure that there is actually a
       character waiting.

       DECLARE SUB dtrz ALIAS "DTRZ" (a%)
       Function:
       This statement sets or resets the DTR line as needed.
       During a normal session the DTR line should be logical level 1.
       Lowering the DTR line should have the effect of hanging up the
       modem.

       DECLARE SUB rtsz ALIAS "RTSZ" (a%)
       Function:
       Sets or reset the RTS (Request To Send) as needed.
       This line should always be logical level 1.

       DECLARE SUB dvpausez ALIAS "DVPAUSEZ" ()
       Function:
       Tell desqview this task is just waiting for user
       input, and give time to other tasks.

       DECLARE SUB chkfile ALIAS "CHKFILEZ" (x$, x&)
       Function:
       Checks for file existance, and returns size if found.

       DECLARE FUNCTION comhit ()
       Function:
       Returns the status of the input buffer. 1 = character
       waiting, 0 = no characters waiting -

       DECLARE FUNCTION ctime (a, b)
       Function:
       This function is used to calculate the time elapsed
       between two time values. Time values are in minutes (1440 per
       day).

       DECLARE FUNCTION ctime2& (a&, b&)
       Function:
       This function is similar to ctime(), but it works in
       seconds instead of minutes.

       DECLARE FUNCTION form$ (x, y, n!)
       Function:
       This function is used to justify numeric data. You
       specify the number of digits on left and right of the decimal
       point (for whole numbers 'y' can be set to 0).

       DECLARE FUNCTION num1$ (a)
       Function:
       Converts a number to a string.
                                         VBBS 6.12 Documentation--C-3

       DECLARE FUNCTION num2$ (a&)
       Function:
       Converts a number to a string.

       DECLARE FUNCTION num3$ (a!)
       Function:
       Converts a number to a string.

       DECLARE FUNCTION opencntl ()
       Function:
       This function opens up the CONTROL.DAT file.

       DECLARE FUNCTION openuser ()
       Function:
       This function opens up the user file, using file
       number 9.

       DECLARE FUNCTION readchar ()
       Function:
       This function is used to read characters form the
       serial input queue. Note: You must use the comhit function to
       insure there are characters waiting!

       DECLARE FUNCTION strlen (a$)
       Function:
       This function is similar to BASIC's LEN() function,
       except that heart code characters and ANSI codes are not
       counted.

       DECLARE FUNCTION sysdate$ ()
       Function:
       This function retrieves the current date in YYMMDD
       format

       DECLARE SUB ansic (x)
       Function:
       This statement causes the program to emit the ANSI
       sequences needed to change the color to the ones desired.

       DECLARE SUB broadcast (t$, prt)
       Function:
       Broadcast a string message to a certain channel. Use in a loop to
       broadcast system-wide

       DECLARE SUB bs (a)
       Function:
       Performs the number of backspaces needed.

       DECLARE SUB cdcheck ()
       Function:
       Sets COMMON SHARED variable cdchk to the current
       carrier detect status.

       DECLARE SUB charin (a)
       Function:
       This is the basic low-level character input statement.
       It handles SysOp Local Function Keys also.
                                         VBBS 6.12 Documentation--C-4

       DECLARE SUB checkbrk ()
       Function:
       Check for user abort key. Returns status in the COMMON
       SHARED variable brkf.

       DECLARE SUB checkq ()
       Function:
       Checks the user's broadcast input queue and prints out
       any data it finds.

       DECLARE SUB checktime ()
       Function:
       Sets COMMON SHARED variable left with the time user
       has left on in minutes. Sets COMMON SHARED variable timeon with
       the time user has been on in minutes.

       DECLARE SUB cll ()
       Function:
       Clears the local screen.

       DECLARE SUB clrs ()
       Function:
       Clears the local screen and the remote user's screen.

       DECLARE SUB cxy (y, x)
       Function:
       Sets cursor position on the local screen and the
       remote user's screen.

       DECLARE SUB deinitport ()
       Function:
       This statement closes the serial port. It should be
       called before exiting the program. See initport, below.

       DECLARE SUB del (f$)
       Function:
       Delete the file specified. Cannot contain wildcards.

       DECLARE SUB docr ()
       Function:
       Does a carriage return/line feed sequence.

       DECLARE SUB dos (z$)
       Function:
       Perform a DOS function or execute another program ON
       TOP of your program. Control returns to your program where it
       left off when the called function or program exits.

       DECLARE SUB drawtextbox (j$, rpr$, iblen)
       Function:
       This command boxes in text with or without an input
       box on the end.

       DECLARE SUB dtr (a)
       Function: Sets or resets the DTR line.
                                         VBBS 6.12 Documentation--C-5

       DECLARE SUB dvpause ()
       Function:
       Tell desqview this task is just waiting for user
       input, and give time to other tasks.

       DECLARE SUB echofile (f$)
       Function:
       Prints the contents of a text file to the screen and
       remote user.

       DECLARE SUB endprogram ()
       Function:
       Ends your program safely. This should be the very last
       statement executed by your program. See 'initialize.'

       DECLARE SUB flush ()
       Function:
       Flushes the serial input buffer

       DECLARE SUB getclr (c, c$)
       Function:
       This function is useful for retreiving the color code
       in string format for storage (and later printing) from the
       numeric code.

       DECLARE SUB getline (t$, e$)
       Function:
       e$ plays a key role in the use of this statement.

       DECLARE SUB getny (a$, p$)
       Function:
       Displays (optional) prompt, and gets YES or NO input,
       with default (Enter) being NO. Its usually a good idea to check
       for carrier after any type of input statement.

       DECLARE SUB getyn (a$, p$)
       Function:
       Displays (optional) prompt, and gets YES or NO input,
       with default (Enter) being YES. Its usually a good idea to check
       for carrier after any type of input statement.

       DECLARE SUB initport ()
       Function:
       Reads the serial channel configuration file and
       initializes the serial port.

       DECLARE SUB initialize ()
       Function:
       This is the MAIN statement that should be the first
       statement in the main code level of your program. It will take
       care of setting up everything. See 'endprogram.'

       DECLARE SUB lockfile (a%)
       Function:
       This statement lets you lock a resource for critical
       multiuser operation. Bits 0 to 12 are *reserved for use by VBBS
       internally.
                                         VBBS 6.12 Documentation--C-6
       DECLARE SUB loopkey (a)
       Function:
       This statement is the main loop of activity during
       user input. Inactivity timeout used is that set in VCONFIG, and
       in addition, user time limits are continually monitored.

       DECLARE SUB menu2 (file$)
       Function:
       Searches the VBBS Text Directory in the following
       sequence:

       <filename>.MNU   -- Universal Heart Code Menus  if not found:
       if user has ansi:        <filename>.ANS  -- ANSI    else
       <filename>.ASC  -- Pure ASCII


       DECLARE SUB pause (v$)
       Function:
       The basic "press any key to continue" type statement.

       DECLARE SUB rl (a$, m$, ul, j$)
       Function:
       Displays the optional prompt, and waits for user
       input. Only characters in the list of allowed input characters
       will be accepted for input, or numeric input within the range 1
       to ul will be allowed. Numeric input features a smart
       "auto-enter" feature.

       DECLARE SUB rr (a$, r$, j$)
       Function:
       Displays the optional prompt, and waits for user
       input. Only characters in the list of allowed input characters
       will be accepted for input.

       DECLARE SUB serwrt (t$)
       Function:
       Prints a string to the serial port and screen exactly
       as it is. NO carriage returns or line feeds are added.

       DECLARE SUB setloc (x$)
       Function:
       Sets the user's current "action" or "location" on the
       system.

       DECLARE SUB statusline ()
       Function:
       Refreshes the status line on the top of the screen.

       DECLARE SUB syslog (v$)
       Function:
       This statement appends information into the VBBS
       system log.

       DECLARE SUB unlockfile (a%)
       Function:
       This statement lets you unlock a resource for critical
       multiuser operation. Bits 0 to 12 are *reserved for use by VBBS
       internally.
                                         VBBS 6.12 Documentation--C-7

       DECLARE SUB waits (s)
       Function:
       Performs time delays, defined in seconds.

       DECLARE SUB who ()
       Function:
       Displays who is currently online, and what they are
       doing.

       DECLARE SUB writeln (t$)
       Function:
       Prints a string of data to the serial port and the
       local screen, with a carriage return/line feed sequence
       automatically being printed after the string. Writeln also does
       "break checking" (space bar), pause checking (P), and also
       checks the line count to see if its time for a page break.