
                              Bbs2Web Version 1.03
                Html Web Page Generator for Maximus BBS Systems
                                4th October 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. This is the first public release version. I've
    no distinct plans for the program, other than continued usage on
    my own system. Some people have expressed an interest in the
    program, and given the value of public beta testing, I'm releasing
    this version to that end. 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 CONNECT recommended. OS/2 V2.1 and WARP
    would also require TCP/IP V2 with the suitable CSD's installed.

    2) An active realtime 24hr internet link. The author operates via
    a dedicated V34 modem link, anything as fast or faster would do
    fine.

    3) An OS/2 httpd server. IBM Internet Connection Server 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. After some evidence of international download corruption
    via the httpd server, the author installed Penguin Software's
    Penftpd as the file server.

    5) An active and working Maximus V3.xx OS/2 BBS file base. Maximus
    is the most popular OS/2 BBS package currently available, with by
    now many years of solid development behind it.



    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



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

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

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

    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.

    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.

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

    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.

    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.

    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 to the corresponding
    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 can be placed in the OS/2 system CONFIG.SYS file, or
    alternatively somewhere within the Web server's task before it's
    execution.

    Here's an example command file for server execution, in this case
    Apache for OS/2;

    RUNWWW.CMD
    
    @Echo off
    SET BBS2WEB_INI=f:\bin\bbs2web.ini
    f:
    cd \www
    \www\bin\httpd.exe -f /www/conf/httpd.conf -d /www/docs
    

    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.



    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.

    

