README.EBCDIC

This version of Apache comes with a first-cut (working, but not
fully tested) port to a mainframe machine which uses the EBCDIC
character set as its native codeset (It is the SIEMENS NIXDORF
family of mainframes running the BS2000 operating system. This
mainframe OS nowadays features a SVR4-like POSIX subsystem).

The port was started initially to
- prove the feasibility
- find a "worthy and capable" successor for the CERN daemon (which
  was ported a couple of years ago), and to
- prove that Apache's preforking process model can on this platform
  easily outperform the accept-fork-serve model used by CERN by a
  factor of 5 or more.

This document serves as a rationale to describe some of the design
decisions of the port to this machine.

* The relevant changes in the source are #ifdef'ed into two
  categories:
  #ifdef CHARSET_EBCDIC     Code which is needed for any EBCDIC
			    based machine
  #ifdef _OSD_POSIX         Code which is needed for the BS2000
			    SIEMENS NIXDORF mainframe platform only.

* The possibility to translate between ASCII and EBCDIC at the
  socket level (on BS2000 POSIX, there is a socket option which
  supports this) was intentionally not chosen, because the byte
  stream at the HTTP protocol level consists of a mixture of
  protocol related strings and non-protocol related raw file data.
  HTTP protocol strings are always encoded in ASCII (the GET
  request, any Header: lines, the chunking information etc.) whereas
  the file transfer parts (i.e., GIF images, CGI output etc.) should
  usually be just "passed thru" by the server. This separation
  between "protocol string" and "raw data" is reflected in the
  server code by functions like bgets() or rvputs() for strings, and
  functions like bwrite() for binary data. A global translation of
  everything would therefore be inadequate.
  (In the case of text files of course, provisions must be made so
  that the documents are always served in ASCII format)

* This port therefore features a built-in protocol level conversion
  for the server-internal strings (which the compiler translated to
  EBCDIC strings) and server-generated documents. The hard coded
  ASCII escapes \012 and \015 which are ubiquitious in the server
  code are an exception: they are not converted to ASCII a second
  time.

* For Text documents (MIME types text/plain, text/html etc.), an
  implicit translation to ASCII can be used, or (if the users prefer
  to store some documents in raw ASCII form for faster serving) can
  be served without conversion.
  Example:
      to serve files with the suffix .ahtml as a raw ASCII text/html
      document (and suffix .ascii as ASCII text/plain), use the
      directives:
    AddType  text/x-ascii-html  .ahtml
    AddType  text/x-ascii-plain .ascii
  Similarly, any text/XXXX MIME type can be served as "raw ASCII" by
  configuring a MIME type "text/x-ascii-XXXX" for it using AddType.

* Non-text documents are always served "binary" without conversion.
  This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU
  file types. This of course requires the user to copy them to the
  mainframe host using the "rcp -b" binary switch.

* Server parsed files are always assumed to be in native (i.e.,
  EBCDIC) format as used on the machine, and are converted after
  processing.

* For CGI output, the CGI script determines whether a conversion is
  needed or not: by setting the appropriate Content-Type, text files
  can be converted, or GIF output can be passed through unmodified.
  An example for the latter case is the wwwcount program which we ported
  as well.

What works:
- In the following list,
    + means: works, tested
    - means: doesn't work for some reason
    ? means: compiled-in, but untested

  http_core.c           +
  mod_access.c          +
  mod_actions.c         ?
  mod_alias.c           +
  mod_asis.c            ?
  mod_auth.c            +
  mod_auth_anon.c       +
  mod_auth_db.c         - / no libdb
  mod_auth_dbm.c        - / no libdbm
  mod_autoindex.c       +
  mod_cern_meta.c       ?
  mod_cgi.c             +
  mod_digest.c          - / MD5 not ported yet
  mod_dir.c             +
  mod_dld.c             - / no shared libs
  mod_env.c             +
  mod_example.c         - / not tried yet
  mod_expires.c         +
  mod_headers.c         +
  mod_imap.c            +
  mod_include.c         +
  mod_info.c            + / some flaws
  mod_log_agent.c       +
  mod_log_config.c      +
  mod_log_referer.c     +
  mod_mime.c            +
  mod_mime_magic.c      - / not tried yet
  mod_negotiation.c     +
  mod_proxy.c           - / no protocol conversion implemented yet
  mod_rewrite.c         ? / untested
  mod_setenvif.c        +
  mod_so.c              - no shared libs
  mod_speling.c         +
  mod_status.c          +
  mod_unique_id.c       +
  mod_userdir.c         +
  mod_usertrack.c       ?


What doesn't work yet:
-   no DBM or DB authentication (library missing)
-   no MD5 hash or digest (not ported yet)

			    Martin Kraemer, 25-Jan-1998