OS/2 Shareware BBS: 2 BBS

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / vdocs.zip / VC10B < prev next >

Wrap

Text File | 1993-12-16 | 13KB | 304 lines

.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.