
CAB OVL 1.42 NOTES

current release version 1.4200

For better documentation refer to either the HYP or HTML format docs.

What is it?

     CAB.OVL is a networking interface layer for use with CAB.  This release
is compatible with any STiK conforming TCP_IP layer, which meets the STiK 
standards.

CAB_OVL now comes in 2 flavors *again* they can be found in the
     respective folders in this archive.

     - CAB_OVL Any 68000 machine

     - CAB_OVL.030 Optimised for 68030 machines (Falcon,TT,etc.)

**** NOTE : You can not use the 030 compiled version of the CAB_OVL on a 
          normal ST/e/fm,MegaST/e *****


Foreward:

     Many changes are in place and more are on the way.  Enjoy!

Newest version can be found at:

     http://www.netset.com/~baldrick/

NEW THIS RELEASE (Since last FULL release - oldest first)

		- Modified POST to check URI, CAB doesn't like a form without an "action"
	It does give an acceptable standard response to this that is easily catchable.
		
		This enables some problematic sites to work properly with my OVL.

NEW LAST (FULL) RELEASE:
		
     - patch to POST
     - SMTP patches
     - Cookie routine patches
     - authorization attempts max reworked
     - changed fake netscape version to 4.73
     - increased URL cache to 10 (was 4)
     - New CFG variable POSTGET 
         - if 0 prompt user for redirection
         - if 1 always do a get
     - process chunk completely rewritten
     - Now states HTTP 1.1
     - handles continue code (100)

How to use PUT (and/or what is it)?

     PUT is the http method for uploading files.  Not all servers support
     it.  In fact many have this turned off.  However there are still a large
     number of sites that do allow it.  If you are lucky enough to have one
     as your web site it can save you a bit of time launching seperate 
     applications.  Simply "test" your page in CAB and if you like it, "PUT"
     it up to your web site.

     How to use PUT.  Go into the open url dialog.  Now type "put http://www.
     mywebsite.com/~me/file_to_upload".  You must put "put http" or "PUT HTTP",
     this is what the CAB.OVL scans for to use this function.  And this is 
     a process that's all done on the OVL side.  CAB goes along with it kicking
     and screaming ;)

     After setting this command in the "Open URL" box, you will be presented
     with a file selector.  If you select a file that file will be sent to your
     web server.  The file you select need not be named the same as what you
     typed into the "Open URL" dialog.  example you could type:
     "put http://www.mysite.org/~me/cool.zip", but the file you select to
     send might be named "a49zb.zip".  On the web server it will be named
     "cool.zip".

     If you web server supports PUT, the file "file_to_upload" (insert your file
     name in place of this) will be stored in your web directory.  If your
     server does not support PUT, you will be prompted with a "Method not allowed"
     form alert.

     If you are using the POST variant (egroups does this), then you will
     simply be presented with a fileselector after filling out the form on
     the web page.  In all other respects the variant behaves the same as the
     PUT method above.

Known problems still existing:

     If you can not use some of CAB's modules with this CAB.OVL try editing your
     STiNG default.cfg.  STiNG sets several entries that actually cause compatibility
     problems with the CAB.OVL and CAB. These entries are for email etc.

     Some users still have problems with email headers,  I'm waiting on more debug 
     info back from beta testers on this.  This is working fine for me and many others
     though so hopefully you'll be lucky ;)  You can verify if it's working for you,
     by setting up a mailto link to yourself or use on of a friends and have them look 
     at what is sent. (I'm not certain if this still exists or not, all feedback
     on this subject has ceased)

     Some users also are having problems downloading multiple binary files from a site.
     However it's not a consistent problem. (This appears to be gone)

     Some forms are exhibiting problems.  These seem at the moment to be CAB errors,
     and as soon as Alex can get to these sites we will find out. (The ones that are
     left appear to be CAB problems)

     Users of CAB 1.5 may notice 'image' notifications in the status bar of
     CAB when retrieving pages, even if the images are disabled.  I think
     this has to do with a newer CAB call.  However beyond it showing up on
     the screen it apparently has no bad effects.

     If you can not check your Hotlist with the CAB Module, then try moving
     the CAB.OVL into the Modules directory.  This should fix the problem.

