home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / v611docs.zip / VMAIN611.ZIP / VC10-AC < prev    next >
Text File  |  1993-10-08  |  16KB  |  378 lines

  1.                                             VBBS 6.11 Documentation -- 10-C-1
  2.  
  3.  
  4.          ╔════════════════════════════════════════════════════════════════╗
  5.          ║ CHAPTER TEN ANNEX C      DATABASE OPERATIONS                   ║
  6.          ╚════════════════════════════════════════════════════════════════╝
  7.  
  8.  
  9.                 Each database (DB) in VBBS can be used in many different
  10.          ways for storing info.  A DB can store normal messages, file
  11.          descriptions, or even messages with attached files. Also, there
  12.          is no reason why you can't redefine the fields and use them for
  13.          other types of data storage, like a special voting booth or
  14.          customized daily news section.
  15.  
  16.                 Each DB entry is made up of two parts - The Header and the
  17.          Memo Section. The Header contains things like the subject, the
  18.          sender's name, addressee, etc. The Memo Section is the actual
  19.          body of the entry.  The body, while always text, may contain
  20.          either a standard message or a long file description, depending
  21.          on how you are using the database.
  22.  
  23.  
  24.          DATABASE SELECTION
  25.          ══════════════════
  26.  
  27.                 Before you can implement any database commands you must
  28.           first select the exact database you wish to use.  This is done
  29.           with the commands DBGROUP and DB.  You must use the commands
  30.           in the order shown for proper results.
  31.  
  32.           DBGROUP ->  DBGROUP <group identifier>
  33.  
  34.                 This selects the database group that you will be using in
  35.           the script.  The <group identifier> is the letter representing
  36.           the DBG as it appears in VCONFIG.  See VBBS.DOC for more info.
  37.           ex: DBGROUP A     <-- This makes DBGroup A the active area.
  38.  
  39.                 Before you can select a database to use, you must first
  40.           select a database group.  Grouping was implemented so that it
  41.           would be much easier to implement global functions and so that
  42.           databases may be added and deleted (using VCONFIG.EXE) without
  43.           the need to edit the scripts every time.  The <group identifier>
  44.           is a single alphabetic character (from A to Z) and you can set
  45.           your database groups up any way you like.  A common set of DB
  46.           Groups might be:
  47.            <A> Public message bases    <H> Hidden/restricted message bases
  48.            <F> Public file bases       <I> Hidden/restricted file bases
  49.            <O> Special bases like voting sections, daily news, etc.
  50.  
  51.           The following read-only variables are loaded when you execute
  52.           the DBGROUP command:
  53.           --------------------
  54.            $DBNUMBER - Stores the total number of databases in the selected
  55.                        group.  The lowest numbered DB in a group is always
  56.                        a 1, so this number supplies the upper limit for
  57.                        loop operations within a database group.
  58.  
  59.  
  60.                                             VBBS 6.11 Documentation -- 10-C-2
  61.  
  62.  
  63.            $DBGROUP  - This stores the letter you selected on the DBGROUP
  64.                        command line. Note: This variable is not cleared
  65.                        when you LINK to another script (see section 7.3),
  66.                        so this can be used to keep track of your location.
  67.            --------------------
  68.  
  69.          DB ->  DB <database number>
  70.  
  71.                The DB commands sets the current database for use. You
  72.            must select a database using this command somewhere in your
  73.            script before any of the other database commands (except
  74.            DBGROUP) are used. Once you set the database, it stays set
  75.            until another DB command is executed. Also, the database must
  76.            have been defined previously using VCONFIG.EXE.
  77.  
  78.            The following read-only variables are loaded when you execute
  79.            the DB command:
  80.            --------------------
  81.            $DB       - This stores the database number you have selected.
  82.                        Like $DBGROUP it is not cleared when you LINK
  83.                        between scripts and so using the two variables you
  84.                        can maintain a constant position within your DBs.
  85.            $DBNAME   - The long name of the selected database.
  86.            $DBPATH   - The path (if any) in the 'File Path' section of the
  87.                        VCONFIG Database entry.
  88.            $DBFILE   - The filename of the actual database storage file.
  89.            $HIGHDB   - This is the pointer that stores the number of the
  90.                        user's highest-read entry in the database.
  91.            $NUMBERDB - This stores the total number of entries in the
  92.                        database.
  93.            $WRITESL  - This contains the minimum security level needed to
  94.                        write to the database.
  95.            --------------------
  96.  
  97.  
  98.          LOAD RELATED COMMANDS
  99.          ═════════════════════
  100.  
  101.                 The next few commands are all used to manually load in a
  102.          database entry for display and/or analysis.
  103.  
  104.          LOAD ->  LOAD <value1> <option>
  105.  
  106.                This command loads the database entry <value1> and has
  107.            one command <option>. Adding /Q to the command line will set
  108.            it so the user's $HIGHDB pointer is not updated. The command
  109.            also loads the following variables:
  110.            --------------------
  111.            $ATTFILE  - Filename of a file that is attached to the message,
  112.                        if any.
  113.            $DBCOUNT  - This variable starts at 0 and can be increased by
  114.                        using the ADDCOUNT command (see section 4.3).  It
  115.                        can not be decreased and has one value for each DB
  116.                        (not for each individual message or file.)
  117.  
  118.  
  119.                                             VBBS 6.11 Documentation -- 10-C-3
  120.  
  121.  
  122.  
  123.            $DBDATE   - Creation date and time of the entry.
  124.            $DBFLAG   - The value can have a value of 0 or 1 and can be
  125.                        toggled with the DBFLAG command (see section 4.3).
  126.                        The value of this variable is constant, so if it is
  127.                        turned ON it is treated as ON for all users who
  128.                        access the message/file affected.
  129.            $FROM     - The handle of the person who created the entry.
  130.            $FROMNO   - The user # of the person who created the entry.
  131.            $FROMNODE - VirtualNET node number of sender.
  132.            $SIZE     - Size of attached file, set to 0 if none.
  133.            $SUBJECT  - The subject of the message, or brief description
  134.                        for a file entry.
  135.            $TO       - The handle of the addressee, if any.
  136.            $TONO     - The user # of the addressee, 0 if to ALL.
  137.            $TONODE   - VirtualNET node number of addressee.
  138.            $RESULT   - This variable contains one of these items:
  139.                          DEL if <value1> is marked for deletion
  140.                          OUT if <value1> is greater than the number of
  141.                              available entries (listed in $NUMBERDB)
  142.                          PRI if the DB is private and the user is not
  143.                              the sender, addressee, or has an SL below
  144.                              250 (ie Sysop or CoSysop)
  145.                          OK  in all other cases
  146.            --------------------
  147.  
  148.          DISPLAYMSG <---
  149.  
  150.                 This command displays the message header info to the user.
  151.            It will clear the screen before showing this info if the user
  152.            is using enhanced ANSI (see VBBS.DOC for more information.)
  153.  
  154.          DISPLAYTEXT <---
  155.  
  156.                 This command displays the memo section of the message to
  157.            the user.  It clears the screen like DISPLAYMSG for enhanced
  158.            ANSI users.
  159.  
  160.  
  161.          EDITING COMMANDS
  162.          ════════════════
  163.  
  164.                 All of these commands operate independently of the LOAD
  165.          command.  They do still require you to select a DBGROUP and DB
  166.          before use, however.
  167.  
  168.          ADDCOUNT ->  ADDCOUNT <value1>
  169.  
  170.                 This command increases the number stored in the $DBCOUNT
  171.            by 1 if <value1> is a positive number.
  172.  
  173.  
  174.                                             VBBS 6.11 Documentation -- 10-C-4
  175.  
  176.  
  177.  
  178.          CLEANUP <---
  179.  
  180.                 This performs the PACK function (below) on all databases.
  181.            This command does not require the use of the DBGROUP or DB
  182.            commands before use.
  183.  
  184.          DBFLAG ->  DBFLAG <value1> <switch>
  185.  
  186.                 This command toggles the value stored in $DBFLAG for the
  187.            entry <value1>.  The valid switches are ON or OFF and the
  188.            matching $DBFLAG values are 1 and 0, respectively.
  189.  
  190.          DEL ->  DEL <value1>
  191.  
  192.                This command marks the entry <value1> for deletion.  It
  193.            also returns the $RESULT variable with the possible values
  194.            being OUT, PRI, and OK (see LOAD entry above.)
  195.  
  196.          PACK <---
  197.  
  198.                This command deletes all messages within the selected DB
  199.            that have been marked for deletion and then resequences the
  200.            database.  All user and network pointers are automatically
  201.            updated to show the change in message numbers.
  202.  
  203.          QS ->  QS <value1>
  204.  
  205.                Manually set the user's $HIGHDB pointer to <value1>. If
  206.            <value1> exceeds the value in $NUMBERDB then $HIGHDB is set
  207.            to equal $NUMBERDB.
  208.  
  209.          SAVE -> (command on next line due to length)
  210.          SAVE <value1> <value2> <string3> <value4> <filename5> <value6>
  211.  
  212.                This command makes a database entry and saves it in the
  213.            current database.  The variables used are:
  214.            --------------------
  215.            <value1>    - This is the user # that the message is addressed
  216.                          to, this should be set to 0 if to ALL.
  217.            <value2>    - This is the network address of the addressee,
  218.                          use $NODE if the addressee is local.
  219.            <string3>   - This will be the $SUBJECT of the saved message.
  220.            <value4>    - This contains the size of the attached file, use
  221.                          0 if none.
  222.            <filename5> - This is the name of the attached file, use "" if
  223.                          none.
  224.            <value6>    - This is the network ID of the addressee, use 1 if
  225.                          the addressee is local.
  226.            --------------------
  227.                The message saved uses the above information to create the
  228.            header and then takes the contents of the buffer and uses it as
  229.            the main body of the message.  See section 5.x for information
  230.            on how to use the buffer.  This command can not be used to send
  231.            files attached to emails, it can only be used to add files to a
  232.            database listing.
  233.  
  234.  
  235.                                             VBBS 6.11 Documentation -- 10-C-5
  236.  
  237.  
  238.  
  239.          SEARCH ->  SEARCH <value1> <number2> <string3>
  240.  
  241.                This command searches the contents of the database for
  242.            <string3> starting at the entry <value1>. The search is case
  243.            insensitive on <string3>. The value for <number2> can be any
  244.            of the following:
  245.              1 - Search the TO field    ┌<string3> is ignored here as it┐
  246.              2 - Search the FROM field  │looks for the current user only│
  247.                                         └  with both of these settings. ┘
  248.              3 - Search the SUBJECT/TITLE field, <string3> can be any word
  249.                  or group of words.
  250.              4 - Search the FILENAME field, <string3> must be an acceptable
  251.                  DOS filename including wildcards.
  252.              5 - Search the FILENAME field, <string3> must be an acceptable
  253.                  DOS filename with no wildcards.
  254.  
  255.            This command also returns two variables:
  256.            --------------------
  257.            $RESULT = OUT if <string3> is not found, OK if otherwise.
  258.            $SEARCH = the entry number where <string3> was found.
  259.            --------------------
  260.  
  261.  
  262.          VIEWING & WRITING
  263.          ═════════════════
  264.  
  265.          ╔════════════════════════════════════════════════════════════════╗
  266.          ║** Note:All commands marked with a (*) before the description **║
  267.          ║**      will only work properly if implemented from within    **║
  268.          ║**      a script that was called from a function block that   **║
  269.          ║**      has DBGroup(s) listed in it.  They take the letters   **║
  270.          ║**      for the DBGroups to use from the second line of the   **║
  271.          ║**      .FB the script was called from.  The DBGROUP and DB   **║
  272.          ║**      commands do not affect any of these commands.         **║
  273.          ╚════════════════════════════════════════════════════════════════╝
  274.  
  275.                These commands allow the user to view messages and move
  276.            around within your databases.
  277.  
  278.          CHOOSETOPIC <---
  279.  
  280.          (*)   This command lists all the DBGroups (also known as topics)
  281.            and allows the user to switch over to a different one.  The
  282.            user can also view an index of all databases available from
  283.            within this option.
  284.  
  285.          LISTBASES <---
  286.  
  287.          (*)   This lists all the DB's in the current DBGroup.
  288.  
  289.          NEXTBASE <---
  290.          PREVBASE <---
  291.  
  292.                These commands move to the next or previous database within
  293.            the selected DBGroup, respectively.
  294.  
  295.  
  296.                                             VBBS 6.11 Documentation -- 10-C-6
  297.  
  298.  
  299.  
  300.          POST <---
  301.  
  302.                This lets the user to enter a message into the active DB.
  303.  
  304.          READSEQMSG <---
  305.  
  306.                This command allows the user to read the messages within
  307.            the current database.  It also contains a search feature.
  308.  
  309.          READNEWMSG <---
  310.  
  311.                This starts the user's new message scan, showing all new
  312.            messages in databases that are in the user's quick-scan list.
  313.  
  314.  
  315.          SCANMSG <---
  316.  
  317.                This command brings up a summary of the messages in the
  318.            selected database.  The user can select a message to read from
  319.            this listing and has access to all sub-menu commands while
  320.            reading the messages.
  321.  
  322.          SELECTBASE <---
  323.  
  324.          (*)   This command lists all the bases and then allows the user
  325.            to select a different DB as the current one.  The user can
  326.            also switch to a different DBGroup with this command.
  327.  
  328.          SETQUICKSCAN <---
  329.  
  330.          (*)   This command allows the user to select what databases he or
  331.            she would like to view during a new message scan.
  332.  
  333.  
  334.          E-MAIL FUNCTIONS
  335.          ════════════════
  336.  
  337.                The E-mail section of the database structure is a separate
  338.            entity.  To make it the active database for using the SAVE
  339.            and BUFFER commands you need to execute the following command:
  340.  
  341.          SETEMAIL <---
  342.  
  343.               This command is used instead of the DBGROUP & DB commands to
  344.            make the e-mail section the active database for use with BUFFER
  345.            and SAVE (see sections 5.x and 4.3, respectively.)
  346.  
  347.          FEEDBACK <---
  348.  
  349.                This brings up the multi-feedback list (see VBBS.DOC)
  350.            and prompts the user to send a message to the sysop.
  351.  
  352.  
  353.                                             VBBS 6.11 Documentation -- 10-C-7
  354.  
  355.  
  356.  
  357.          QUICKMAIL <---
  358.  
  359.                This brings up the multi-mail menu for sending e-mail to
  360.            a group of people all at once.
  361.  
  362.          READALLEMAIL <---
  363.  
  364.                This is a sysop command that allows you to read all E-mail
  365.            currently in the system.
  366.  
  367.          READEMAILFROM <---
  368.          READEMAILTO <---
  369.  
  370.                These commands allow the user to read all the E-mail FROM
  371.            them or addressed TO them, respectively.
  372.  
  373.          SENDEMAIL <---
  374.  
  375.                This command allows the user to send E-mail to other users.
  376.  
  377.  
  378.