home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / va210-o2.zip / SCRIPT.DOC < prev    next >
Text File  |  1997-02-05  |  63KB  |  1,797 lines
  1.         
  2.          SCRIPT
  3.          ══════
  4.  
  5.                 This document explains how to create script files and
  6.          describes the available set of script commands and functions
  7.          available when programming script for your system.  Throughout 
  8.          this document, script code fragments (examples) are preceeded 
  9.          by the characters ">>".
  10.       
  11.          SCRIPT FILES
  12.          ════════════
  13.       
  14.                 Scripts are one of the many ways in which you can modify
  15.          or customize the look, feel, and functionality of your BBS.
  16.          Script files are simple ASCII text files.  They must have a
  17.          .V filename extension, and they reside in the Script Directory,
  18.          usually C:\VADV\V, although this will differ if you installed
  19.          to a different drive and/or directory.  Script files do NOT require
  20.          compilation.
  21.  
  22.                 It is recommended that you use a plain text editor to create
  23.          and modify scripts, such as MS-DOS EDIT or similar.  If you wish
  24.          to use something fancier, such as Word for Windows, make sure
  25.          you save your script file in Text Format.  (Other word processors
  26.          may refer to this as ASCII or Plain Text format.)
  27.  
  28.                 It is also recommended that you not attempt to edit a script
  29.          which is in-use (being executed).  If needed, copy the script to
  30.          another directory and work on it there.
  31.         
  32.          BASIC SYNTAX
  33.          ════════════
  34.       
  35.                 A script file is basically just lines of text.  A line may
  36.          be blank, or contain a comment, a label, or a command with
  37.          accompanying keywords and/or arguments.  Here is an example
  38.          showing a blank line:
  39.         
  40.      >>  cls
  41.      >>
  42.      >>  ? "Hello World!"
  43.  
  44.          The "'" character at the start of a line denotes a comment.
  45.          Here is an example showing a comment:
  46.  
  47.      >>  cls
  48.      >>  'Now This is a comment
  49.      >>  ? "Hello World!"
  50.  
  51.          The ":" character denotes a label.  Note the placement of
  52.          the ":" at the END of the label.  Here is an example showing
  53.          a label:
  54.       
  55.      >>  cls
  56.      >>  gosub printmsg
  57.      >>  exit
  58.      >>
  59.      >>  printmsg:
  60.      >>  ? "Hello World!"
  61.      >>  return
  62.         
  63.          Notice that the ":" is left off when the label is actually
  64.          used in a GOTO or GOSUB command.
  65.  
  66.          SIMPLE VARIABLES
  67.          ════════════════
  68.       
  69.                 260 simple variables are available for use by your script.
  70.          Variables names are limited up to two characters; the first character
  71.          must be a character from "A" to "Z", and the second character must
  72.          be a digit from "0" to "9".  (That means you have variables
  73.          A0 to A9, B0 to B9, and so on up to Z0 to Z9.)
  74.  
  75.          Note that if you use a single-character variable name, as in:
  76.  
  77.      >>  let a = 10
  78.  
  79.          Thats the same as writing:
  80.   
  81.      >>  let a0 = 10
  82.  
  83.          GLOBAL ARRAY VARIABLE
  84.          ═════════════════════
  85.  
  86.                 You have one global array to use.  It has slots 0 to 255.
  87.          You indicate that you want to access the global array by using
  88.          the "$" character.  You may access a slot by using a number or
  89.          a variable.  This is an example using a number:
  90.       
  91.      >>  print $12
  92.      
  93.          It prints out the contents of whatever was in slot 12.  This
  94.          is an example using a simple variable:
  95.  
  96.      >>  let y1 = 10
  97.      >>  print $y1
  98.  
  99.          This is an example showing how to clear out the global array
  100.          using a DO-LOOP structure:
  101.  
  102.      >>  do i,1,100
  103.      >>   let $i = ""
  104.      >>  loop
  105.  
  106.          SPECIAL VALUES
  107.          ══════════════      
  108.                
  109.                 The "!" character indicates access to the special values,
  110.          and works similarly to the global array variable.  Here are two
  111.          examples that both do the exact same thing:
  112.       
  113.      >>  print !12
  114.   
  115.      >>  let z = 12
  116.      >>  print !z
  117.  
  118.          !12 happens to be the current channel number.
  119.       
  120.          The special values are divided into six groups based on their
  121.          function.  Those groups are a) Functionals, b) System, c) Color,
  122.          d) User Record, e) Database, and f) Caller ID.
  123.          
  124.          a) Functionals
  125.          --------------
  126.           
  127.                 Functionals take values from the simple vairables x, y, and
  128.          z, as shown below.  You must use the LET command to set the x
  129.          (and sometimes y and z) variable(s) before trying to use the
  130.          function.  While the example show here primary use the PRINT
  131.          command to illustrate usage, it is important note that you
  132.          can freely use functions in string and numeric expressions.
  133.       
  134.          0  chr(x)  -  Character Function
  135.  
  136.      >>  let x=65
  137.      >>  print !0
  138.  
  139.          The above example would print the character "A", since "A"
  140.          is the character represented by the ASCII code 65.  Valid
  141.          values for x the standard ASCII codes, 0 to 255.
  142.       
  143.          1  asc(x)  -  ASCII Code Function
  144.  
  145.      >>  let x="A"
  146.      >>  print !1
  147.  
  148.          The above example would print the number 65, since 65
  149.          is the ASCII code for the character "A".
  150.       
  151.          2  sqr(x)  -  Square Root Function
  152.  
  153.      >>  let x=4
  154.      >>  print !2
  155.       
  156.          The above example would print the result 2, since 2 is the square
  157.          root of 4.
  158.   
  159.          3  int(x)  -  Integer Function
  160.  
  161.      >>  let x=5.5
  162.      >>  print !3
  163.       
  164.          The above example would print the result 5, chopping off
  165.          the fractional part of the number.
  166.  
  167.          4  abs(x)  -  Absolute Value Function
  168.  
  169.      >>  let x=-4
  170.      >>  print !4
  171.       
  172.          The above example would print the result 4.
  173.  
  174.          5  ucase(x)  -  Upper Case Function
  175.   
  176.      >>  let x="Hello World!"
  177.      >>  print !5
  178.       
  179.          The above example would print the string "HELLO WORLD!".
  180.   
  181.          6  rnd(x)
  182.   
  183.      >>  let x=1
  184.      >>  print !6
  185.       
  186.          The above example would print a random floating-point number
  187.          from 0 to 1.  To generate a random number between 1 and some
  188.          given limit, for example 100, use some arithmetic:
  189.  
  190.      >>  let x=1                 
  191.      >>  let x=!6*100        <------ get random number, multiply by
  192.      >>  let x=!3+1          <--     100, and store result back in x.
  193.                                |
  194.                                ----- use int(x) function to truncate any
  195.                                      remaining fractional part and add 1.
  196.  
  197.          7  len(x)  -  String Length Function
  198.  
  199.      >>  let x="Hello World!"
  200.      >>  print !7
  201.  
  202.          The above example would print the result 12.
  203.       
  204.          8  instr(x,y)  -  InString Function
  205.  
  206.      >>  let x="ABCD"
  207.      >>  let y="C"
  208.      >>  print !8
  209.     
  210.          The above example would print the result 3, since the substring
  211.          "C" is in the third position of the mainstring "ABCD".  If the
  212.          substring cannot be found the result is zero.
  213.       
  214.          9  left(x,y)  -  Left String Function
  215.     
  216.      >>  let x="ROLAND DE GRAAF"
  217.      >>  let y=6
  218.      >>  print !9
  219.  
  220.          The preceeding example would print the string "ROLAND".
  221.  
  222.          10 mid(x,y,z)  -  Mid String Function
  223.  
  224.      >>  let x="ABC"
  225.      >>  let y=2              <---- set position
  226.      >>  let z=1              <---- set number of characters to retrieve
  227.      >>  print !10
  228.   
  229.          The above example would print the string "B".
  230.       
  231.          11 right(x,y)  -  Right String Function
  232.   
  233.      >>  let x="ROLAND DE GRAAF"
  234.      >>  let y=8
  235.      >>  print !11
  236.      
  237.          The preceeding example would print the string "DE GRAAF".
  238.  
  239.          27 lower(x) - Lower Case Function
  240.          
  241.      >>  let x="Hello World!"
  242.      >>  print !27
  243.       
  244.          The above example would print the string "hello world!".
  245.  
  246.          b) System
  247.          ---------
  248.       
  249.          12  Channel Number
  250.          13  Carriage Return
  251.          14  Date
  252.          15  Date/Human Format
  253.          16  Time
  254.          17  Highest NetworkID #
  255.          18  NetName(x)
  256.          19  BBS Name
  257.          20  SysOp Name
  258.          21  YN<cr>
  259.          22  Global Result Code
  260.          23  Current Video Mode, Working Stroage Value (see also #53)
  261.          24  Baud Rate (0=Local console)
  262.          25  Text Directory Path
  263.          26  Data Directory Path
  264.          28  COM Port #
  265.          29  SysOp Available  (0=No, 1=Yes)
  266.          
  267.          c) Colors
  268.          ---------
  269.       
  270.          30  Normal Color
  271.          31  Red
  272.          32  Green
  273.          33  Yellow
  274.          34  Blue
  275.          35  Magenta
  276.          36  Cyan
  277.          37  White
  278.          38  Bold
  279.          39  Base Color
  280.          40  Prompt Color
  281.          41  Input Color
  282.          42  Reserved
  283.          43  Reserved
  284.          44  Reserved
  285.          45  Reserved
  286.          46  Reserved
  287.          47  Reserved
  288.          48  Reserved
  289.          49  Reserved
  290.  
  291.          The following two examples both accomplish the same effect:
  292.  
  293.      >>  print !31, "Red", !32, "Green"
  294.  
  295.      >>  print !31 % "Red" % !32 % "Green"
  296.       
  297.          Note that "%" is the string concatenation operator.
  298.       
  299.          d) User Record
  300.          --------------
  301.           
  302.                 The user record variables let you have access to the user's
  303.          account data.  The ones marked with an asterisk "*" are also
  304.          writable.
  305.       
  306.          50  User Number
  307.          51* User Handle
  308.          52* User Name
  309.          53* User Video Mode, Long-Term Storage Value (see #23)
  310.          54* User Security Level
  311.          55* User Time Limit
  312.          56* User Access Flags
  313.          57* User Flags
  314.          58* User Credits
  315.          59* User Expiration Date
  316.          60* User Page Size
  317.          61* User Extra #1
  318.          62* User Extra #2
  319.          63* User Extra #3
  320.          64* User Extra #4
  321.          65* User Extra #5
  322.          66* User Extra #6
  323.          67* User Extra #7
  324.          68* User Extra #8
  325.          69  User Total Number of Calls
  326.          70  User Total Mins Online
  327.          71  User Time On (Current Login)
  328.          72  User Time Left (Current Login)
  329.          73  User Date Last On (YYMMDD Format)
  330.          74* User # of Files Downloaded
  331.          75* User # of Kilobytes Downloaded
  332.          76* User # of Files Uploaded
  333.          77* User # of Kilobytes Uploaded
  334.          78* User # of Emails
  335.          79* User # of Posts
  336.          80* User Address
  337.          81* User City
  338.          82* User State
  339.          83* User Zip Code
  340.          84* User Phone #1
  341.          85* User Phone #2
  342.          86  User Age
  343.          87* User Birthdate - Month
  344.          88* User Birthdate - Day
  345.          89* User Birthdate - Year
  346.  
  347.          This is an example showing how to set the security level:
  348.       
  349.      >>  let !54 = 100
  350.  
  351.          This is an example showing how to increase a user's credits by 500:
  352.  
  353.      >>  let !58 = !58 + 500
  354.       
  355.          e) Database Access
  356.          ------------------
  357.  
  358.                 The first 3 values, 90 through 92 are set by your use
  359.          of the script DBGROUP command, which selects a topic group:
  360.       
  361.          90  Current Topic Group Letter
  362.          91  Current Topic Group Description
  363.          92  Number of Databases in Group
  364.  
  365.          The values 93 through 99 are set by your use of the script
  366.          DB command, which selects a database within the current
  367.          topic group:
  368.  
  369.          93  Current Database Number
  370.          94  Current Database Description
  371.          95  Number of Entries in Database
  372.          96  Next-New-Message Read Pointer
  373.          97  Database Filename (no extension)
  374.          98  Database Attached-File Storage Path
  375.          99  Database Maximum
  376.  
  377.          The values 100 through 117 are set by your use of the script
  378.          LOAD command, which loads data one entry from the currently
  379.          selected database:
  380.  
  381.          100 Subject
  382.          101 From field, Handle or Name
  383.          102 From field, User number (0=Not Applicable)
  384.          103 From field, Network Address
  385.          104 From field, NetworkID
  386.          105 To field, Handle or Name
  387.          106 To field, User number (0=Not Applicable)
  388.          107 To field, Network Address
  389.          108 To field, NetworkID
  390.          109 Date/Time Stamp (String)
  391.          110 Count
  392.          111 Attached Filename (If Any)
  393.          112 Attached File Size (0=None)
  394.          113 Attached File/Full Path Format (If Any)
  395.          114 Offset into BIN file of text component
  396.          115 Length of BIN file text component
  397.          116 Date/Time Stamp (Numeric)
  398.          117 Flag field
  399.  
  400.          f) Caller ID    
  401.          ------------
  402.  
  403.          140 CID Name
  404.          141 CID Phone Number
  405.  
  406.          NOTE: For most modems, the command to turn on Caller ID is AT#CID=1
  407.                and you must set the BBS to answer on at least 2 rings, since
  408.                CID info is sent by the telco between ring 1 and ring 2.
  409.          
  410.          STRING LITERALS
  411.          ═══════════════
  412.  
  413.                 A string literal is just a sequence of characters, enclosed
  414.          in double quotes, such as "string literal".  Here are some examples
  415.          using string literals:
  416.  
  417.      >>  print "Hello World!"
  418.  
  419.      >>  let x="ABCD"
  420.  
  421.      >>  exit "main"
  422.  
  423.      >>  if a="Y" goto yes
  424.  
  425.          STRING EXPRESSIONS & STRING PARAMETERS
  426.          ══════════════════════════════════════
  427.  
  428.                 A STRING PARAMETER is a literal string ("hello"), a
  429.          variable possibly containing string data (x1), or a special
  430.          value (!51, for example).
  431.  
  432.                 When working with any of the script commands that
  433.          take parameters, you may use any of the three types of
  434.          STRING PARAMETER types listed in the previous paragraph.
  435.  
  436.          The following example shows how a STRING EXPRESSION
  437.          is used in the LET statement, but that a STRING PARAMETER
  438.          is used in the LOG statement:
  439.  
  440.      >>  let z = "User #" % !50 % " completed the questionnaire"
  441.      >>  log z
  442.     
  443.                 A STRING EXPRESSION is when you use the "%" character
  444.          as the "string append" operator, to combine strings together.
  445.          STRING EXPRESSIONS can only be used in LET statements.
  446.         
  447.          The following example shows how a STRING EXPRESSION
  448.          is used in the LET statement, but that a STRING PARAMETER
  449.          is used in the PRINT statement:
  450.         
  451.      >>  let a = "Your Name is " % !51
  452.      >>  print a
  453.  
  454.          In addition to the % operator, the relational operators
  455.          <, >, <=, >=, =, and <> can be used to test for string order.
  456.         
  457.          NUMERIC EXPRESSIONS
  458.          ═══════════════════
  459.         
  460.                 The following mathematical, bitwise, and relational operators
  461.          are available for use in numeric expressions:
  462.       
  463.          ^ Exponentiation
  464.          + Addition
  465.          - Subtraction
  466.          * Multiplication
  467.          / Floating-Point Division
  468.          \ Integer Division
  469.          # Modulo Arithemtic
  470.  
  471.          | Bitwise OR
  472.          & Bitwise AND
  473.  
  474.          >  Greater Than
  475.          >= Greater Than Or Equal
  476.          <  Less Than
  477.          <= Less Than or Equal
  478.          =  Equal
  479.          <> Not Equal
  480.  
  481.          Numeric expressions maybe used anywhere.  In LET statements,
  482.          and as parameters in the other script commands.
  483.         
  484.          COMMAND REFERENCE
  485.          ═════════════════
  486.         
  487.                 As you read the COMMAND REFERENCE, bear in mind that
  488.          the following commands may be used in a SCRIPT or as an
  489.          internal command in a FUNCTION BLOCK.  Commands marked with
  490.          an "!" only make sense within the context of a script, and
  491.          therefore, should only be used in scripts.  All other commands
  492.          can be used either from a script or from a function block.
  493.  
  494.        ************************************************************
  495.        *                                                          *
  496.        *                   Data Output Commands                   *
  497.        *                                                          *
  498.        ************************************************************
  499.  
  500. **** !   CLS
  501.  
  502.            Clears the screen.  This command takes no parameters.
  503.           
  504.            If the user is non-ansi, this entails having the BBS
  505.            send an ascii code 12, which is the TTY clear screen
  506.            command.  If the user is ANSI, then the sequence
  507.            <Esc>[2J is used instead.
  508.      
  509.      >>    CLS
  510.  
  511.  
  512. **** !   PRINT <param1>, <param2>, ..., <param31> [;]
  513.  
  514.            Display text, variable data, or expression results.
  515.            From zero to 32 parameters may be given.
  516.            An optional semi-colon on the end of the line inhibits the
  517.            automatic sending of a CRLF (carraige return-linefeed) sequence.
  518.            Also abbreviated as ?.
  519.  
  520.            The following example simply prints a blank line:
  521.  
  522.      >>    PRINT
  523.  
  524.            The following prints some text, and some data from a variable:
  525.     
  526.      >>    let a = "Your Name"
  527.      >>    PRINT "Hello ", a
  528.  
  529.            This one prints 1 to 10 on a single line:
  530.     
  531.      >>    do i,1,10
  532.      >>      ? i; " ";
  533.      >>    loop
  534.      >>    ?
  535.  
  536.  
  537. **** !   EF <path and file spec>
  538.  
  539.            Display a file on the screen, and to the remote caller.
  540.            The file could be a text file, an ANSI file, or whatever
  541.            is generally viewable.
  542.  
  543.  
  544. **** !   MENU <menu filename>
  545.  
  546.            Displays a menu file, in a similar manner to the way
  547.            menus files are displayed for FUNCTION BLOCKS.  The
  548.            <menu filename> is an extension-less filename of 8
  549.            characters or less, and the system will by default
  550.            look for this file in your TEXT DIRECTORY, and supply
  551.            an extension of either ASC, ANS, MNU, RIP, or VWC,
  552.            depending on file availability and user video mode selection:
  553.  
  554.            User Video Mode:                Progression:
  555.  
  556.            0 (plain text)                  .MNU -> .ASC
  557.  
  558.                .MNU files are looked for first, and if found
  559.                are displayed with the heart code color suppressed.
  560.                If no .MNU file exists, then the system tries .ASC.
  561.  
  562.            1 (ANSI)                        .MNU -> .ANS
  563.            2 (Enh ANSI)
  564.  
  565.                .MNU files are looked for first, and if found
  566.                are displayed with the heart code color.  If no .MNU
  567.                file exists, then the system tries .ANS.
  568.  
  569.            3 (RIP)                         .RIP -> .MNU -> .ANS
  570.               
  571.                .RIP files are looked for first, and if found
  572.                are displayed verbatim. If not found then
  573.                .MNU files are looked for second, and if found
  574.                are displayed with the heart code color.  If no .MNU
  575.                file exists, then the system tries .ANS.
  576.  
  577.            4 (VWC)                         .VWC -> .MNU -> .ANS
  578.               
  579.                .VWC files are looked for first, and if found
  580.                are displayed verbatim. If not found then
  581.                .MNU files are looked for second, and if found
  582.                are displayed with the heart code color.  If no .MNU
  583.                file exists, then the system tries .ANS.
  584.  
  585.  
  586. **** !   ANSIC <numeric expression>
  587.  
  588.            Transmits Ctrl-C (heart code) color.  Allowable values
  589.            are 0 to 35 for <numeric expression>.
  590.  
  591.      >>    ansic 0
  592.  
  593.      >>    ansic a
  594.     
  595.  
  596. **** !   LOC <row>, <column>
  597.  
  598.            Position the text screen cursor at the position given.
  599.            <row> and <column> are numeric expressions.
  600.  
  601.  
  602. **** !   SUSPENDPAGEBREAK
  603.  
  604.            Turn off page-break checking.
  605.  
  606.  
  607. **** !   RESUMEPAGEBREAK
  608.  
  609.            Turn page-break checking back on again.
  610.  
  611.  
  612. **** !   NEWPAGE
  613.  
  614.            Resets the internal page-break line coutner to 0.
  615.  
  616.  
  617. **** !   PAUSE <prompt string>
  618.  
  619.            Displays the pause prompt string, and waits for the caller
  620.            to press any key.  If the string parameter <prompt string>
  621.            is omitted, the default system prompt (external string #19)
  622.            is used instead.
  623.  
  624.        
  625.        ************************************************************
  626.        *                                                          *
  627.        *                 Program Control Commands                 *
  628.        *                                                          *
  629.        ************************************************************
  630.         
  631. **** !   GOTO <line label>
  632.  
  633.            Go to the line label specified, and continue execution
  634.            from there.
  635.  
  636.      >>    GOTO nextentry
  637.         
  638.         
  639. **** !   GOSUB <line label>
  640.  
  641.            Execute a subroutine.  Program control passes to the
  642.            line label specified.  A matching RETURN statement
  643.            in the subroutine returns control to the calling routine.
  644.  
  645.      >>    GOSUB docalculation
  646.  
  647.  
  648. **** !   RETURN
  649.  
  650.            Return control back to the calling routine, which executed
  651.            the GOSUB.
  652.  
  653.      >>    RETURN
  654.  
  655.         
  656. **** !   DO <var>, <start>, <end> [, <increment>]
  657.  
  658.            Form the beginning of a DO-LOOP structure.  <var> must be
  659.            a variable; <start>, <end>, and <increment> must be numeric
  660.            expressions of some sort.  Note that the <increment> field
  661.            is optional, and if omitted, defaults to 1.
  662.  
  663.      >>    DO c,1,100
  664.      >>      ? c
  665.      >>    LOOP
  666.  
  667.         
  668. **** !   LOOP
  669.  
  670.            Form the end of a DO-LOOP structure.  This command takes no
  671.            parameters.  Note that DO-LOOP structures may be nested up to
  672.            10 levels deep.
  673.  
  674. **** !   IF <string relational expression> GOTO <label>
  675.  
  676.            This command can be used to compare two string paramaters
  677.            to each other, and make a decision based on the result.
  678.            If the relationship is true, then the <label> specified
  679.            is found and program execution resumes there.  If the 
  680.            relationship is false, then execution continues normally
  681.            on the next line.
  682.  
  683. **** !   IFVAL <numeric expression> GOTO <label>
  684.  
  685.            This command is exactly like the IF command, except it
  686.            is more suited to working with numeric values.  If the
  687.            <numeric expression> evaluates to ZERO (false), then
  688.            execution continues normally on the next line.  If the
  689.            <numeric expression> evaluates to NON-ZERO (true), then
  690.            the <label> is found and execution continues there.
  691.  
  692. ****     LOGOFF
  693.          -or-
  694.          LOGOFFYN
  695.  
  696.            Proceed to the log-off sequence -- LOGOFFYN gives the
  697.            caller a chance to change their mind, LOGOFF does not.
  698.  
  699.  
  700. **** !   EXIT <function block>
  701.          -or-
  702.          END <function block>
  703.  
  704.            End the current script, and transfer control to a function
  705.            block.  <function block> is a string parameter, and should
  706.            specify an eight-character or less extension-less function
  707.            block filename.  If <function block> is omitted, the most
  708.            recent function block is referenced.  (This reference
  709.            is cleared by execution of the LINK command, so therefore
  710.            it is recommended that you use the full form everytime.)
  711.  
  712.            NOTE: DO NOT use EXIT or END in cases where the script
  713.                  is being CALLed from another script, unless ending
  714.                  script execution altogether is your desired effect.
  715.  
  716. **** !   LINK <script name>
  717.  
  718.            End the current script, and transfer control to another script. 
  719.            <script name> is a string parameter, and should an eight
  720.            character or less filename, without an extension.
  721.  
  722. **** !   CALL <script name>
  723.  
  724.            Saves the execution position of the current script, and loads
  725.            and executes another script.  When the CALLed script runs out
  726.            of lines to execute, control returns to the old script at the
  727.            position where the interpreter left off.
  728.  
  729.            NOTE: Script invoked by external string (ie. DEFAULT.S) are
  730.            always automatically executed as though they were CALLed,
  731.            so as not to disturb any script which may be running at the time.
  732.  
  733.            CALLs may be nested up to 20 levels deep, and recursion
  734.            is allowed -- BUT BE VERY CAREFUL WITH THIS COMMAND IF YOU
  735.            ATTEMPT THIS.
  736.  
  737.            NOTE: The "CALL stack" is LOST if VA for DOS must "shrink out"
  738.                  to run a door, or if the script DOOR command is used.
  739.  
  740. **** !   SHELL <DOS or OS2 command line>
  741.  
  742.            Executes, by way of the resident operating system,
  743.            the DOS or OS2 command line given, as a string
  744.            parameter.
  745.  
  746.      >>    shell "dir /p"
  747.  
  748.      >>    let f = "ADVAUX " % !12 % " TELECON"
  749.      >>    shell f
  750.  
  751.  
  752. **** !   DOOR <DOS or OS2 command line>
  753.  
  754.            Execute a door program, batch file or other application.
  755.            <DOS or OS2 command line> is a string parameter.
  756.            DOOR differs from shell in that:
  757.  
  758.            1) Dropfiles (CHAIN.TXT, DOOR.SYS, DORINFO1.DEF) Created
  759.            2) Virtual Advanced for DOS "shrinks out" of memory
  760.               to open up maximum space for the application
  761.            3) If the <DOS or OS2 command line> is omitted or null,
  762.               then the built-in door selection menu is presented.
  763.  
  764.            The DOOR command is usually preceeded by either a RETURNSCRIPT
  765.            or RETURNFB block command.  Since the DOS version of Virtual
  766.            Advanced "shrinks out," continuation of the script past
  767.            the DOOR command is not possible.  But execution of the
  768.            script under Virtual Advanced for OS2 does continue.
  769.            So, how to handle the difference?
  770.  
  771.            When your desired destination is an FB:
  772.  
  773.      >>    returnfb "myfb"
  774.      >>    door "doorgame.bat %1"
  775.      >>    exit "myfb"
  776.  
  777.            When your desired destination is a script:
  778.  
  779.      >>    returnscript "myscript"
  780.      >>    door "doorgame.bat %1"
  781.      >>    link "myscript"
  782.  
  783.            In either of the above situations, whether DOS or OS2,
  784.            the result is the same.
  785.  
  786.  
  787. **** !   RETURNFB <function block name>
  788.          -or-
  789.          RETURNSCRIPT <script>
  790.       
  791.            RETURNFB/RETURNSCRIPT control how the DOOR command behaves.
  792.            They allow your script to specify the action to be taken
  793.            after the DOOR command returns.  In the case of RETURNFB,
  794.            it allows you to specify a function block as the destination
  795.            after the door call is complete.  In the case of RETURNSCRIPT,
  796.            it allows you to specify a script as the destination after
  797.            a door call completes.  (Often, RETURNSCRIPT is used to
  798.            return control to the script that called it.)
  799.  
  800.  
  801.        ************************************************************
  802.        *                                                          *
  803.        *                   Data Input Commands                    *
  804.        *                                                          *
  805.        ************************************************************
  806.  
  807. **** !   INPUT [<prompt1>, <prompt2>, ..., <prompt30>,] <var>
  808.          -or-
  809.          LINEINPUT [<prompt1>, <prompt2>, ..., <prompt30>,] <var>
  810.  
  811.            Input data from a user into variables.  Up to 30
  812.            optional parameters may be specified to form the
  813.            optional prompt for the input.  Note that the user
  814.            must hit ENTER for the input to be accepted by the
  815.            program.
  816.  
  817.        
  818. **** !   RH <var>
  819.  
  820.            Scan the input queue for keystrokes (local or remote),
  821.            and return the next keystroke in <var>, if one is available.
  822.            If no data is available, <var> comes back as empty ("").
  823.            Does not wait for ENTER.  Does not wait for input to
  824.            become available.
  825.  
  826.        
  827. **** !   RW <var>, <prompt>
  828.  
  829.            Display optional <prompt>, and input data from the user.
  830.            Data format is 80 cols per line, with automatic WORD-WRAP.
  831.      
  832.        
  833. **** !   RS <var>, <prompt>
  834.  
  835.            Display optional <prompt>, and input data from the user.
  836.            Data format is 80 cols per line, max.
  837.      
  838.         
  839. **** !   RF <var>, <prompt>
  840.  
  841.            Display optional <prompt>, and input data from the user.
  842.            Data format is limited to conventional 8.3 filename
  843.            syntax, and wildcards are not allowed.
  844.  
  845.         
  846. **** !   RI <var>, <prompt>
  847.  
  848.            Display optional <prompt>, and input data from the user.
  849.            Data format is limited to conventional 8.3 filename
  850.            syntax, and wildcards are allowed.
  851.  
  852.         
  853. **** !   RN <var>, <prompt>
  854.           
  855.            Display optional <prompt>, and input data from the user.
  856.            Data format is limited to numeric digits, and a maximum value
  857.            of 999999999.
  858.  
  859.         
  860. **** !   RX <var>, <prompt>
  861.           
  862.            Display optional <prompt>, and input data from the user.
  863.            Data format is limited to 8 characters maximum, and "X"
  864.            characters are echoed back to the caller instead of
  865.            the actual character typed.  This is useful for passwords.
  866.  
  867.  
  868. **** !   RC <var>, <prompt>
  869.           
  870.            Display optional <prompt>, and wait for one keystroke
  871.            to be returned in <var>.  This differs from RH in that
  872.            RH does not wait for a keystroke and will return empty
  873.            if necessary.
  874.         
  875.         
  876. **** !   RR <var>, <allowed keys>, <prompt>
  877.           
  878.            Display optional <prompt>, and wait for one keystroke
  879.            to be returned in <var>.  Keystrokes are limited to
  880.            the ones allowed in <allowed keys>.
  881.  
  882.         
  883. **** !   RL <var>, <allowed keys>, <max numeric>, <prompt>
  884.  
  885.            Display optional <prompt>, and wait for user input to
  886.            be returned in <var>.  Allowed input are the single
  887.            characters as specified by <allowed keys>, and the numbers
  888.            1 to <max numeric>.  This is a multi-purpose input command.
  889.  
  890.            You might use RL when allowing a user to access a list of
  891.            choices, say for example, text files to look at:
  892.           
  893.      >>    displist:
  894.      >>    cls
  895.      >>    do i,1,10
  896.      >>      ? i,". Text File #",i
  897.      >>    loop
  898.      >>    ?
  899.      >>    rl k1, "?Q", 10, "Your Choice: "
  900.      >>    if k1="?" goto displist
  901.      >>    if k1="Q" goto quit
  902.      >>    let f="c:\text\text" % k1 % ".TXT"
  903.      >>    ef f
  904.      >>    pause
  905.      >>    goto displist
  906.      >>    quit:
  907.      >>    exit
  908.  
  909.  
  910. **** !   GETYN <var>, <prompt>
  911.  
  912.            Display optional <prompt>, and wait for one character
  913.            (keystroke) from the user.  Input characters allowed is limited
  914.            to Y, N, and ENTER.  In the case of GETYN, pressing ENTER
  915.            defaults to Y.
  916.  
  917.         
  918. **** !   GETNY <var>, <prompt>
  919.  
  920.            Display optional <prompt>, and wait for one character
  921.            (keystroke) from the user.  Input characters allowed is limited
  922.            to Y, N, and ENTER.  In the case of GETNY, pressing ENTER
  923.            defaults to N.
  924.  
  925.        
  926.        ************************************************************
  927.        *                                                          *
  928.        *                     String Commands                      *
  929.        *                                                          *
  930.        ************************************************************
  931.  
  932. **** !   JR <var>, <width>
  933.  
  934.            Justify the text or numeric contents of a variable <var>
  935.            to the RIGHT, using the <width> specified.
  936.         
  937.         
  938. **** !   JL <var>, <width>
  939.           
  940.            Justify the text or numeric contents of a variable <var>
  941.            to the LEFT, using the <width> specified.
  942.  
  943.  
  944. **** !   JC <var>, <width>
  945.  
  946.            Justify the text or numeric contents of a variable <var>
  947.            to the CENTER, using the <width> specified.
  948.  
  949.  
  950. **** !   LEFT <var>, <string parameter>, <number of chars>
  951.  
  952.            Take the leftmost <number of chars> from <string parameter>
  953.            and put them into <var>.  This is an alternative to the !9
  954.            function.
  955.  
  956.  
  957. **** !   MID <var>, <string parameter>, <position>
  958.          -or-
  959.          MID <var>, <string parameter>, <position>, <number of chars>
  960.  
  961.            Take <number of chars> from <string parameter>, starting
  962.            at <position>, and put them into <var>.  If <number of chars>
  963.            is omitted, then the rest of the string is taken.  This is an
  964.            alternative to the !10 function.
  965.  
  966.  
  967. **** !   RIGHT <var>, <string parameter>, <number of chars>
  968.            
  969.            Take the rightmost <number of chars> from <string parameter>
  970.            and put them into <var>.  This is an alternative to the
  971.            !11 function.
  972.  
  973.            
  974.        ************************************************************
  975.        *                                                          *
  976.        *                 General File I/O Commands                *
  977.        *                                                          *
  978.        ************************************************************
  979.  
  980. **** !   FINDFIRST <path and file spec>, <var>
  981.  
  982.            Start a directory search for a particular path and file
  983.            specification - may contain wildcards.  Results returned
  984.            in <var>.  <var> returns empty ("") when there are no
  985.            files matching the the filemask.
  986.  
  987.        
  988. **** !   FINDNEXT <var>
  989.  
  990.            Find next filename in a directory search.  This command must
  991.            be used in conjunction with the FINDFIRST command.
  992.  
  993.  
  994. **** !   XFERTIME <var>, <filesize>
  995.  
  996.            Calculates the estimated download transfer time and
  997.            returns this value in <var>, given the <filesize>.
  998.            The time value returned is expressed in minutes.
  999.           
  1000.  
  1001. **** !   CHECKFILE <var>, <path and file spec>
  1002.  
  1003.            Performs a file check for a particular path and file
  1004.            specification - may NOT contain wildcards.  Results returned
  1005.            in <var>:
  1006.  
  1007.              <var> = -1    Path given does not exist
  1008.  
  1009.              <var> = 0     Path is OK, but file does not exist
  1010.  
  1011.              <var> > 0     Path and File are OK, and <var> indicates
  1012.                            file size
  1013.  
  1014.  
  1015. **** !   DOWNLOAD <path and file spec>
  1016.  
  1017.                This command is useful for sending a file to the caller.
  1018.                The user is prompted to choose a transfer protocol, and the
  1019.                file specified is sent.  <path and file spec> is a string
  1020.                parameter.
  1021.  
  1022.  
  1023. **** !   UPLOAD <path and file spec>
  1024.               
  1025.                This command is useful for receiving a file from a caller.
  1026.                The user is prompted to choose a transfer protocol, and the
  1027.                file specified is received.  If a path is specified with the
  1028.                filename, then the file is received into that directory. 
  1029.                <path and file spec> is a string parameter.
  1030.  
  1031.  
  1032. **** !   KILL <path and file spec>
  1033.  
  1034.            Delete a file.  <path and file spec> is a string
  1035.            parameter, and wildcards are not allowed.
  1036.  
  1037.  
  1038. **** !   OPEN <path and filename>, <file mode>
  1039.  
  1040.            Open up an ASCII file for manipulation with the READ and
  1041.            WRITE script commands.  Both parameters are string
  1042.            parameters, with <file mode> being either "A"
  1043.            for append, "O" for output, and "I" for input.
  1044.  
  1045.            If a file is already open with the OPEN command when
  1046.            your script tries to execute this command, the message
  1047.            "File already OPEN." will appear in your BBS.LOG, and
  1048.            the operation will fail.
  1049.  
  1050.            If you try to open a non-existant file for input,
  1051.            the message "File or Path OPEN/INPUT does not exist."
  1052.            will appear in your BBS.LOG.
  1053.  
  1054.  
  1055. **** !   CLOSE
  1056.  
  1057.            Close the file currently opened with the OPEN command.
  1058.            This command takes no parameters.
  1059.           
  1060.  
  1061. **** !   WRITE <data to be written>
  1062.  
  1063.            Writes data (string parameter) to the currently OPEN
  1064.            file.  File must be open for either input or append
  1065.            modes. 
  1066.           
  1067.            If the file is not open when this command is encountered,
  1068.            the message "File not OPEN." will appear in BBS.LOG.  If
  1069.            the file is OPEN, but for the wrong file mode, then the
  1070.            message "Bad File Mode." will appear in the system log.
  1071.           
  1072.  
  1073. **** !   READ <var>
  1074.  
  1075.            Reads the next line of data in the currently OPEN file
  1076.            to a variable, <var>.  If there is no more data available,
  1077.            then the string "!EOF!" is returned in <var>.
  1078.           
  1079.            If the file is not open when this command is encountered,
  1080.            the message "File not OPEN." will appear in BBS.LOG.  If
  1081.            the file is OPEN, but for the wrong file mode, then the
  1082.            message "Bad File Mode." will appear in the system log.
  1083.  
  1084.        
  1085.        ************************************************************
  1086.        *                                                          *
  1087.        *                Miscellaneous Commands                    *
  1088.        *                                                          *
  1089.        ************************************************************
  1090.  
  1091. **** !   CLEAR
  1092.  
  1093.            Clears all variables, and all slots in the global array.
  1094.            
  1095.  
  1096. **** !   RANDOM
  1097.  
  1098.            Displays a random message from the configuration file
  1099.            RANDOM.CFG.  RANDOM.CFG is modifiable through VCONFIG.
  1100.  
  1101.  
  1102. **** !   LOG <string parameter>
  1103.  
  1104.            Writes the string parameter to the log:
  1105.  
  1106.      >>    log "Hello There"
  1107.  
  1108.      >>    let x = "User Number " % !50
  1109.      >>    log x
  1110.  
  1111.  
  1112. **** !   ACTION <description>
  1113.  
  1114.            Modifies what is seen by the WHO command in terms of
  1115.            the action that the user is doing.  <description>
  1116.            is a string parameter.
  1117.  
  1118.  
  1119. **** !   DELAY <seconds>
  1120.  
  1121.            Delay for certain time period.  <seconds> is a numeric
  1122.            expression.
  1123.  
  1124.  
  1125. **** !   BEEP
  1126.             
  1127.            Causes a BEEP to be sounded locally on the SysOp's computer.
  1128.  
  1129.  
  1130. ****     PAGESYSOP
  1131.  
  1132.            This pages the sysop for chat, if the sysop is available.
  1133.  
  1134.  
  1135. **** !   ADDTIME <minutes to add>
  1136.  
  1137.            Temporarily grant additional time to a user during this
  1138.            call.  <minutes to add> is a numeric expression.
  1139.  
  1140.  
  1141. **** !   SETFLAGS <flag>, <on/off>
  1142.  
  1143.            Manipulate the 26 user flags (*not* the database access
  1144.            flags, which are a separate set of flags). <flag> is string
  1145.            parameter from "A" to "Z" and <on/off> is a string parameter
  1146.            of either "ON" or "OFF".  These flags go largely unused by
  1147.            the system and are therefore available for custom uses.
  1148.            The flags in use by the system are:
  1149.  
  1150.            F - Full Screen Editor
  1151.            X - Expert Mode (Menus Skipped)
  1152.            N - User Has Been Sent New-User Email
  1153.            I - Enable Internet Pass-Thru Access
  1154.            U - Enable UUCP Access
  1155.  
  1156.  
  1157. ****     STACK <keystrokes to fake>
  1158.  
  1159.            Stack fakes keysrokes to the Virtual Advanced program.
  1160.            <keystrokes to fake> is a string parameter.
  1161.  
  1162.  
  1163. ****     SYSINFO
  1164.  
  1165.            Displays the system current stats information screen.
  1166.  
  1167.  
  1168. ****     WHO
  1169.  
  1170.            Displays who is online, and what they are doing.
  1171.  
  1172.  
  1173. ****     VALIDATE
  1174.  
  1175.            Allows the sysop or co-sysop to validate outgoing
  1176.            network posts that are pending validation.
  1177.  
  1178.  
  1179. ****     ONELINERS
  1180.  
  1181.            Displays the "one-line" messages awaiting the user (ie
  1182.            "Joe Public read your email...."), and then checks for 
  1183.            waiting email.
  1184.  
  1185.  
  1186. ****     AUTOPOST
  1187.  
  1188.            Displays the autoposts, and allows the caller to add
  1189.            a message of their own, if they have the sufficient security
  1190.            level as defined under VCONFIG Main Configuration.
  1191.  
  1192.  
  1193. ****     LISTCALLERS <number of callers>
  1194.  
  1195.            Displays on the screen the last <number of callers>
  1196.            who have called and logged into the system.  If numeric
  1197.            expression <number of callers> is equal to zero, then all
  1198.            of the current day's calls are listed.
  1199.  
  1200.  
  1201. ****     ACCOUNT
  1202.  
  1203.            Allows the caller to access the built-in account defaults
  1204.            modification routine, so that they may change some of their
  1205.            user account options, such as password, colors, etc.
  1206.  
  1207.  
  1208. ****  S  EDITFILE
  1209.  
  1210.            A convenience command to allow the sysop to edit small
  1211.            ASCII files (or ASCII files with heart-code) using the
  1212.            built-in editor.  This command should be restricted to 
  1213.            SYSOP USE ONLY.
  1214.  
  1215.  
  1216. ****  S  USEREDIT
  1217.  
  1218.            A convenience command to allow the sysop to access the
  1219.            user editor locally or remotely, through the BBS.
  1220.            This command should be restricted to SYSOP USE ONLY.
  1221.  
  1222.  
  1223. ****  S  LOCALWFC
  1224.  
  1225.            Displays the Local WFC Screen that the sysop can
  1226.            call upon when logged into channel 0.
  1227.  
  1228.        ************************************************************
  1229.        *                                                          *
  1230.        *             Database Manipulation Commands               *
  1231.        *                                                          *
  1232.        ************************************************************
  1233.  
  1234. **** !   DBGROUP <database group id>
  1235.  
  1236.            Sets the current database group, to the database group
  1237.            identifier in string parameter <database group id>.
  1238.  
  1239.            Executing the DBGROUP command sets special values
  1240.            !90 to !92.
  1241.  
  1242.            NOTE: DBGROUP should be executed before DB.
  1243.           
  1244.  
  1245. **** !   DB <database #>
  1246.  
  1247.            Selects a database from the currently selected DBGROUP.
  1248.            <database #> should be a numeric expression from 1 to !92.
  1249.  
  1250.            Executing the DB command sets special values !93 to !99.
  1251.            From there, you can determine which record number
  1252.            to be used with subsequent LOAD or SEARCH commands.
  1253.  
  1254.  
  1255. **** !   SETEMAIL
  1256.  
  1257.            SETEMAIL should be used, instead of the DBGROUP/DB command
  1258.            combination, when you want to use the database commands
  1259.            to manipulate/access the EMAIL database.
  1260.  
  1261.  
  1262. **** !   LOAD <record number>[, "/Q"]
  1263.  
  1264.            Loads the database <record number> given into the current
  1265.            special var workspace.  If the /Q option is included,
  1266.            the "new scan pointer" is not updated.
  1267.  
  1268.            <record number> should be between 1 and !95.
  1269.  
  1270.            NOTE: The LOAD command should not be issued until
  1271.            DBGROUP and DB commands have been issued, selecting
  1272.            a database to work with.
  1273.  
  1274.            !22 can be examined to determine the outcome of the
  1275.            LOAD command:
  1276.  
  1277.            "OK"   Record was successfully loaded
  1278.  
  1279.            "PRI"  Record was private and could not be loaded
  1280.  
  1281.            "DEL"  Record was deleted and could not be loaded
  1282.  
  1283.            NOTE: The LOAD command should not be issued until
  1284.            DBGROUP and DB commands have been issued, selecting
  1285.            a database to work with.
  1286.  
  1287.  
  1288. **** !   SEARCH <record number to start>, <search type>, <search string>
  1289.  
  1290.            Searches the currently selected database, starting
  1291.            at the record number specified, using the <search type>
  1292.            and <search string> given:
  1293.  
  1294.            <search type>                        <search string>
  1295.           
  1296.            1  Messages To User                  N/A
  1297.            2  Message From User                 N/A
  1298.            3  Subject Field                     Yes
  1299.            4  Filename FileMask                 Yes
  1300.            5  Filename Match                    Yes
  1301.  
  1302.            !22 can be examined to determine the outcome of the
  1303.            LOAD command:
  1304.  
  1305.            "OUT"        Data was not found
  1306.  
  1307.            "<number>"   Data Found !22 = Record Number
  1308.           
  1309.            NOTE: The SEARCH command should not be issued until
  1310.            DBGROUP and DB commands have been issued, selecting
  1311.            a database to work with.
  1312.  
  1313.  
  1314. **** !   DISPLAYMSG
  1315.  
  1316.            Optionally used after a LOAD or SEARCH command to display
  1317.            the message header information on the screen.
  1318.           
  1319.            NOTE: The DISPLAYMSG command should not be issued until
  1320.            DBGROUP and DB commands have been issued, selecting
  1321.            a database to work with, AND either a LOAD or SEARCH command
  1322.            to load a data record.
  1323.           
  1324.  
  1325. **** !   DISPLAYTEXT <record number>
  1326.  
  1327.            Display the text message associated with the database
  1328.            <record number> given.
  1329.  
  1330.            <record number> should be between 1 and !95.
  1331.  
  1332.            NOTE: The DISPLAYTEXT command should not be issued until
  1333.            DBGROUP and DB commands have been issued, selecting
  1334.            a database to work with.
  1335.  
  1336.  
  1337. **** !   QS <new new-scan pointer>
  1338.  
  1339.            Alters the users "new-scan pointer" (ie. !96) for the
  1340.            currently selected database.  <new new-scan pointer> is
  1341.            a numeric expression.
  1342.           
  1343.            NOTE: The QS command should not be issued until
  1344.            DBGROUP and DB commands have been issued, selecting
  1345.            a database to work with.
  1346.  
  1347.  
  1348. **** !   DEL <record number>
  1349.  
  1350.            Mark a record for deletion in the current database. 
  1351.            <record number> is a numeric expression.
  1352.  
  1353.            NOTE: The DEL command should not be issued until
  1354.            DBGROUP and DB commands have been issued, selecting
  1355.            a database to work with.
  1356.  
  1357.  
  1358. **** !   DBFLAG <record number>, <on/off>
  1359.  
  1360.            Sets or resets the database flag bit for the entry at
  1361.            the record given in numeric expression <record number>.
  1362.  
  1363.            NOTE: The DBFLAG command should not be issued until
  1364.            DBGROUP and DB commands have been issued, selecting
  1365.            a database to work with.
  1366.  
  1367.  
  1368. **** !   ADDCOUNT <record number>
  1369.  
  1370.            Adds 1 to the access counter for the database entry at
  1371.            the record number given in numeric expression <record number>.
  1372.           
  1373.            NOTE: The ADDCOUNT command should not be issued until
  1374.            DBGROUP and DB commands have been issued, selecting
  1375.            a database to work with.
  1376.  
  1377.  
  1378. **** !   SAVE <handle>, <user #>, <node address>, <network #>, <subject>,
  1379.               <attached file size>, <attached filename>
  1380.  
  1381.            Save a new record to the currently selected database.  <handle>,
  1382.            <node address>, <subject>, and <attached filename> are string
  1383.            parameters; <user #>, <network #>, and <attached file size>
  1384.            are numeric expressions.
  1385.  
  1386.            If saving a record to a NETWORK # that doesn't use user #'s
  1387.            such as the Internet or FIDOnet, then <user #> should be set
  1388.            to zero.
  1389.  
  1390.            If there is no file to be attached, then <attached file size>
  1391.            should be set to zero, and <attached filename> should be set
  1392.            to empty ("").
  1393.           
  1394.            NOTE: The SAVE command should not be issued until
  1395.            DBGROUP and DB commands have been issued, selecting
  1396.            a database to work with.
  1397.  
  1398.  
  1399. **** !   BUFFER CLEAR
  1400.  
  1401.            Clears the current text buffer workspace.  This workspace
  1402.            is saved as the message text with the SAVE command described
  1403.            above.
  1404.  
  1405.  
  1406. **** !   BUFFER EDIT
  1407.  
  1408.            Use the line editor to edit the buffer worksapce.
  1409.  
  1410.  
  1411. **** !   BUFFER LIST
  1412.  
  1413.            Display the current contents of the worksapce buffer.
  1414.  
  1415.  
  1416. **** !   BUFFER APPEND, <data string>
  1417.  
  1418.            Appends the string parameter <data string> onto
  1419.            the current work space buffer.
  1420.  
  1421.  
  1422.        ************************************************************
  1423.        *                                                          *
  1424.        *        Email-Related Commands (Usually Used in FBs)      *
  1425.        *                                                          *
  1426.        ************************************************************
  1427.  
  1428. ****     SENDEMAIL
  1429.  
  1430.            This calls upon a complete routine which handles the task
  1431.            of allowing a user to send local or networked electronic
  1432.            mail.  This command is called from the default EMAIL.FB.
  1433.  
  1434.  
  1435. ****     FEEDBACK
  1436.  
  1437.            This calls upon a complete routine which handles the task
  1438.            of allowing a user to send feedback to the sysop or any
  1439.            address in your multi-feedback list, as configured in VCONFIG.
  1440.            This command is called from the default EMAIL.FB.
  1441.  
  1442.  
  1443. ****     READEMAILTO
  1444.  
  1445.            This calls upon a complete routine which handles the task
  1446.            of allowing a user to read mail that is addressed TO them.
  1447.            This command is called from the default EMAIL.FB.
  1448.  
  1449.            The user is given the option of reading mail based on:
  1450.  
  1451.            (A)ll       All Email Messages To User
  1452.            (N)ew       All New Email Messages To User
  1453.            (S)earch    Search the From: and Subject: Fields
  1454.            (E)xt Srch  Extended Search Includes Message Text
  1455.            (L)ocal     Email Written Locally
  1456.           
  1457.  
  1458. ****     READEMAILFROM
  1459.  
  1460.            This calls upon a complete routine which handles the task
  1461.            of allowing a user to read mail that is addressed FROM them.
  1462.            This command is called from the default EMAIL.FB.
  1463.  
  1464.            The user is given the option of reading mail based on:
  1465.  
  1466.            (A)ll       All Email Messages From User
  1467.            (N)ew       All New Email Messages From User
  1468.            (S)earch    Search the To: and Subject: Fields
  1469.            (E)xt Srch  Extended Search Includes Message Text
  1470.            (L)ocal     Email Written Locally
  1471.          
  1472.  
  1473. ****     QUICKMAIL
  1474.  
  1475.            This accesses the complete routine which handles the
  1476.            automatic sending of email using multiple mailing lists.
  1477.            This command is called from the default EMAIL.FB.
  1478.  
  1479.  
  1480. ****  S  READALLEMAIL
  1481.  
  1482.            This command should be executed by the SYSOP ONLY.
  1483.            This command is called from the default SYSOP.FB.
  1484.            It allows the sysop access to the entire email database.
  1485.          
  1486.  
  1487.        ************************************************************
  1488.        *                                                          *
  1489.        *         File-Related Commands (Usually Used in FBs)      *
  1490.        *                                                          *
  1491.        ************************************************************
  1492.  
  1493. ****     LISTFILES
  1494.  
  1495.            This command executes a complete routine which takes
  1496.            a filename or filemask (wildcards allowed) from the user
  1497.            and lists all matching entries in the current file base.
  1498.            This command is called from the default FILE.FB.
  1499.  
  1500.  
  1501. ****     SEARCHALL
  1502.            
  1503.            Like LISTFILES, this command executes a complete routine which 
  1504.            takes a filename or filemask (wildcards allowed) from the user 
  1505.            and lists all matching entries for all file area databases within 
  1506.            the current TOPIC GROUP or all file area databases on the BBS.  
  1507.            This command is called from the default FILE.FB.
  1508.  
  1509.  
  1510. ****     NEWFILES
  1511.            
  1512.            This command executes a complete routine which lists all new
  1513.            entries for all file area databases within the current TOPIC GROUP 
  1514.            or all file area databases on the BBS.  This command is called 
  1515.            from the default FILE.FB.
  1516.  
  1517.  
  1518. ****     FINDFILES
  1519.  
  1520.            This command executes a complete routine which takes a text 
  1521.            string input from the user and lists all matching entries for 
  1522.            all file area databases within the current TOPIC GROUP or all 
  1523.            file area databases on the BBS.  Entries are matched based on
  1524.            the description.  This command is called from the default FILE.FB.
  1525.  
  1526.  
  1527. ****     DOWNLOADFILE
  1528.            
  1529.            This command executes a complete routine which takes a filename 
  1530.            from the user and automatically tags these entries for
  1531.            download.  All file area databases are searched for the matching
  1532.            file entry, starting with the current database.  This command 
  1533.            is called from the default FILE.FB.
  1534.  
  1535.  
  1536. ****     REMOTEUPLOAD
  1537.  
  1538.            This command executes a complete routine which allows the
  1539.            caller to upload one or more files.  The caller has the option 
  1540.            of entering descriptions before or after the upload.  In 
  1541.            addition, after the upload the routine will automatically 
  1542.            try to detect the FILE_ID.DIZ from any ARCS.CFG supported 
  1543.            archive type, and use that information for the description,
  1544.            if possible.  This command is called from the default FILE.FB.
  1545.  
  1546.  
  1547. ****     TOPDOWNLOADS
  1548.  
  1549.            This convenience command lists the top 50 downloads in
  1550.            the current TOPIC GROUP.  This command is called from 
  1551.            the default FILE.FB.
  1552.  
  1553.  
  1554. ****     REVIEWFILE
  1555.  
  1556.            This convenience command allows users to review files
  1557.            sequentially (from the current file area database).
  1558.            This command is called from the default FILE.FB.
  1559.  
  1560.  
  1561. ****     RATIO
  1562.  
  1563.            This convenience command simply display the caller's
  1564.            upload/download ratio.  This command is called from the 
  1565.            default FILE.FB.
  1566.  
  1567.  
  1568. ****     DLMASTERLIST
  1569.  
  1570.            This convenience command allows the user to download a 
  1571.            custom-generated masterlist of files.  This command is 
  1572.            called from the default FILE.FB.
  1573.  
  1574.  
  1575. ****     SETNEWFILESSCAN
  1576.  
  1577.            This command lets the user sets the "days back" pointer
  1578.            for their new file listings.  This command is called from 
  1579.            the default FILE.FB.
  1580.  
  1581.  
  1582. ****  S  SYSOPUPLOAD
  1583.  
  1584.            This command executes a complete routine which allows the
  1585.            sysop to "upload" one or more files; that is, enter
  1586.            the descriptions necessary to put files online and make
  1587.            them available for download by callers.  The routine will 
  1588.            automatically try to detect the FILE_ID.DIZ from any ARCS.CFG 
  1589.            supported archive type, and use that information for the 
  1590.            description, if possible, saving the sysop lots of time and 
  1591.            typing.  This command is called from the default FILE.FB.
  1592.  
  1593.  
  1594. ****  S  REVIEWUPLOADS
  1595.  
  1596.            If you have VCONFIG Main Option "Secure Uploads" set to "Yes"
  1597.            then this command lets the sysop review the new files that have
  1598.            been uploaded by users, before the file is accessible to
  1599.            all users of the BBS.  From this routine, the sysop can easily
  1600.            move the file (and description) to the desired destination 
  1601.            directory.
  1602.  
  1603.       
  1604.        ************************************************************
  1605.        *                                                          *
  1606.        *      Message-Related Commands (Usually Used in FBs)      *
  1607.        *                                                          *
  1608.        ************************************************************
  1609.  
  1610. ****     SETQUICKSCAN
  1611.  
  1612.            Accesses a complete routine that allows the caller to
  1613.            manipulate their new-scan pointers for the public message
  1614.            bases.  User can choose to ignore message areas entirely.
  1615.            This command is called from the default MESSAGE.FB.
  1616.  
  1617.  
  1618. ****     READSEQMSG
  1619.  
  1620.            Accesses a complete routine that will allow the user to
  1621.            read messages sequentially, with an optional searching
  1622.            capability, from the currently selected message base.
  1623.            This command is called from the default MESSAGE.FB.
  1624.  
  1625.  
  1626. ****     READNEWMSG
  1627.  
  1628.            Read all new messages in all databases selected (as per
  1629.            SETQUICKSCAN).  This command is called from the default
  1630.            MESSAGE.FB.
  1631.  
  1632.  
  1633. ****     READNEWPERSONALMSG
  1634.  
  1635.            Read only new messages in all databases selected (as per
  1636.            SETQUICKSCAN), which are addressed TO: the user.  This command
  1637.            is called from the default MESSAGE.FB.
  1638.  
  1639.  
  1640. ****     SCANMSG
  1641.  
  1642.            Scan the current message base 10 messages at a time,
  1643.            and allows user to switch into read mode at any time.
  1644.            During a message base scan, the Title, From, and To
  1645.            fields of a message are displayed.  This command is
  1646.            called from the default MESSAGE.FB.
  1647.  
  1648.  
  1649. ****     POST
  1650.  
  1651.            Execute a complete routine which allows the user to post
  1652.            on the current message base.  This command is called from
  1653.            the default MESSAGE.FB.
  1654.  
  1655.       
  1656.        ************************************************************
  1657.        *                                                          *
  1658.        * Database Selection Commands (Used in MESSAGE.FB/FILE.FB) *
  1659.        *                                                          *
  1660.        ************************************************************
  1661.  
  1662. ****     LISTBASES
  1663.  
  1664.            This command lists all of the databases available in the
  1665.            current TOPIC GROUP.
  1666.  
  1667.  
  1668. ****     SELECTBASE
  1669.  
  1670.            This command lists all of the databases available in the
  1671.            current TOPIC GROUP, and allows the user to choose a new
  1672.            database for the current database.
  1673.  
  1674.  
  1675. ****     CHOOSETOPIC
  1676.  
  1677.            This command lists all of the available topic groups,
  1678.            and allows the user to select a new TOPIC GROUP for
  1679.            the current topic group.
  1680.  
  1681.  
  1682. ****     PREVBASE
  1683.  
  1684.            The PREVBASE command moves to the previous database within the
  1685.            current TOPIC GROUP.
  1686.  
  1687.  
  1688. ****     NEXTBASE
  1689.           
  1690.            The NEXTBASE command moves to the next database within the
  1691.            current TOPIC GROUP.
  1692.  
  1693.  
  1694.          HOW TO LAUNCH A SCRIPT
  1695.          ══════════════════════
  1696.  
  1697.                 START.V is executed automatically when a user logs
  1698.          into your BBS.  To get other scripts to execute, one of three
  1699.          methods can be employed:
  1700.  
  1701.          1) From a Function Block
  1702.  
  1703.             The first two lines of each function block file specify
  1704.             the menu used (line 1) and the database TOPIC GROUPs
  1705.             enabled, if any, (line 2) for this menu.  Lines 3 onward
  1706.             are used to define commands, and this is how to define a 
  1707.             command (/SCRIPT) which runs a script (SCRIPT.V):
  1708.             
  1709.             /SCRIPT1 001 2 script1
  1710.             
  1711.          2) From START.V or other Script
  1712.  
  1713.             To end execution of the current script, and transfer control 
  1714.             to another script, use the LINK command, referenced elsewhere 
  1715.             in this document.
  1716.             
  1717.  
  1718.          3) From the DEFAULT.S String File
  1719.  
  1720.             You can embed references to Script files in most of 
  1721.             the external strings in the DEFAULT.S string file.
  1722.             Strings which cannot be replaced are:
  1723.             #19, 422, 423, 424, 425
  1724.  
  1725.             How to execute script file SCRIPT2.V:
  1726.  
  1727.             !script2
  1728.             
  1729.  
  1730.          TIPS
  1731.          ════
  1732.  
  1733.                 You have up to 260 simple variables for use.  If you should
  1734.          run out, feel free to use slots in the global array as simple
  1735.          variables (ie. $0, $1, $2, and so on).  The only limitation
  1736.          is that global array slots cannot be used as the index variable
  1737.          in a DO-LOOP structure.
  1738.  
  1739.                 Simple Variables and the Global Array Variable are NOT
  1740.          automatically cleared when a script is started, or when the LINK
  1741.          command is used to branch to another script.  Therefore, you must
  1742.          explicitly use the LET command to clear or zero any variables
  1743.          which you want cleared.
  1744.         
  1745.      >>  let a = "" 
  1746.     
  1747.      >>  let b = 0
  1748.  
  1749.          This also means that you may pass information or data values
  1750.          from one script to another.
  1751.  
  1752.  
  1753.                 Two important parts of each user's account record are
  1754.          the "access flags" (!56) and "flags" (!57).  The "access flags"
  1755.          are used primarly for access-control to DATABASES and DOORS, as
  1756.          configured through VCONFIG.EXE Database Configuration or
  1757.          Door Configuration, or VMB.EXE set-up functions.  You can
  1758.          manipulate the access flags by manipulating !56, ORing (|)
  1759.          or ANDing (&) a value to give the desired result. The
  1760.          values for the flags A through Z are:
  1761.  
  1762.          A       1 (2^0)    J     512 (2^9)    S   262144 (2^18)
  1763.          B       2 (2^1)    K    1024 (2^10)   T   524288 (2^19)
  1764.          C       4 (2^2)    L    2048 (2^11)   U  1048576 (2^20)
  1765.          D       8 (2^3)    M    4096 (2^12)   V  2097152 (2^21)
  1766.          E      16 (2^4)    N    8192 (2^13)   W  4914304 (2^22)
  1767.          F      32 (2^5)    O   16384 (2^14)   X  8388608 (2^23)
  1768.          G      64 (2^6)    P   32768 (2^15)   Y 16777216 (2^24)
  1769.          H     128 (2^7)    Q   65536 (2^16)   Z 33554432 (2^25)
  1770.          I     256 (2^8)    R  131072 (2^17)
  1771.                                                  
  1772.          The total of all flags added together is 67108863.
  1773.          
  1774.          For example, to turn on the I flag, use OR:
  1775.  
  1776.      >>  let !56=!56 | 256
  1777.     
  1778.          To turn off the I flag, use AND:
  1779.  
  1780.      >>  let t=67108863 - 256
  1781.      >>  let !56=!56 & t
  1782.      
  1783.          The other set of "flags" specify information about the user's 
  1784.          account, and govern access to network email (via NETWORKS.LST), 
  1785.          UUCP access, and Internet Pass-Thru access.  These other flags
  1786.          can be manipulated as !57, though a much easier way is to
  1787.          use the SETFLAGS command documented earlier in this text.
  1788.  
  1789.          The "flags" in use by the system are:
  1790.  
  1791.          F - Full Screen Editor
  1792.          X - Expert Mode (Menus Skipped)
  1793.          N - User Has Been Sent New-User Email
  1794.          I - Enable Internet Pass-Thru Access
  1795.          U - Enable UUCP Access
  1796.  
  1797.