Variables CAB_OVL uses:

     These are set in the default.cfg or with an appropriate program
          that modifies STiK variables.

     1. EMAIL - format "EMAIL = me@myhost.com"

          This is the address where you would like any mail sent
     with the CAB.OVL to be addressed from.  Not all mail servers
     will send mail with an incorrect email address or a non local
     email address.

     2. USERNAME - format "USERNAME = mylogin_name"

          This is used by CAB.OVL in conjunction with HOSTNAME, to
     attempt to create an email address, if the variable EMAIL is not
     present.  This is also used in conjunction with authentication
     in PPP so this needs to be correct. (note PPP will be available in 
     STiK 2)

     3. HOSTNAME - format "HOSTNAME = myhost.com"

          This is used with USERNAME in the event that EMAIL is not
     present to construct an email address for you.

     4. SMTP_HOST - format "SMTP_HOST = mail.myhost.com"

          * NOTE: You can now also use SMTP_SERVER, which is actually
               a preferable name

          CAB.OVL needs this if you want to send mail with it while
     cruising the web.  It must be a valid SMTP mail host.  Some hosts
     will not allow mail to be sent through them, if this is the case
     contact your ISP for an alternate mail host.

     5. HTTP_PROXY - format "HTTP_PROXY = proxy.www.cache.com"

          Used in conjunction with HTTP_PROXY_PORT for getting web documents
     from a local cache as opposed to the original remote host.  This cache
     is not the normal CAB CACHE on your machine, but a similar structure on 
     a remote machine.  Many large ISP's supply these (ex. Demon in the UK) 
     and many Universities require them to gain access to the web at all.

     6. HTTP_PROXY_PORT - format "HTTP_PROXY_PORT = 8080"

          Used in conjunction with HTTP_PROXY, for retrieving web documents
     from a remote cache.  If your ISP supplies an HTTP proxy, you can get
     the info for the name and port from them.

     7. NNTP_PROXY - format "NNTP_PROXY = newsproxy.myhost.org"

          * Note:  Has anyone actually seen one of these ?

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     8. NNTP_PROXY_PORT - format "NNTP_PROXY_PORT = 8080"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     9. NNTP_HOST - format "NNTP_HOST = news.myhost.org"

          * NOTE: You can now also use NNTP_SERVER, which is actually
               a preferable name.

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     10. FTP_PROXY - format "FTP_PROXY = ftp.myhost.org"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     11. FTP_PROXY_PORT - format "FTP_PROXY_PORT = 8080"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     12. GOPHER_PROXY - format "GOPHER_PROXY = gopher.myhost.org"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     13. GOPHER_PROXY_PORT - format "GOPHER_PROXY_PORT = 8080"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     14. WAIS_PROXY - format "WAIS_PROXY = wais.myhost.org"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     15. WAIS_PROXY_PORT - format "WAIS_PROXY_PORT = 8080"

          This is not directly used by CAB.OVL, but is supplied to CAB at boot
     time.

     16. SMTP_SERVER - format "SMTP_SERVER = mail.myhost.com"
     
          CAB.OVL will use this to send mail through the internet.
          Must be a valid SMTP server name.
     
     17. NNTP_SERVER - format "NNTP_SERVER = news.myhost.com" 
     
        CAB.OVL will use this for retrieving mail.  Note.  Currently
        this will only be passed to an external NNTP client.

     (Quite a few eh? Bet you didn't know all that was there ;)

Errors CAB reports:

          There are 4 types of errors you might encounter during the use of CAB, 
     with this CAB.OVL.

          1. Serious errors - These are crashes, bombs, Magic's infamous 
     error -69, and others of this type.  Unfortunately you will find no more
     usefull information about these here.

          2. CAB intercepted errors - These are the infamous "Runtime error at
     Offset xxx" errors.  These might be in CAB or the CAB.OVL or some conjuntion
     between the two.  If anyone has a copy of the error reports for Pure Pascal
     please send me a copy, as currently I have no idea what any of them actually
     mean.

          3. STiK errors - Such as Krmalloc - memory corruption detected.  

          4. CAB/CAB.OVL network error reports - These I can give you more info on.
     When they occur in a compatible CAB they will appear in the status line.

 CAB/CAB.OVL network error definitions:

    #-1   - No Connection or similar error.  This shouldn't appear normally under STiK.

    #-36  - Connection Failed.  The site may be too far away, or network
               trafic to high at the current time.

    #-39  - No memory.  Requested action can't be preformed as STiK is out of memory.

    #-65  - Bad SYN.  This is another error you shouldn't encounter.  But might pop up.

    #-300 - Bad Connection handle.  The OVL has gotten confused somewhere and is trying
               to use a non existant connection.  You shouldn't encounter this.

    #-307 - No name server.  CAB.OVL can't function as it can't resolve any sites, due
               to the lack of a nameserver.  This is a misconfiguration of STiK, or
               a STiK corruption problem.

    #-308 - Bad DNS format.  CAB.OVL can't resolve the site with the given site name.

    #-311 - This is a general purpose network error.  Due to some problem with the site
               name, CAB.OVL can't retrieve the requested URL.

    #-312 - Network Down - Lost Carrier.  You are no longer connected to the network.

    #-313 - The site is unreachable.  It's offline or you are or both. This
               also happens during high net trafic when it is impossible
               to get a connection to the site.

    #-314 - The other end has sent an unacceptable packet, we are forcing
               a reset.

    #-315 - Abort due to user action. 
          This should only occur in one of the following 3 circumstances.

               1. You have pressed the STOP button.

               2. You have pressed the 'esc' key.

               3. The current routine has timed out. 

          *Note there is also a bad mapping onto this error that show's
               an internal STiK error*

    #-316 - The other end has forced a reset on the connection, closing it.

    #-318 - CAB.OVL is trying to preform an action on a closed socket.

    #-320 - The connection has timed out and closed.

    #-321 - The other end has refused to allow you to retrieve the document.
               This can occur on pages with authentication or with sites that
               do not allow non-local connections (or conections from too far
               away ie. another continent)  This could also happen when accessing
               the web through a proxy, that also acts as a firewall.

    #-323 - Resolver has reached it's work limit.  The CAB.OVL cannot 
               resolve the host for the specific document as it's just too
               far away/deep for it to get the address.

    #-600 - CAB.OVL can not resolve the host for the specified document.
               When this happens the CAB.OVL will attempt to see if you are 
               still online.  If it can not determine your online status,
               it will prompt the user to "Abort", if the user chooses 'YES',
               then CAB.OVL assumes it is offline and informs CAB of this status.
               If the user chooses 'NO', then CAB assumes it is still online and
               just couldn't resolve the current site.
     
  The CAB.OVL now processes and reports normal GEM errors that it encounters during
      it's operation.
      
CABOVL.CFG file

# CAB.OVL for STiK Config File
#
# Lines started with # are Remarks
#
# FAKE_NETSCAPE
# 1 - Fake a mozilla entry as the browser
# anything else remain normal CAB.OVL entry
# Default value is off, normal CAB.OVL entry
#
FAKE_NETSCAPE = 1
#
# SHARE_TIME
#  amount of time in msec that the OVL returns to CAB during the OVL's
#  operation.  Like all GEM calls this is the minimum time returned.
#  It's Default value is 100 msec
#
SHARE_TIME = 20
#
# ONLINE
# determines how the CAB.OVL will work with you on determining it's
# online status, if it's unable to.
#
# 0 - 'Always Online' - The OVL relies entirely upon the errors returned
#         from the stack to determine online/offline status.  It will
#         never question you as to it's status or attempt to determine
#         it's online status.
#
# 1 - 'Use Abort Alert' - If you are having problems with with the CAB.OVL,
#         when it is launched by CAB, try using this setting.  CAB.OVL
#         will attempt to determine it's online/offline status by using
#         routines in the TCPIP stack. If it's unable to determine it's
#         status, you will be prompted with the 'Abort' alert.  If you
#         answer 'Yes' you are online, if you answer 'No' you are offline.
#         Not pretty but hopefully will get around a problem call on 
#         systems that are experiencing this bug.
#
# 2 - 'Use Online Alert' (This is the default value if ONLINE is not set)
#         If the CAB.OVL can not determine it's online/offline status
#         It will prompt you with 'Online?'.  Answer 'Yes' if you are
#         and 'No' if you are not.
#
#    Using value 1 or 2 is preferable to 0 if you can in your situation,
# as there are some errors that are not 100% black and white, knowing it's
# status helps the OVL determine what actions to take in certain situations.
#
ONLINE = 2
#
# TIMEOUT
# amount of time in seconds that you wish to wait before time out's occur on
# connections
#
# Default is 120
#
# **** WARNING **** Do not make this value too small
#
TIMEOUT = 120
#
# POSTGET
# determines how the CAB.OVL handles redirections after a POST
#
# 0 - Prompt user to decide to GET, POST or Cancel
# 1 - GET the resulting file
#
POSTGET = 1