.TOPIC:                                            
Database Operations

                                            VBBS 6.12 Documentation -- 10-C-1


         ͻ
          CHAPTER TEN ANNEX C      DATABASE OPERATIONS                   
         ͼ


                Each database (DB) in VBBS can be used in many different
         ways for storing info.  A DB can store normal messages, file
         descriptions, or even messages with attached files. Also, there
         is no reason why you can't redefine the fields and use them for
         other types of data storage, like a special voting booth or
         customized daily news section.

                Each DB entry is made up of two parts - The Header and the
         Memo Section. The Header contains things like the subject, the
         sender's name, addressee, etc. The Memo Section is the actual
         body of the entry.  The body, while always text, may contain
         either a standard message or a long file description, depending
         on how you are using the database.


         DATABASE SELECTION
         

                Before you can implement any database commands you must
          first select the exact database you wish to use.  This is done
          with the commands DBGROUP and DB.  You must use the commands
          in the order shown for proper results.

          DBGROUP ->  DBGROUP <group identifier>

                This selects the database group that you will be using in
          the script.  The <group identifier> is the character representing
          the DBG as it appears in VCONFIG, Ascii characters 33-255.
          ex: DBGROUP A     <-- This makes DBGroup A the active area.

                Before you can select a database to use, you must first
          select a database group.  Grouping was implemented so that it
          would be much easier to implement global functions and so that
          databases may be added and deleted (using VCONFIG.EXE) without
          the need to edit the scripts every time.  The <group identifier>
          is a single alphabetic character (from A to Z) and you can set
          your database groups up any way you like.  A common set of DB
          Groups might be:
           <A> Public message bases    <H> Hidden/restricted message bases
           <F> Public file bases       <I> Hidden/restricted file bases
           <O> Special bases like voting sections, daily news, etc.

          The following read-only variables are loaded when you execute
          the DBGROUP command:
          --------------------
           $DBNUMBER - Stores the total number of databases in the selected
                       group.  The lowest numbered DB in a group is always
                       a 1, so this number supplies the upper limit for
                       loop operations within a database group.


                                            VBBS 6.12 Documentation -- 10-C-2


           $DBGROUP  - This stores the character you selected on the DBGROUP
                       command line. Note: This variable is not cleared
                       when you LINK to another script (see section 7.3),
                       so this can be used to keep track of your location.
           --------------------

         DB ->  DB <database number>

               The DB commands sets the current database for use. You
           must select a database using this command somewhere in your
           script before any of the other database commands (except
           DBGROUP) are used. Once you set the database, it stays set
           until another DB command is executed. Also, the database must
           have been defined previously using VCONFIG.EXE.

           The following read-only variables are loaded when you execute
           the DB command:
           --------------------
           $DB       - This stores the database number you have selected.
                       Like $DBGROUP it is not cleared when you LINK
                       between scripts and so using the two variables you
                       can maintain a constant position within your DBs.
           $DBNAME   - The long name of the selected database.
           $DBPATH   - The path (if any) in the 'File Path' section of the
                       VCONFIG Database entry.
           $DBFILE   - The filename of the actual database storage file.
           $HIGHDB   - This is the pointer that stores the number of the
                       user's highest-read entry in the database.
           $NUMBERDB - This stores the total number of entries in the
                       database.
           $WRITESL  - This contains the minimum security level needed to
                       write to the database.
           --------------------


         LOAD RELATED COMMANDS
         

                The next few commands are all used to manually load in a
         database entry for display and/or analysis.

         LOAD ->  LOAD <value1> <option>

               This command loads the database entry <value1> and has
           one command <option>. Adding /Q to the command line will set
           it so the user's $HIGHDB pointer is not updated. The command
           also loads the following variables:
           --------------------
           $ATTFILE  - Filename of a file that is attached to the message,
                       if any.
           $DBCOUNT  - This variable starts at 0 and can be increased by
                       using the ADDCOUNT command (see section 4.3).  It
                       can not be decreased and has one value for each DB
                       (not for each individual message or file.)


                                            VBBS 6.12 Documentation -- 10-C-3



           $DBDATE   - Creation date and time of the entry.
           $DBFLAG   - The value can have a value of 0 or 1 and can be
                       toggled with the DBFLAG command (see section 4.3).
                       The value of this variable is constant, so if it is
                       turned ON it is treated as ON for all users who
                       access the message/file affected.
           $FROM     - The handle of the person who created the entry.
           $FROMNO   - The user # of the person who created the entry.
           $FROMNODE - VirtualNET node number of sender.
           $SIZE     - Size of attached file, set to 0 if none.
           $SUBJECT  - The subject of the message, or brief description
                       for a file entry.
           $TO       - The handle of the addressee, if any.
           $TONO     - The user # of the addressee, 0 if to ALL.
           $TONODE   - VirtualNET node number of addressee.
           $RESULT   - This variable contains one of these items:
                         DEL if <value1> is marked for deletion
                         OUT if <value1> is greater than the number of
                             available entries (listed in $NUMBERDB)
                         PRI if the DB is private and the user is not
                             the sender, addressee, or has an SL below
                             250 (ie Sysop or CoSysop)
                         OK  in all other cases
           --------------------

         DISPLAYMSG <---

                This command displays the message header info to the user.
           It will clear the screen before showing this info if the user
           is using enhanced ANSI (see VBBS.DOC for more information.)

         DISPLAYTEXT <---

                This command displays the memo section of the message to
           the user.  It clears the screen like DISPLAYMSG for enhanced
           ANSI users.


         EDITING COMMANDS
         

                All of these commands operate independently of the LOAD
         command.  They do still require you to select a DBGROUP and DB
         before use, however.

         ADDCOUNT ->  ADDCOUNT <value1>

                This command increases the number stored in the $DBCOUNT
           by 1 if <value1> is a positive number.


                                            VBBS 6.12 Documentation -- 10-C-4



         CLEANUP <---

                This performs the PACK function (below) on all databases.
           This command does not require the use of the DBGROUP or DB
           commands before use.

         DBFLAG ->  DBFLAG <value1> <switch>

                This command toggles the value stored in $DBFLAG for the
           entry <value1>.  The valid switches are ON or OFF and the
           matching $DBFLAG values are 1 and 0, respectively.

         DEL ->  DEL <value1>

               This command marks the entry <value1> for deletion.  It
           also returns the $RESULT variable with the possible values
           being OUT, PRI, and OK (see LOAD entry above.)

         PACK <---

               This command deletes all messages within the selected DB
           that have been marked for deletion and then resequences the
           database.  All user and network pointers are automatically
           updated to show the change in message numbers.

         QS ->  QS <value1>

               Manually set the user's $HIGHDB pointer to <value1>. If
           <value1> exceeds the value in $NUMBERDB then $HIGHDB is set
           to equal $NUMBERDB.

         SAVE -> (command on next line due to length)
         SAVE <value1> <value2> <string3> <value4> <filename5> <value6>

               This command makes a database entry and saves it in the
           current database.  The variables used are:
           --------------------
           <value1>    - This is the user # that the message is addressed
                         to, this should be set to 0 if to ALL.
           <value2>    - This is the network address of the addressee,
                         use $NODE if the addressee is local.
           <string3>   - This will be the $SUBJECT of the saved message.
           <value4>    - This contains the size of the attached file, use
                         0 if none.
           <filename5> - This is the name of the attached file, use "" if
                         none.
           <value6>    - This is the network ID of the addressee, use 1 if
                         the addressee is local.
           --------------------
               The message saved uses the above information to create the
           header and then takes the contents of the buffer and uses it as
           the main body of the message.  See section 5.x for information
           on how to use the buffer.  This command can not be used to send
           files attached to emails, it can only be used to add files to a
           database listing.


                                            VBBS 6.12 Documentation -- 10-C-5



         SEARCH ->  SEARCH <value1> <number2> <string3>

               This command searches the contents of the database for
           <string3> starting at the entry <value1>. The search is case
           insensitive on <string3>. The value for <number2> can be any
           of the following:
             1 - Search the TO field    <string3> is ignored here as it
             2 - Search the FROM field  looks for the current user only
                                          with both of these settings. 
             3 - Search the SUBJECT/TITLE field, <string3> can be any word
                 or group of words.
             4 - Search the FILENAME field, <string3> must be an acceptable
                 DOS filename including wildcards.
             5 - Search the FILENAME field, <string3> must be an acceptable
                 DOS filename with no wildcards.

           This command also returns two variables:
           --------------------
           $RESULT = OUT if <string3> is not found, OK if otherwise.
           $SEARCH = the entry number where <string3> was found.
           --------------------


         VIEWING & WRITING
         

         ͻ
         ** Note:All commands marked with a (*) before the description **
         **      will only work properly if implemented from within    **
         **      a script that was called from a function block that   **
         **      has DBGroup(s) listed in it.  They take the letters   **
         **      for the DBGroups to use from the second line of the   **
         **      .FB the script was called from.  The DBGROUP and DB   **
         **      commands do not affect any of these commands.         **
         ͼ

               These commands allow the user to view messages and move
           around within your databases.

         CHOOSETOPIC <---

         (*)   This command lists all the DBGroups (also known as topics)
           and allows the user to switch over to a different one.  The
           user can also view an index of all databases available from
           within this option.

         LISTBASES <---

         (*)   This lists all the DB's in the current DBGroup.

         NEXTBASE <---
         PREVBASE <---

               These commands move to the next or previous database within
           the selected DBGroup, respectively.


                                            VBBS 6.12 Documentation -- 10-C-6



         POST <---

               This lets the user to enter a message into the active DB.

         READSEQMSG <---

               This command allows the user to read the messages within
           the current database.  It also contains a search feature.

         READNEWMSG <---

               This starts the user's new message scan, showing all new
           messages in databases that are in the user's quick-scan list.


         SCANMSG <---

               This command brings up a summary of the messages in the
           selected database.  The user can select a message to read from
           this listing and has access to all sub-menu commands while
           reading the messages.

         SELECTBASE <---

         (*)   This command lists all the bases and then allows the user
           to select a different DB as the current one.  The user can
           also switch to a different DBGroup with this command.

         SETQUICKSCAN <---

         (*)   This command allows the user to select what databases he or
           she would like to view during a new message scan.


         E-MAIL FUNCTIONS
         

               The E-mail section of the database structure is a separate
           entity.  To make it the active database for using the SAVE
           and BUFFER commands you need to execute the following command:

         SETEMAIL <---

              This command is used instead of the DBGROUP & DB commands to
           make the e-mail section the active database for use with BUFFER
           and SAVE (see sections 5.x and 4.3, respectively.)

         FEEDBACK <---

               This brings up the multi-feedback list (see VBBS.DOC)
           and prompts the user to send a message to the sysop.


                                            VBBS 6.12 Documentation -- 10-C-7



         QUICKMAIL <---

               This brings up the multi-mail menu for sending e-mail to
           a group of people all at once.

         READALLEMAIL <---

               This is a sysop command that allows you to read all E-mail
           currently in the system.

         READEMAILFROM <---
         READEMAILTO <---

               These commands allow the user to read all the E-mail FROM
           them or addressed TO them, respectively.

         SENDEMAIL <---

               This command allows the user to send E-mail to other users.


