OS/2 Shareware BBS: 2 BBS/02-BBS.zip/va210-o2.zip/VWCSYSOP.DOC

Text File | 1997-02-05 | 29KB | 847 lines

         VWC SYSOP
         ═════════

                VWC is short for Virtual Windows Client -- a free
         communications software program written for Microsoft
         Windows that your callers (and soon, telnet'ers) can use
         to access your Virtual Advanced Bulletin Board System.

                VWC can do some pretty awesome things:

         -Open up to two standard GUI windows at a time

         -Place Command Buttons, Option Boxes, Check Boxes,
          Text, and other GUI elements on each window

         -Flexible, efficient screen design language

         -Compatible with Windows-Standard .BMP, .ICO and .WAV formats

         -Dynamically transmit .BMP pictures for display and/or
          .WAV sounds files for immediate play, and/or make use
          of same files already on the caller's hard drive.

         -Built-In ANSI terminal window for handling plain text
          and ansi color with "door games."

          For information related to using VWC to access boards,
          see the VWC.DOC that comes with the VWC archive.  This
          document describes the VWC command set and gives examples.


         VWC FILES
         ═════════

                Included with the basic Virtual Advanced set-up
         are two kinds of *.VWC files; during INSTALL.EXE they
         are automatically copied to your Text Directory.  The first
         kind are the MENU/LOGIN files such as MAIN.VWC, LOGIN.VWC,
         and so on.  The second kind are the R###.VWC files that
         serves as replacements for external strings.

                The first kind, the menus, typically draw out a whole
         menu, or scene, and then wait for the user to make some type
         of input -- clicking the mouse or using the keyboard.

                The second kind, the replacements, are mostly scene
         fragments, though some are complete scenes of their own.

                There are three important rules when creating VWC files:

         1) The first line should always be blank

         2) Each line thereafter must begin with the "\"
            character, or it will be interpreted as normal text.

         3) Parameters on the command line, if any, are separated
            from the command and from each other by a single space
            character.


         VWC COMMAND SET
         ═══════════════

         \@

             Closes all GUI windows currently open (if any).

         \!

             Clears the ANSI terminal window.

         \# <state>

             Set WindowState of the ANSI terminal window
             according to the value of <state>:

             <state> = 0  Normal
             <state> = 1  Maximized
             <state> = 2  Minimized

         \$

             Hides the ANSI terminal window.

         \^

             Unhides the ANSI terminal window.

         \a <color table>

             Set background color of the currently open GUI window
             using <color table>:

             0 black    4 red        8 grey         12 light red
             1 blue     5 magenta    9 light blue   13 light magenta
             2 green    6 brown     10 light green  14 yellow
             3 cyan     7 white     11 light cyan   15 bright white

         \A <RGB color>

             Set background color of the currently open GUI window
             using <RGB color>. <RGB color> numbers are formed using
             the following pattern:

             &H00xxyyzz

             Where xx, yy, and zz are hexadecimal (00 to FF)
             values defining the levels of Red (xx), Green (yy),
             and Blue (zz).  The \A command gives finer detailed
             control over color usage than \a.

         \b <x1> <y1> <x2> <y2>

             Draws a box on the current GUI window using <x1>, <y1>
             and <x2>, <y2> as coordinates of the upper-left and
             lower-right corners, respectively.  The box is drawn
             using the currently selected color (\c or \C).

             Maximum number of boxes per window: unlimited.

         \B <x1> <y1> <x2> <y2>

             Same as \b, but the box is drawn filled in.

             Maximum number of filled-in boxes per window: unlimited.

         \c <color table>

             Set foreground color of the currently open GUI window
             using <color table>:

             0 black    4 red        8 grey         12 light red
             1 blue     5 magenta    9 light blue   13 light magenta
             2 green    6 brown     10 light green  14 yellow
             3 cyan     7 white     11 light cyan   15 bright white

         \C <RGB color>

             Set foreground color of the currently open GUI window
             using <RGB color>. <RGB color> numbers are formed using
             the following pattern:

             &H00xxyyzz

             Where xx, yy, and zz are hexadecimal (00 to FF)
             values defining the levels of Red (xx), Green (yy),
             and Blue (zz).  The \A command gives finer detailed
             control over color usage than \a.

         \d <text>

             Prints <text> on the currently open GUI window
             at the current cursor position, using the current
             foreground color.

         \D <x> <y>

             Sets the current cursor position of the GUI window.

         \e <left> <top> <width> <height>

             Initializes a text list-box in the current GUI window.
             <left> and <top> specify the location of the list-box,
             relative the top left corner of the window.  <width>
             and <height> specify the size of the list-box.

             Maximum number of list-boxes per window: 1.

         \E <item text...>

             Adds a text item to the list-box.

             Maximum number of item per list-box: 2000.

         \f <left> <top> <width> <height> <reserved> <default input>

             Pops up a text input box.  <left> and <top> specify the
             location, <width> and <height> the size.  <reserved>
             should always be 0.  <default input> (optional) is
             text put into the text box for the user to edit or
             press enter to accept as-is.

         \l <x1> <y1> <x2> <y2>

             Draws a line using the current foreground color, from
             <x1>, <y1> to <x2>, <y2> on the current GUI window.

             Maximum number of lines per window: unlimited.

         \L <x> <y> <radius>

             Draws a circle using the current foreground color
             with the center of the circle at coordinates <x>, <y>
             and with the given <radius>.

             Maximum number of circles per window: unlimited.

         \m <left> <top> <width> <height> <closewindow> <return>

             Creates a command button on the current GUI window, located
             at <left>, <top> relative to the window, with a size of
             the given <width> and <height>.

             <closewindow> is 1 if you want activation of the button
             to automatically close the window, 0 otherwise.  This is
             handy from the BBS perspective as it simplifies things.

             <return> is the text you want VWC to send back when the
             button is clicked.

             For example, the default VWC menus set VWC to return
             "/WHO" when someone clicks the "Who's Online" button.
             To the BBS, clicking on a command button is the same
             as when as a non-VWC caller type commands manually.

             Note: The Text Caption to be used for this newly created
                   button should have been set previously with the \t
                   command.

             Maximum number of buttons per window: 20.

         \M

             Removes the most recently created command button.

         \p <left> <top> <visible> <autosize> <filename> <closewindow> <return>

             Creates a picture-box on the current GUI window and loads
             and displays Bitmap (BMP) pictures and Icon (ICO) files stored
             on the caller's hard drive.  \p is also used to call up icons
             which have been package the ICONLIB.DAT file.

             <left> and <top> are coordinates relative to the current
             GUI window.

             <visible> specifies whether the picture should be made visible
             immediately upon loading from disk.  Currently, this should
             always be 1.

             <autosize> specifies whether windows should automatically
             size the picture-box to fit the graphic.  Currently, this
             should always be 1.

             <filename> specifies the file to load.  If <filename>
             has no extension, then ICONLIB.DAT is searched.  If
             the extension is .ICO, then the picture is loaded as
             an icon file.  If the extension is .BMP, then the picture
             is loaded as a bitmapped picture.

             <closewindow> and <return> are optional; they allow you
             make a picture or icon a click-able command.  Their
             meaning and usage as exactly the same as for the \m
             command button command described previously.

             Maximum number of pictures per window: 22.

         \P

             Removes the most recently created picture-box.

         \s <filename> <options>

             Plays a WAV file, using the desired <options>. <filename>
             should specify a WAV file on the hard drive (do include
             the .WAV extension).  <options> are:

             0 Synchronous:   Processing Held Up Until Sound Completed
             1 Asynchronous:  Processing Continues While Sound Plays

             The sound will stop when the entire WAV file has been played.

         \S

             Stops the playing of the WAV file, even if it hasn't
             been played all the way through.

         \t <caption text>

             Sets the Caption Text to be used for next GUI window
             to be opened with the \w command, or the next command
             button be created with the \m command.

         \T <milliseconds>

              Time delay for <milliseconds>. 1000 milliseconds = 1 sec.
              Multi-tasking friendly.

         \w <left> <top> <width> <height> <visible>

             Creates a GUI window using the parameters given.  <left>
             and <top> are relative to the whole screen, and <height>
             and <width> control the size.

             <visible> specifies whether the window should be made visible
             immediately upon its creation, and currently this should always
             be set to 1.

             Note: The Text Caption to be used for this newly created
                   window should have been set previously with the \t
                   command.

             Maximum number of GUI windows: 2.

         \W

             Closes the most recently opened GUI window.

         \x <filename> <overwrite>

            Dynamically plays WAV files.  If <overwrite> is 0,
            then the user's hard drive is check for <filename>,
            and if found it is immediately played.  If the
            file is not found, then VWC will receive the file
            with Ymodem, and then immediately play the file.
            If <overwrite> is 1, then same-name copies of <filename>
            on the user's hard drive are ignored, and a new file
            is received with Ymodem, and then immediately played.
            <filename> must have a .WAV or .WA$ extension.

            Note: <overwrite>=1 should only be used when the intention
                  is to update an older version of the same file, or
                  when you absolutely want to make sure that the file
                  is retransmitted every time. Use <overwrite>=1
                  sparingly.

         \X <filename> <left> <top> <overwrite>

            Dynamically loads and displays BMP files.  If <overwrite> is 0,
            then the user's hard drive is check for <filename>,
            and if found it is immediately displayed.  If the
            file is not found, then VWC will receive the file
            with Ymodem, and then immediately display the file.
            If <overwrite> is 1, then same-name copies of <filename>
            on the user's hard drive are ignored, and a new file
            is received with Ymodem, and then immediately displayed.
            <filename> must have a .BMP or .BM$ extension.

            Note: <overwrite>=1 should only be used when the intention
                  is to update an older version of the same file, or
                  when you absolutely want to make sure that the file
                  is retransmitted every time. Use <overwrite>=1
                  sparingly.

         \y

             Causes VWC to automatically enter YMODEM receive mode
             to receive one or more files -- typically BMP, ICO, or
             WAV files.

             Note: This command can be used ONLY with a script.

         \Y

             Causes VWC to automatically enter YMODEM-G receive mode
             to receive one or more files -- typically BMP, ICO, or
             WAV files.

             Note: This command can be used ONLY with a script.

         \z <RGB Color>

             Set foreground color of the currently open GUI window
             using <RGB color>. <RGB color> numbers are formed using
             the following pattern:

             &H00xxyyzz

             Where xx, yy, and zz are hexadecimal (00 to FF)
             values defining the levels of Red (xx), Green (yy),
             and Blue (zz).  The \A command gives finer detailed
             control over color usage than \a.

         \Z <RGB Color>

             Set background color of the currently open GUI window
             using <RGB color>. <RGB color> numbers are formed using
             the following pattern:

             &H00xxyyzz

             Where xx, yy, and zz are hexadecimal (00 to FF)
             values defining the levels of Red (xx), Green (yy),
             and Blue (zz).  The \A command gives finer detailed
             control over color usage than \a.


         EXAMPLE VWC FILES
         ═════════════════

                The default Virtual Advanced package comes with dozens
         of ready-to-use VWC files.  You may modify these files,
         or use them as-is.  Please feel free to examine these files
         and compare them to the information in this documentation.


         COMMANDING VWC WITH SCRIPTS
         ═══════════════════════════

                There is a lot that can be done with "static" VWC
         files, as has been previously described.  However, when
         using Virtual Advacned script language to specifically
         work with VWC, there lies true potential.

         First off, you'll need a way to detect from within script
         when VWC is being used by the remote caller.  !23 is the
         special script variable that gives the current video mode
         as a number between 0 and 4:

         0 ASCII
         1 ANSI
         2 ANSI-Enhanced
         3 RIP
         4 VWC

         The following script code fragments demonstrate.  A lot of
         comments (') have been put in for clarity.

         'Example showing how to branch to another
         'part of the script if VWC is being used
         '
         ifval !23=4 goto vwcyes
         '
         'script code for non-VWC callers goes here
         '
         exit
         '
         vwcyes:
         '
         ' code for VWC callers goes here
         '
         exit


         'Example showing how to skip over the entire script if VWC
         'is not being used (ie..use for VWC-only script)
         '
         ifval !23<4 goto exitscript
         '
         'script code for VWC callers goes here
         '
         exitscript:
         exit

         Now, for some real examples of script code that illustrate
         how to command VWC interactively, dynamically, and how to
         send data on-the-fly.

         The first example shows how to display a BMP file on the fly.
         The bitmap has not been pre-compressed by PAK.EXE.  The bitmap
         file LOGO.BMP is assumed to reside in the Virtual Advanced main
         directory, waiting for occassions where it needs to be transmitted.

?
? "\t LOGO.BMP"
? "\w 0 0 8000 6000 1"
? "\t &Close"
? "\m 0 0 1200 400 1 ^M"
? "\X LOGO.BMP 0 0 0"
let x = "vxy " % !12 % " -YS LOGO.BMP"
shell x
delay 2
pause

         Note that in the above example, the <overwrite> field is set to
         0, meaning that the file will need to be transmitted from
         the BBS to the remote caller if the file doesn't already
         exist on the caller's system.  Here is the same example
         with comments:

?                                        <-- Required Blank Line
? "\t LOGO.BMP"                          <-- Set Text Caption For Window
? "\w 80 2000 8000 6000 1"               <-- Open GUI Window
? "\t &Close"                            <-- Set Text Caption For Button
? "\m 0 0 1200 400 1 ^M"                 <-- Create Close Button
? "\X LOGO.BMP 0 0 0"                    <-- VWC Download/Display BMP
let x = "vxy " % !12 % " -YS LOGO.BMP"   <-- Prepare Command Line For BBS
shell x                                  <-- Start VXY For Transfer
delay 2                                  <-- Delay 2 Seconds
pause                                    <-- Wait Click On Close Button

         Note that in all of these examples, the window sizes, button
         sizes, captions, etc can be altered to suit your needs and/or
         fit your BMP.

         The next example shows how to display a BMP file on the fly.
         The bitmap has been pre-compressed by PAK.EXE.  The bitmap
         file BIRTHDAY.BM$ is assumed to reside in the Virtual Advanced main
         directory, waiting for occassions where it needs to be transmitted.

?
? "\t BIRTHDAY.BMP"
? "\w 80 200 12000 8000 1"
? "\t &Close"
? "\m 0 0 1200 400 1 ^M"
? "\X BIRTHDAY.BMP 0 0 0"
let x = "vxy " % !12 % " -YS BIRTHDAY.BMP"
shell x
delay 2
pause

         Note that in the above example, the <overwrite> field is set to
         0, meaning that the file will need to be transmitted from
         the BBS to the remote caller if the file doesn't already
         exist on the caller's system.  If you wanted to make sure
         to overwrite any previous older version of the file:

?
? "\t BIRTHDAY.BMP"
? "\w 80 200 12000 8000 1"
? "\t &Close"
? "\m 0 0 1200 400 1 ^M"
? "\X BIRTHDAY.BMP 0 0 1"
let x = "vxy " % !12 % " -YS BIRTHDAY.BMP"
shell x
delay 2
pause

         The following example illustrates how to make VWC play
         a WAV file on-the-fly:

?
? "\x WELCOME.WA$ 0"
let x = "vxy " % !12 % " -YS WELCOME.WA$"
shell x
delay 2

         Note that it wasn't required to open a window to play a sound.
         Note also that the <overwrite> field is set to 0, indicating
         that the file will only be retransmitted if necessary.  If you
         wanted to update the file you would instead use:

?
? "\x WELCOME.WA$ 1"
let x = "vxy " % !12 % " -YS WELCOME.WA$"
shell x
delay 2

         The next example is more complex than the previous examples.
         It details a complete script, using GUI windows with command
         buttons as interactive menus, displaying the weather map
         (.BM$ picture) requested by the user:

'Required start
?
? "\$"
top:
'Display menu to user
suspendpagebreak
? "\t Weather Information"
? "\w 1600 1500 5540 4150 1"
? "\t &High Temps"
? "\m 200 100 2400 400 0 1"
? "\t &Low Temps"
? "\m 200 600 2400 400 0 2"
? "\t &Extended Forecast"
? "\m 200 1100 2400 400 0 3"
? "\t &24hr Precip"
? "\m 200 1600 2400 400 0 4"
? "\t &Precip Forecast"
? "\m 200 2100 2400 400 0 5"
? "\t S&unshine Forecast"
? "\m 200 2600 2400 400 0 6"
? "\t US &Radar"
? "\m 2800 100 2400 400 0 C"
? "\t Northern Radar"
? "\m 2800 600 2400 400 0 A"
? "\t Southern Radar"
? "\m 2800 1100 2400 400 0 B"
? "\t National &Satellite"
? "\m 2800 1600 2400 400 0 F"
? "\t Eastern Satellite"
? "\m 2800 2100 2400 400 0 D"
? "\t Western Satellite"
? "\m 2800 2600 2400 400 0 E"
? "\t E&xit"
? "\m 200 3100 5000 400 0 Q"
resumepagebreak
'Get user input & execute choice
rc a
if a="Q" goto quit
if a="1" goto ht
if a="2" goto lt
if a="3" goto ext
if a="4" goto 24hr
if a="5" goto p2us
if a="6" goto snus
if a="A" goto rne_
if a="B" goto rse_
if a="C" goto rus
if a="D" goto es
if a="E" goto ws
if a="F" goto us
goto top
quit:
?
? "\W"
? "\#"
exit
ht:
let f="HT??.bm$"
let z="High Temps"
let n=2
gosub dofiles
goto top
lt:
let f="LT??.bm$"
let z="Low Temps"
let n=2
gosub dofiles
goto top
ext:
let f="?EWX.bm$"
let z="Extended Forecast"
let n=3
gosub dofiles
goto top
24hr:
let f="24hr.bm$"
let z="Past 24hr Precipitation"
let n=1
gosub dofiles
goto top
p2us:
let f="p2us.bm$"
let z="Next 24hr Precipitation Forecast"
let n=1
gosub dofiles
goto top
snus:
let f="snus.bm$"
let z="Sunshine Forecast"
let n=1
gosub dofiles
goto top
rne_:
let f="rn?_.bm$"
let z="Northern Radar"
let n=3
gosub dofiles
goto top
rse_:
let f="rs?_.bm$"
let z="Southern Radar"
let n=3
gosub dofiles
goto top
rus:
let f="rus_.bm$"
let z="US Radar"
let n=1
gosub dofiles
goto top
es:
let f="se0?.bm$"
let z="Eastern Satellite"
let n=2
gosub dofiles
goto top
ws:
let f="sw0?.bm$"
let z="Western Satellite"
let n=2
gosub dofiles
goto top
us:
let f="su0?.bm$"
let z="National Satellite"
let n=2
gosub dofiles
goto top
'Get files by filemask and deliver to caller
dofiles:
let c=0
?
? "\W"
? "\t ", z, " [", n, " view(s)]"
? "\w 0 0 9600 7200 1"
let g="f:\fs\weather\"%f
findfirst a,g
loop1:
let c=c+1
ifval n=1 goto nonext
? "\t &Next (",c," of ",n,")"
? "\m 1600 0 1600 400 0 N"
nonext:
? "\t E&xit"
? "\m 0 0 1600 400 0 ^M"
if a="" goto nofiles
let x="copy f:\fs\weather\"%a%" demand.bm$ >nul"
shell x
? "\X DEMAND.bm$ 0 0 1"
let x = "VXY " % !12 % " -YS DEMAND.bm$"
shell x
delay 1
rc a
if a<>"N" goto nofiles
findnext a
?
goto loop1
nofiles:
?
? "\W"
return

         Note: The above example specifies a number of .BM$ files
         which are assumed to be already existing at f:\fs\weather.
         Also, notice that the file is copied to DEMAND.BM$ before
         transmission; this is so that each successive DEMAND.BM$
         overwrites the previous, and the weather maps do not
         "pile up" on a user's system.  If you wanted to save
         the pictures on the user's hard drive so that they could
         review it later, offline with a BMP viewer, we'd replace
         the following segment:

let x="copy f:\fs\weather\"%a%" demand.bm$ >nul"
shell x
? "\X DEMAND.bm$ 0 0 1"
let x = "VXY " % !12 % " -YS DEMAND.bm$"
shell x
delay 1

         with:

let x="copy f:\fs\weather\"%a%" "%a%" >nul"
shell x
? "\X ",a," 0 0 1"
let x = "VXY " % !12 % " -YS "%a
shell x
delay 1

         For an example batch file showing how to convert from
         a different format and then compress the BMP with PAK.EXE,
         see the following chapter.


         PAK.EXE, BMP FILES, WAV FILES
         ═════════════════════════════

                PAK.EXE is a single-file compression/decompression
         utility program.  It operates on a command line basis:

         PAK c <infile> <outfile>

              Compress the contents of <infile>, yielding <outfile>.

         PAK d <infile> <outfile>

              Decompress the contents of <infile>, yielding <outfile>.

         PAK.EXE does not make any assumptions about filename extensions,
         so make sure you include extensions.  PAK was mainly designed
         to be used in conjunction with VWC, as it yields excellent
         compression ratios with .BMPs and .WAVs -- two items that VWC
         can work with, although there are bound to be other uses.

         Examples for using PAK.EXE with VWC are as follows:

         For BMP Files:

           PAK c filename.bmp filename.bm$

         For WAV Files:

           PAK c filename.wav filename.wa$

         Note the $ on the end of the output filename.  When VWC
         receives this file as part of a \x or \X transfer, it
         will automatically call upon the VWC-included version
         of PAK.EXE to decompress the .BM$ to .BMP and .WA$ to
         .WAV before trying to make use of the file.

                The only type of accepted BMP files for use with
         VWC are Standard BMP files, and another type called
         compressed BMP files (has nothing to do with PAK.EXE).

         If the source data you have is in a different format, you
         can get a shareware program to convert whatever you have
         into stardard or compressed bitmaps.  From there, you can
         you PAK.EXE to compress a standard or compressed bitmap
         even further.  Ratios of 4:1 to 10:1 are not uncommon.

         One such shareware program is called Image Alchemy.

         Here is an example from an actual batch file I used
         to use with Planet Connect to make the weather maps
         available to VWC callers.  The batch file would run
         as an event. The weather map data file would come in as
         WEATHER.ARC (even though it was ZIPed).  Inside each
          ZIP was several PCX format graphic. Comments have been
         added:

         'Check to see if new weather file received
         if not exist z:\weather\weathmap.arc goto nosat

         'If so, copy it to a storage area
         copy z:\weather\weathmap.arc f:\fs\weather >nul

         'And delete the copy from the Planet Connect computer
         del z:\weather\weathmap.arc

         'Unzip it to get the PCX files out (unzip is an OS2 util)
         'DOS users instead use:
         'pkunzip f:\fs\weather\weathmap.arc f:\fs\weather
         unzip -j f:\fs\weather\weathmap.arc -d f:\fs\weather

         'Convert the PCX files (about 200k) to compressed .BMP files
         '(about 40k)
         alchemy f:\fs\weather\*.pcx f:\fs\weather -o -w -p1

         'Delete the PCX files
         del f:\fs\weather\*.pcx

         :nosat
         'Check to see if any files need PAKing
         if not exist f:\fs\weather\*.bmp goto nobmp

         'Do a rename from .BMP to .BM
         ren f:\fs\weather\*.bmp *.bm

         'PAK each .BM file to .BM$
         for %%i in (f:\fs\weather\*.bm) do pak c %%i %%i$

         'Delete the .BM files
         del f:\fs\weather\*.bm

         :nobmp

         After the batch file executes, all unneeded files have
         been cleaned up, and what is leftover is the original
         WEATHER.ARC (so you can let non-VWC use download it and
         view offline), and the .BM$ files which are now ready
         for transmission to VWC as needed by a Virtual Advanced
         script.  The resultant .BM$ files are in the 8k to
         20k size range -- they transmit quickly, efficiently.

         Considering that the original PCX file may have
         been 160k to 200k in size, that is an awesome amount
         of overall data compression without any lossiness.

                Use PAK.EXE to compress WAV files also.  When selecting
         and/or creating WAV files, bear in mind that higher sampling
         rates, and/or use of stereo over mono will have a direct
         bearing on file size, and that not all sound cards have the
         exact same capabilities.