home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / v611docs.zip / VMAIN611.ZIP / VC10-AB < prev    next >
Text File  |  1993-10-08  |  13KB  |  301 lines
  1.                                             VBBS 6.11 Documentation --  10-B-1
  2.  
  3.  
  4.          ╔════════════════════════════════════════════════════════════════╗
  5.          ║  CHAPTER TEN ANNEX B     INPUT AND OUTPUT COMMANDS             ║
  6.          ╚════════════════════════════════════════════════════════════════╝
  7.  
  8.  
  9.          READING INPUT
  10.          ═════════════
  11.  
  12.                One of the most common uses of a script is to get some
  13.            information from a user and the script language contains many
  14.            commands to help implement this task.  All the commands allow
  15.            for a <prompt> string, but this is optional so you do NOT have
  16.            to use it if you do not want to.
  17.  
  18.          GETYN ->  GETYN <variable1> <prompt>
  19.          GETNY ->  GETNY <variable1> <prompt>
  20.  
  21.                These two commands show the user whatever is stored within
  22.            the <prompt> and ask for a response of Y, N, or <enter>.  The
  23.            GETYN command defaults to Y when then user presses <enter> and
  24.            GETNY defaults to N.
  25.            ex: GETYN $yesorno "Do you wish to continue ? "
  26.  
  27.          RS ->  RS <variable1> <prompt>
  28.  
  29.                This command prints the optional <prompt> and then accepts
  30.            a line of input.  The input can be no more than 81 characters
  31.            in length, and input is terminated by pressing <enter>.
  32.            ex: RS $yourname "What is your name ? "
  33.  
  34.          RX ->  RX <variable1> <prompt>
  35.  
  36.                This command works like the RS command but instead of it
  37.            echoing the keys that the user presses it prints X's.  This is
  38.            very useful for password systems.
  39.  
  40.          RW ->  RW <variable1> <prompt>
  41.  
  42.                This command works like the RS command with the only real
  43.            difference being that this command has a word-wrapping feature.
  44.            If a word passes the 80 character point it is word-wrapped over
  45.            to the next input line.  To prevent the extra characters from
  46.            being placed into the next input statement you will need to
  47.            place 'Buffer Clear' after the last RW input line.  See section
  48.            5.x for more info on buffer commands.
  49.  
  50.          RN ->  RN <variable1> <prompt>
  51.  
  52.                This command prints the optional prompt and then accepts
  53.            only numerical input.  It will not take any keys but the #'s
  54.            and input is terminated by pressing <enter>.
  55.            ex: RN $number "Enter your favorite number : "
  56.  
  57.  
  58.                                             VBBS 6.11 Documentation --  10-B-2
  59.  
  60.  
  61.          RC ->  RC <variable1> <prompt>
  62.  
  63.                This command prints the optional <prompt> and then waits
  64.            for a single character to be pressed.  The character is stored
  65.            in <variable1> but it is not shown on the screen.
  66.            ex: RC $onechar "Pick a key, any key : "
  67.  
  68.          RR ->  RR <variable1> <string2> <prompt>
  69.  
  70.                This command operates in the same way as the RC command
  71.            with only one difference.  It will only accept characters that
  72.            are listed in the <string2>, all others will be ignored.
  73.            ex: RR $thisone ARI "A>bort, R>etry, I>gnore ? "
  74.  
  75.          RL ->  RL <variable1> <string2> <value3> <prompt>
  76.  
  77.                This command operates similarly to the RR command.  It will
  78.            accept any character listed in <string2> and also will accept a
  79.            number between 1 and <value3>.  This is the most versatile form
  80.            for getting input, and is most commonly used for creating a
  81.            menu within a script.
  82.            ex: RL $thatone ABC 3 "Choose A, B, C, 1, 2, or 3 : "
  83.  
  84.          RF ->  RF <variable1> <prompt>
  85.  
  86.                This command is used to get a filename as input.  It will
  87.            only accept input in the format 'xxxxxxxx.xxx' with each 'x'
  88.            being a character.  It will only allow legal characters for the
  89.            name and it will not accept globals (* and ?.)  The complete
  90.            list of acceptable characters contains A thru Z (uppercase is
  91.            forced automatically) and the symbols => ! # $ _ - (the => is
  92.            not in the list, it is used only for emphasis.)
  93.            ex: RF $filename "Name of file to be uploaded : "
  94.  
  95.          RI ->  RI <variable1> <prompt>
  96.  
  97.                This command is nearly identical to the RF command.  The
  98.            one difference being that this command accepts the * and ?
  99.            globals in the filename.
  100.            ex: RI $filetoget "Name of file to find (* and ? allowed) : "
  101.  
  102.  
  103.          SHOWING LINE OUTPUT
  104.          ═══════════════════
  105.  
  106.                There are two different ways that you can show output one
  107.            line at a time.  While they are slightly different, both accept
  108.            the same formatting information for their output.
  109.  
  110.          TR ->  TR <token2> <token3> <token4> ... <token7>
  111.          TS ->  TS <token2> <token3> <token4> ... <token7>
  112.  
  113.                These commands can print out up to 6 different tokens using
  114.            a single line.  After the last token on the line is printed the
  115.  
  116.  
  117.                                             VBBS 6.11 Documentation --  10-B-3
  118.  
  119.  
  120.            TR command performs a carriage return/linefeed while the TS
  121.            command does not.
  122.  
  123.            The three formatting statements are listed below.
  124.  
  125.            %s ->  %s<number1> <variable2>
  126.  
  127.                Outputs <variable2> in a field of <number1> spaces and then
  128.            left justifies it.
  129.  
  130.            %i ->  %i<number1> <variable2>
  131.  
  132.                Outputs <variable2> in a field of <number1> spaces and then
  133.            right justifies it.
  134.  
  135.            %d ->  %d<number1>.<number2> <value3>
  136.  
  137.                Outputs <value3> with the format ###.## where <number1> and
  138.            <number2> are the ### and the .## respectively.  The left part
  139.            of the output is padded with spaces and the right is padded
  140.            with 0's.  This format uses the absolute value of <value3>, so
  141.            the output is always a positive number.
  142.  
  143.                You can use any numbers within the statements as long as
  144.            you follow the specified syntax.  If the field selected is too
  145.            small for the variable then the output will be chopped down to
  146.            fit it into the field.
  147.  
  148.            Example:                     Results:
  149.            $a = "Green"
  150.            $b = 16.2312
  151.            tr $b " : " %d3.3 $b         => "16.2312 :  16.231"
  152.            tr %s10 $a ":" %i10 $a       => "Green     :     Green"
  153.            ts $b " : "
  154.            tr $a " : The End"           => "16.2312 : Green : The End"
  155.  
  156.            Note: The quotes are not in the actual output, they are only
  157.                  supplied to emphasize the blank spaces.
  158.  
  159.  
  160.  
  161.          COLORIZATION
  162.          ════════════
  163.  
  164.                 There are three different ways to change color in the
  165.          script language.  All are identical in output, but each has a
  166.          unique form of implementation.  Note: <color code> is the number
  167.          number (0-9) or letter (capital A-Z) code that corresponds to the
  168.          colors as listed in the COLORS.TXT file.  Also, the input commands
  169.          from section 3.1 (RS, RW, RX, etc.) will all change the color to
  170.          to the user's default prompt setting unless the <prompt> has a
  171.          color code within it.
  172.  
  173.  
  174.                                             VBBS 6.11 Documentation --  10-B-4
  175.  
  176.  
  177.          ANSIC ->  ANSIC <color code>
  178.  
  179.                This command is executed on a line by itself and changes
  180.            the effective color to that of the selected <color code>.
  181.  
  182.          $<color> ->  Special
  183.  
  184.                The $color commands are actually individual tokens that
  185.            resemble variable names.  As such, they may be included into
  186.            other strings with the '&' command (section 2.3) or used on
  187.            their own in output statements (TR & TS.)
  188.  
  189.                 $<color>   color code      $<color>   color code
  190.                 --------   ----------      --------   ----------
  191.                 $RED           6           $YELLOW        2
  192.                 $BLUE          7           $MAGENTA       B
  193.                 $GREEN         5           $CYAN          1
  194.                 $WHITE         U           $NORM          0
  195.                 $BLACK        n/a
  196.  
  197.                The command $BLACK makes very dark letters though they may
  198.            be visible, depending on your system configuration.  A common
  199.            use for this is to cover over ANSI music symbols.
  200.  
  201.          Hearts ->  Special
  202.  
  203.                The most frequently used way to change colors is to use
  204.            what has been coined 'Heart-code ANSI.'  The Heart code is the
  205.            ASCII code 3 and can be created in a couple of different ways.
  206.            If your ANSI driver supports the extended ASCII character set
  207.            you can create the 'heart' by pressing the <CTRL> key and the
  208.            <C> key or it can be made by holding down the <ALT> key, then
  209.            press 3 (or 003 or 259) on the number pad and then releasing
  210.            the <ALT> key.  You will have to test this for your particular
  211.            system to see which works for you.  You can also create the
  212.            codes by using the full-screen editor to colorize although this
  213.            can be a bit of work.  Immediately after the 'heart' you place
  214.            the desired <color code> and when the script actually runs,
  215.            VBBS will show the correct color (you will not see the 'heart'
  216.            or the next character after it.)
  217.  
  218.           Example:
  219.              These -----\_______/ANSIC 6
  220.              three      |       \TR "Hello ! " $handle
  221.              pieces     |
  222.              of code    |_______/$stuff = $red & "Hello ! " & $handle
  223.              all do     |       \TR $stuff
  224.              the exact  |
  225.              same thing-/-------<TR "<heart>6Hello ! " & $handle
  226.  
  227.  
  228.                                             VBBS 6.11 Documentation --  10-B-5
  229.  
  230.  
  231.          OTHER DISPLAY COMMANDS
  232.          ══════════════════════
  233.  
  234.          EF ->  EF <pathfile1>
  235.  
  236.                This command displays the contents of the specified file
  237.            in <pathfile1>.  It will pause whenever the users screen fills
  238.            and continue when a key is pressed.
  239.  
  240.          DRAWWAITBAR ->  DRAWWAITBAR <value1>
  241.  
  242.                This command draws a string of green o's surrounded by red
  243.            []'s. The number of o's is equal to <value1>.  The cursor is
  244.            then placed on the first 'o' so you can write over it with
  245.            another character.  See Appendix D for an example.
  246.  
  247.          LOC ->  LOC <value1> <value2>
  248.  
  249.                This command places the cursor at the location equal to the
  250.            (x, y) coordinates that match (<value2>, <value1>).  Legitimate
  251.            values for <value1> are 1-25 and for <value2> are 1-80. This
  252.            only operates for users of ANSI, Enhanced ANSI, and VGIX.
  253.  
  254.          MENU ->  MENU <filename1>
  255.  
  256.                This command displays a menu file stored in your text
  257.            directory (as set in VCONFIG.)  VBBS first checks to see if
  258.            <filename>.MNU exists, and shows it if true.  Otherwise it
  259.            shows <filename>.ANS if the user has ANSI and <filename>.ASC
  260.            otherwise.
  261.  
  262.                The .MNU files are universal text files colorized with
  263.            VBBS' heart-code ANSI colors.  If the user has ANSI then the
  264.            file displays w/ the colors, but if the user does not have
  265.            ANSI then it is displayed without the colors.  You can still
  266.            use .ANS and .ASC menus if you like, however.
  267.  
  268.                If ! is the first character of a line in a menu then VBBS
  269.            will only show the line if the user's security level is greater
  270.            than or equal to the three-digit number that follows the '!'.
  271.  
  272.            Examples:
  273.            !255 S) SysOp Menu  <== Not shown unless the user has SL >= 255.
  274.            !100 F) Forward     <==  "    "     "     "   "    "   " >= 100.
  275.  
  276.          NEWPAGE <---
  277.          SUSPENDPAGEBREAK <---
  278.          RESUMEPAGEBREAK <---
  279.  
  280.                These three commands alter the user's page-break pointer.
  281.            This pointer determines how many lines of text have been viewed
  282.            and the user's screen length (as set in defaults) determines
  283.            when a pause should be used.  NEWPAGE resets the pointer to 0
  284.  
  285.  
  286.                                             VBBS 6.11 Documentation --  10-B-6
  287.  
  288.  
  289.            so the output will scroll for a number of lines equal to the
  290.            value set in the user's defaults.  SUSPENDPAGEBREAK turns the
  291.            use of the pointer off completely (no pauses at all), while
  292.            RESUMEPAGEBREAK turns the pointer back on.
  293.  
  294.          PAUSE ->  PAUSE <prompt>
  295.  
  296.                This displays the optional <prompt> or the default prompt
  297.            as set in VCONFIG.  It then waits for a keypress and erases
  298.            the prompt before continuing.
  299.  
  300.  
  301.