.TOPIC:                                            
Input & Output Commands

                                            VBBS 6.12 Documentation --  10-B-1


         ͻ
           CHAPTER TEN ANNEX B     INPUT AND OUTPUT COMMANDS             
         ͼ


         READING INPUT
         

               One of the most common uses of a script is to get some
           information from a user and the script language contains many
           commands to help implement this task.  All the commands allow
           for a <prompt> string, but this is optional so you do NOT have
           to use it if you do not want to.

         GETYN ->  GETYN <variable1> <prompt>
         GETNY ->  GETNY <variable1> <prompt>

               These two commands show the user whatever is stored within
           the <prompt> and ask for a response of Y, N, or <enter>.  The
           GETYN command defaults to Y when then user presses <enter> and
           GETNY defaults to N.
           ex: GETYN $yesorno "Do you wish to continue ? "

         RS ->  RS <variable1> <prompt>

               This command prints the optional <prompt> and then accepts
           a line of input.  The input can be no more than 81 characters
           in length, and input is terminated by pressing <enter>.
           ex: RS $yourname "What is your name ? "

         RX ->  RX <variable1> <prompt>

               This command works like the RS command but instead of it
           echoing the keys that the user presses it prints X's.  This is
           very useful for password systems.

         RW ->  RW <variable1> <prompt>

               This command works like the RS command with the only real
           difference being that this command has a word-wrapping feature.
           If a word passes the 80 character point it is word-wrapped over
           to the next input line.  To prevent the extra characters from
           being placed into the next input statement you will need to
           place 'Buffer Clear' after the last RW input line.  See section
           5.x for more info on buffer commands.

         RN ->  RN <variable1> <prompt>

               This command prints the optional prompt and then accepts
           only numerical input.  It will not take any keys but the #'s
           and input is terminated by pressing <enter>.
           ex: RN $number "Enter your favorite number : "


                                            VBBS 6.12 Documentation --  10-B-2


         RC ->  RC <variable1> <prompt>

               This command prints the optional <prompt> and then waits
           for a single character to be pressed.  The character is stored
           in <variable1> but it is not shown on the screen.
           ex: RC $onechar "Pick a key, any key : "

         RR ->  RR <variable1> <string2> <prompt>

               This command operates in the same way as the RC command
           with only one difference.  It will only accept characters that
           are listed in the <string2>, all others will be ignored.
           ex: RR $thisone ARI "A>bort, R>etry, I>gnore ? "

         RL ->  RL <variable1> <string2> <value3> <prompt>

               This command operates similarly to the RR command.  It will
           accept any character listed in <string2> and also will accept a
           number between 1 and <value3>.  This is the most versatile form
           for getting input, and is most commonly used for creating a
           menu within a script.
           ex: RL $thatone ABC 3 "Choose A, B, C, 1, 2, or 3 : "

         RF ->  RF <variable1> <prompt>

               This command is used to get a filename as input.  It will
           only accept input in the format 'xxxxxxxx.xxx' with each 'x'
           being a character.  It will only allow legal characters for the
           name and it will not accept globals (* and ?.)  The complete
           list of acceptable characters contains A thru Z (uppercase is
           forced automatically) and the symbols => ! # $ _ - (the => is
           not in the list, it is used only for emphasis.)
           ex: RF $filename "Name of file to be uploaded : "

         RI ->  RI <variable1> <prompt>

               This command is nearly identical to the RF command.  The
           one difference being that this command accepts the * and ?
           globals in the filename.
           ex: RI $filetoget "Name of file to find (* and ? allowed) : "


         SHOWING LINE OUTPUT
         

               There are two different ways that you can show output one
           line at a time.  While they are slightly different, both accept
           the same formatting information for their output.

         TR ->  TR <token2> <token3> <token4> ... <token7>
         TS ->  TS <token2> <token3> <token4> ... <token7>

               These commands can print out up to 6 different tokens using
           a single line.  After the last token on the line is printed the


                                            VBBS 6.12 Documentation --  10-B-3


           TR command performs a carriage return/linefeed while the TS
           command does not.

           The three formatting statements are listed below.

           %s ->  %s<number1> <variable2>

               Outputs <variable2> in a field of <number1> spaces and then
           left justifies it.

           %i ->  %i<number1> <variable2>

               Outputs <variable2> in a field of <number1> spaces and then
           right justifies it.

           %d ->  %d<number1>.<number2> <value3>

               Outputs <value3> with the format ###.## where <number1> and
           <number2> are the ### and the .## respectively.  The left part
           of the output is padded with spaces and the right is padded
           with 0's.  This format uses the absolute value of <value3>, so
           the output is always a positive number.

               You can use any numbers within the statements as long as
           you follow the specified syntax.  If the field selected is too
           small for the variable then the output will be chopped down to
           fit it into the field.

           Example:                     Results:
           $a = "Green"
           $b = 16.2312
           tr $b " : " %d3.3 $b         => "16.2312 :  16.231"
           tr %s10 $a ":" %i10 $a       => "Green     :     Green"
           ts $b " : "
           tr $a " : The End"           => "16.2312 : Green : The End"

           Note: The quotes are not in the actual output, they are only
                 supplied to emphasize the blank spaces.



         COLORIZATION
         

                There are three different ways to change color in the
         script language.  All are identical in output, but each has a
         unique form of implementation.  Note: <color code> is the number
         number (0-9) or letter (capital A-Z) code that corresponds to the
         colors as listed in the COLORS.TXT file.  Also, the input commands
         from section 3.1 (RS, RW, RX, etc.) will all change the color to
         to the user's default prompt setting unless the <prompt> has a
         color code within it.


                                            VBBS 6.12 Documentation --  10-B-4


         ANSIC ->  ANSIC <color code>

               This command is executed on a line by itself and changes
           the effective color to that of the selected <color code>.

         $<color> ->  Special

               The $color commands are actually individual tokens that
           resemble variable names.  As such, they may be included into
           other strings with the '&' command (section 2.3) or used on
           their own in output statements (TR & TS.)

                $<color>   color code      $<color>   color code
                --------   ----------      --------   ----------
                $RED           6           $YELLOW        2
                $BLUE          7           $MAGENTA       B
                $GREEN         5           $CYAN          1
                $WHITE         U           $NORM          0
                $BLACK        n/a

               The command $BLACK makes very dark letters though they may
           be visible, depending on your system configuration.  A common
           use for this is to cover over ANSI music symbols.

         Hearts ->  Special

               The most frequently used way to change colors is to use
           what has been coined 'Heart-code ANSI.'  The Heart code is the
           ASCII code 3 and can be created in a couple of different ways.
           If your ANSI driver supports the extended ASCII character set
           you can create the 'heart' by pressing the <CTRL> key and the
           <C> key or it can be made by holding down the <ALT> key, then
           press 3 (or 003 or 259) on the number pad and then releasing
           the <ALT> key.  You will have to test this for your particular
           system to see which works for you.  You can also create the
           codes by using the full-screen editor to colorize although this
           can be a bit of work.  Immediately after the 'heart' you place
           the desired <color code> and when the script actually runs,
           VBBS will show the correct color (you will not see the 'heart'
           or the next character after it.)

          Example:
             These -----\_______/ANSIC 6
             three      |       \TR "Hello ! " $handle
             pieces     |
             of code    |_______/$stuff = $red & "Hello ! " & $handle
             all do     |       \TR $stuff
             the exact  |
             same thing-/-------<TR "<heart>6Hello ! " & $handle


                                            VBBS 6.12 Documentation --  10-B-5


         OTHER DISPLAY COMMANDS
         

         EF ->  EF <pathfile1>

               This command displays the contents of the specified file
           in <pathfile1>.  It will pause whenever the users screen fills
           and continue when a key is pressed.

         DRAWWAITBAR ->  DRAWWAITBAR <value1>

               This command draws a string of green o's surrounded by red
           []'s. The number of o's is equal to <value1>.  The cursor is
           then placed on the first 'o' so you can write over it with
           another character.  See Appendix D for an example.

         LOC ->  LOC <value1> <value2>

               This command places the cursor at the location equal to the
           (x, y) coordinates that match (<value2>, <value1>).  Legitimate
           values for <value1> are 1-25 and for <value2> are 1-80. This
           only operates for users of ANSI, Enhanced ANSI, and VGIX.

         MENU ->  MENU <filename1>

               This command displays a menu file stored in your text
           directory (as set in VCONFIG.)  VBBS first checks to see if
           <filename>.MNU exists, and shows it if true.  Otherwise it
           shows <filename>.ANS if the user has ANSI and <filename>.ASC
           otherwise.

               The .MNU files are universal text files colorized with
           VBBS' heart-code ANSI colors.  If the user has ANSI then the
           file displays w/ the colors, but if the user does not have
           ANSI then it is displayed without the colors.  You can still
           use .ANS and .ASC menus if you like, however.

               If ! is the first character of a line in a menu then VBBS
           will only show the line if the user's security level is greater
           than or equal to the three-digit number that follows the '!'.

           Examples:
           !255 S) SysOp Menu  <== Not shown unless the user has SL >= 255.
           !100 F) Forward     <==  "    "     "     "   "    "   " >= 100.

         NEWPAGE <---
         SUSPENDPAGEBREAK <---
         RESUMEPAGEBREAK <---

               These three commands alter the user's page-break pointer.
           This pointer determines how many lines of text have been viewed
           and the user's screen length (as set in defaults) determines
           when a pause should be used.  NEWPAGE resets the pointer to 0


                                            VBBS 6.12 Documentation --  10-B-6


           so the output will scroll for a number of lines equal to the
           value set in the user's defaults.  SUSPENDPAGEBREAK turns the
           use of the pointer off completely (no pauses at all), while
           RESUMEPAGEBREAK turns the pointer back on.

         PAUSE ->  PAUSE <prompt>

               This displays the optional <prompt> or the default prompt
           as set in VCONFIG.  It then waits for a keypress and erases
           the prompt before continuing.


