
                              Bbs2Web Version 1.07
                Html Web Page Generator for Maximus BBS Systems
                               3rd November 1996

         (C) Copyright 1996 by CodeLand Australia, All Rights Reserved
                             Written by Colin Wheat

                               colinw@ami.com.au
                             http://www.ami.com.au
                              ftp://ftp.ami.com.au
                              3:690/613.0@fidonet



    INTRODUCTION
    
    Bbs2Web is a simple web page generator for an OS/2 Maximus BBS
    system's file base. If it works for you, that's great. If not than
    I'm interested in hearing about it. I can't promise fixes or ongoing
    support, but assuming your problem may also turn up here on my
    system, it's possible I'll fix it for a subsequent version.

    As usual with Shareware and Freeware releases, there are no
    guarantees with this software. User beware, use it at your own risk.



    REQUIREMENTS
    
    1) OS/2 2.1 or above, WARP V4 (Merlin) recommended. OS/2 V2.1 and
    WARP would also require TCP/IP V2 with the suitable CSD's
    installed.

    2) An HPFS partition to hold the generated output *.html files.
    Bbs2Web supports the nested Maximus V3.XX file area groups. For
    nested area output, files with long file names will be generated.
    E.g. "Os2.Network.Tcpip.Html". This is a design feature which
    cannot be changed.

    3) An OS/2 httpd (WEB) server. IBM Internet Connection Server
    (ICS) is highly recommended.

    4) A suitable server for file serving. Files can be served by the
    httpd server, but you may prefer to install an ftpd server for the
    purpose.

    5) An active and working Maximus V3.XX OS/2 BBS file base. Maximus
    is the most popular OS/2 BBS package available. Note that it may
    be possible to modify a Max V2.xx system to successfully support
    Bbs2Web operation.

    6) An active realtime 24hr internet link. The author operates via
    a dedicated V34 modem link, anything as fast or faster would do
    fine. Note that for intranet operation this is not requirement.



    FEATURE SUMMARY
    
    Bbs2Web generates a full set of Web pages representing a Maximus
    V3.xx file base. It includes support for file groups by building
    nested pages. CDROM file areas are supported, and can be excluded
    from the output pages. Download links are automatically placed in
    the output pages for every listed file. Files can be downloaded by a
    suitable server, usually either httpd or ftpd. This is controlled by
    the configuration file FileLinkPath statement. File areas can be
    excluded from the output by priviledge setting, using the
    configuration file ListPrivBelow statement. Bbs2Web also includes a
    file base search engine, MaxFind.Exe. All generated pages include a
    file name search entry form and a matching call to MaxFind.Exe via
    the Search button. MaxFind.Exe should be copied to your web server's
    cgi-bin sub-directory. Note that MaxFind.Exe also -needs- an
    environment variable set, to allow it to find the configuration
    file.

    MaxFind.Exe environment variable setting example:
    SET BBS2WEB_INI=f:\bin\bbs2web.ini



    DISTRIBUTION FILES
    
    BBS2WEB.EXE     -   The Web page compiler
    BBS2WEB.INI     -   Compiler configuration text file
    MAXFIND.EXE     -   The Maximus 3.XX file base search engine
    BBS2WEB.TXT     -   This documentation
    INDEX.HTM       -   Example Bbs2Web generated Web page from the
                        author's system
    BBS2WEB.GIF     -   Example background image for generated pages
    MASTBBS.GIF     -   Example masthead image for generated pages



    THE CONTROL FILE BBS2WEB.INI
    
    [BBS2WEB]
    Denotes the start of data within the configuration file. Data is
    read from the configuration file beginning from the line following
    the [BBS2WEB] entry, and continues until a token beginning with a
    '[' character (e.g. [END]).

    ;-MAXIMUS--------------------------------------------------

    MaxPath=F:\Bbs
    The Maximus directory. Several files are assumed to exist in this
    directory, including Farea.Dat and Maxfiles.Idx.

    AreaDatFile=Farea.Dat
    The name of the Maximus V3.xx file area data file, usually found
    in the Maximus directory. Bbs2Web will look for this file at the
    MaxPath path, see below.

    IncludeCdrom=Yes
    A flag to control the including or excluding of CDROM file areas
    for the output pages.

    ListPrivBelow=Extra
    File areas will only be included in the output pages when holding
    a priviledge less than the ListPrivBelow setting. File area
    priviledge levels are set in your Maximus FIlearea.Ctl control
    file. Note that Bbs2Web currently has NO support for override
    locks and levels.

    ListKeyAreas=No
    Bbs2Web supports only the standard Maximus priviledge levels, and
    does not support extended priviledges. "Normal" is a valid
    priviledge verb, "Normal/1" (note the Key extension) is not.
    Unknown priviledge strings are assigned a "Hidden" (65535)
    priviledge value so that such areas will not appear in the
    generated output. ListKeyAreas=No is the default operation.
    ListKeyAreas=Yes instructs Bbs2Web to trim "/" extensions from
    priviledge strings prior to further processing. This would for
    example convert "Normal/1" to "Normal" thus allowing areas thus
    marked to appear in the output listings. The effect is to ignore
    Key extensions in your file areas.

    ;-HTML CONTENT---------------------------------------------

    BackGroundImage=/bbs/Bbs2Web.Gif
    An optional page background bitmap image, used on all output
    pages.

    HtmlTitle=The_Library_Network_BBS
    The Web page system title. Underscore characters are converted to
    space characters.

    HtmlMast=/bbs/MastBbs.Gif
    An optional masthead image, that replaces the HtmlTitle heading on
    generated pages.

    HtmlHeading=BBS_File_Areas
    The Web page sub-heading. Underscore characters are converted to
    space characters.

    ReturnLinkTitle=The_Library_Network
    The title for a link pointing the browsing user back to your site
    home page or equivalent. Underscore characters are converted to
    space characters.

    ReturnLinkPath=http://www.ami.com.au/
    A link entry for the master Web page, pointing the browsing user
    back to your site home page or equivalent.

    NoSearch=No
    Bbs2Web defaults to adding a search form to every generated page.
    NoSearch=Yes disables the search form, Bbs2Web does not include
    the form on generated pages.

    CgiSrvrPath=http://www.ami.com.au/cgi-bin/maxfind.exe
    The CGI search engine full URL path and name.

    ;-HTML GENERATION------------------------------------------

    HtmlFile=index.html
    The name of the generated master Web page. All other pages are
    linked from this page, or from pages linked from this page,
    recursively.

    HtmlPath=f:\bbs\html\
    The path for the generated Web page files. You should create a
    sub-directory for this purpose. On the author's system, the
    Bbs2Web output Web pages total 438 files and !6.2 Megabytes of
    text/html data files.

    FileLinkPath=ftp://bbs.ami.com.au/pub/
    The file download link path. Bbs file paths and names will be
    appended to this entry, for creation of the on page download link.
    You can send the files to the user via various servers, including
    httpd, and ftpd. Here's an example for a httpd served file for the
    author's system; "http://bbs.ami.com.au/pub/". Note that you'll
    need to setup your server to allow access to the file base.
    Bbs2Web filters out drive names from the Maximus supplied file
    download paths. See also the MapDrive command.

    MapDrive=j: /hobbes1/
    Multiple MapDrive verbs can be listed, to a maximum of 16. Bbs2Web
    will convert a MapDrive listed drive letter or initial path to the
    supplied path, for the output page links. This is probably a
    required function for most systems. I've not considered the
    situation in depth, only that it's required here. Let me know if
    you're unable to fully serve your file base with the existing
    Bbs2Web features.

    [END]
    Denotes the end of Bbs2Web data within the control file. This verb
    is optional, end of file will also terminate control file data
    loading.



    FILE SERVING
    
    Setting up the file server and arranging for Bbs2Web to correctly
    build working file links in the output pages, is probably the
    largest part of the Bbs2Web installation task. :) I've attempted
    to clearly explain the control file verbs usage above, with the
    verbs FileLinkPath and MapDrive both directly affecting file serving.
    Rather than attempting an in depth discussion, I'll now provide an
    example of the working setup here, the environment in which and
    for which Bbs2Web was written.

    Bbs2Web finds the Maximus files by firstly reading the Farea.Dat
    file in the Maximus directory. From this file it's able to build a
    list of downloadable file areas.

    Here's one of the Maximus file areas on the system here, as
    represented in Filearea.Ctl. Farea.Dat is compiled from
    Filearea.Ctl, subject to specific Maximus configuration.

    FILEAREA LOCAL
            ACS             Disgrace
            DESC            System Utilities & Information
            DOWNLOAD        H:\General\Newuser
            UPLOAD          H:\Upload
            % FILELIST        <file>
            % OVERRIDE        FILE File_Download Normal
            % TYPE            <Slow> <Staged> <NoNew> <CD>
            % MENUNAME        <OldName> <NewName>
    END FILEAREA

    The relevant entry is the file download path,
    "H:\General\Newuser".

    Having build a list of downloadable file areas, Bbs2Web accesses
    the data files (FILES.IDX/DAT/DMP) within each directory, to
    compile and generate the output Web pages. A Maximus V3.xx system
    uses the FILES.BBS text file as the master for the directory
    listing, so you'll want to run the file base compiler (fbp)
    -before- Bbs2Web is run, usually during nightly maintenance. We're
    ignoring CDROM areas in this simple explanation, for those areas
    the data files are actually found on the FILELIST path.

    So far that's not too difficult :). The problems begin to appear
    though when attempting to build a working download file link for
    each listed file. From the example above, we have a Maximus
    supplied path of "H:\General\Newuser". On the system here, I use
    the Toronto File System (TVFS) to build a ftp downloadable single
    drive representation of the complete BBS file base, itself spread
    across multiple server drives. The corresponding TVFS path is;
    "T:\pub\general\newuser". The ftp server is setup with a home
    directory of "T:\", so that a base ftp login shows the "\pub"
    directory available from root.

    For any one file from our example directory, say "LIBRARY.LZH",
    using a Bbs2Web FileLinkPath of "ftp://bbs.ami.com.au/pub/", and a
    file area path from Maximus of "/General/Newuser" (Bbs2Web
    converts '\' characters to '/' for the purpose of link creation),
    the resulting Web page listed file link becomes
    "ftp://bbs.ami.com.au/pub/general/newuser/LIBRARY.LZH".

    The MapDrive verb becomes useful (essential) for Maximus file
    paths that are mapped back to the one virtual drive for server
    usages such as ftp. As a short example; a CDROM file on the BBS
    has a path of "J:\Bbs\MAX300C.ZIP". For ftp server usage, that
    path is mapped by TVFS to "T:\pub\hobbes1\bbs\MAX300C.ZIP". With a
    MapDrive setting of "MapDrive=j: /hobbes1/" and by converting the
    '\' characters to '/' characters, the file path becomes
    "/hobbes1/Bbs/MAX300C.ZIP". With the addition of the FileLinkPath
    setting, the full file link is
    "ftp://bbs.ami.com.au/pub/hobbes1/Bbs/MAX300C.ZIP".



    THE SEARCH ENGINE
    
    The search engine MaxFind is a html CGI server utility. It should
    be moved to your Web server cgi-bin directory. Standard cgi usage
    uses program command line and stdout for remote communication, so
    configuration information is usualy passed via environment
    variables. In fact the Web server also passes the user's search
    request data to MaxFind via environment variables in this case.
    MaxFind uses methods and code similar to Bbs2Web to access the
    Maximus file bases. It's able to operate soley on the information
    contained within Bbs2Web.Ini. The one configuration requirement
    then, is to pass it the full path and name of the Bbs2Web.Ini
    configuration file. This is accomplished by the BBS2WEB_INI
    environment variable.

    e.g. SET BBS2WEB_INI=f:\bin\bbs2web.ini

    This must be placed in the OS/2 system CONFIG.SYS file.

    Technically, MaxFind uses a sub-string single key search, across
    all BBS listed file bases. This may be subject to enhancement in
    later versions of the program. Access restrictions identical to
    Bbs2Web apply to the resulting output.



    VERSION CHANGES
    
    V1.00 - Released 96-03-24.
            The initial public release.

    V1.03 - Released 96-10-04.
            Minor code changes and bug fixes. Fixed a problem with
            html tokens in the file description fields, where too
            many '<' or '&' characters in the description field would
            overflow allocated storage.

    V1.04 - Released 96-10-09.
            Modified the MapDrive INI verb to support a partial path.
            The original design supported only drive letters. Changed
            the Maximus file area access support to allow and use the
            new Max V3 verbs. Bbs2Web was using the old V2 verbs
            (Twit) etc. Opps.

    V1.05 - Released 96-10-10.
            Added a new INI verb, CgiSrvrPath. CgiSrvrPath supplies
            the full URL path and name of the CGI search engine,
            usually MaxFind.Exe. Previously the search engine path was
            generated from the ReturnLinkPath URL.

    V1.06 - Released 96-10-29.
            Adjusted the area priviledge verb lookup function, to
            correctly supply caller nominated default responses for
            unknown verbs. Bbs2Web does not yet support keys in the
            privil verbs, so that an access level of "Normal/1" is an
            unknown verb. Bbs2Web will now set area/file priviledge
            levels to HIDDEN for unknown verbs, and the INI's
            ListPrivBelow setting to TRANSIENT for unknown privil verbs.
            This should stop Bbs2Web displaying files or areas which
            have unknown privil levels attached.

            Added new INI verb, "ListKeyAreas". ListKeyAreas defaults
            to off (No). When activated (ListKeyAreas=Yes), ListKeyAreas
            will instruct Bbs2Web to mask all key additions to priviledge
            strings. E.g. "Normal/1" would be translated to "Normal".
            The default action (ListKeyAreas=No) is to use privil
            verbs as supplied, and Bbs2Web does NOT support keys.

            Added a new INI verb, "BackGroundImage". E.g.
            BackGroundImage=/bbs/Bbs2Web.Gif
            BackGroundImage activates a background image file for
            the Bbs2Web generated html pages. The image file should
            be copied to a server accessable path, and a matching
            URL listed with the BackGroundImage verb. On the author's
            system the image file exists in the html output directory.
            Note that the background image is used by both Bbs2Web and
            MaxFind.Exe. BBS2WEB.GIF was also added to the distribution
            archive.

    V1.07 - Released 96-11-03.
            Fixed a problem with MaxFind, concerning string termination
            for the file name field within the FIDX structure used by
            MAXFILES.IDX. This should fix some problems with the
            search engine.

            Add new INI verb, NoSearch. With NoSearch=Yes, Bbs2Web
            does not include the search form on the generated html
            pages.

            Added new INI verb, HtmlMast. HtmlMast supplies the URL of
            and optional page masthead image. This replaces the
            HtmlTitle heading. Example: HtmlMast=/bbs/MastBbs.Gif

            Fixed a problem with priviledge value comparisons.
            Priviledge values are now stored as unsigned values.



    FEEDBACK
    
    Mail me a note at colinw@ami.com.au if you've found Bbs2Web useful
    on your system, or if you find problems with it's usage. Call by
    http://www.ami.com.au/bbs to see a working example.

    My interest at this time especially, is to use and push OS/2 to
    the limit with internet and tcp/ip usage. OS/2 is indeed an
    excellent product :). IBM's years of OS/2 support and development
    are bound to have major repercussions into the next decade, the
    writing is on the wall. This especially true now in the
    home/office and consumer markets, given MS's dismal longterm
    performance in the OS arena, not the least recently with the
    slightly sad and disappointing WIN3.XX upgrade, the predominately
    16bit WIN95. With MS's own product life projection of 3yrs or
    less, Win95 has NO future even now shortly after it's (much
    belated) launch. With the need for stable 32bit OS's for the lead
    into the next centuary, OS/2 and it's future relatives are looking
    increasingly inviting to a great many people. If you haven't yet
    tasted real 32bit power on your desktop, run don't walk to your
    local OS/2 specialist and order your copy of the future now :).

    For Australian residents; Amisoft Computers can supply all your
    OS/2 hardware and software needs. Call them at (09) 293-3278
    regarding your requirements..

    IBM OS/2 WARP V4.0 (Upgrade Version) $199.00
    IBM OS/2 WARP V4.0 (FullPack Version) $299.00

    Regards,
    Colin Wheat.

    

