rubbos/app/apache2/manual/platform/ebcdic.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>The Apache EBCDIC Port - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.0</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Platform Specific Notes</a></div><div id="page-content"><div id="preamble"><h1>The Apache EBCDIC Port</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/platform/ebcdic.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="../ko/platform/ebcdic.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  23 </div>
  24
  25
  26     <div class="warning"><strong>Warning:</strong> This document
  27     has not been updated to take into account changes made in
  28     the 2.0 version of the Apache HTTP Server. Some of the
  29     information may still be relevant, but please use it with care.
  30     </div>
  31
  32   </div>
  33 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#overview">Overview of the Apache EBCDIC Port</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#design">Design Goals</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#technical">Technical Solution</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#porting">Porting Notes</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#document">Document Storage Notes</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#modules">Apache Modules' Status</a></li>
  39 <li><img alt="" src="../images/down.gif" /> <a href="#third-party">Third Party Modules' Status</a></li>
  40 </ul></div>
  41 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  42 <div class="section">
  43 <h2><a name="overview" id="overview">Overview of the Apache EBCDIC Port</a></h2>
  44
  45
  46
  47     <p>Version 1.3 of the Apache HTTP Server is the first version
  48     which includes a port to a (non-ASCII) mainframe machine which
  49     uses the EBCDIC character set as its native codeset.</p>
  50
  51     <p>(It is the SIEMENS family of mainframes running the <a href="http://www.siemens.de/servers/bs2osd/osdbc_us.htm">BS2000/OSD
  52     operating system</a>. This mainframe OS nowadays features a
  53     SVR4-derived POSIX subsystem).</p>
  54
  55     <p>The port was started initially to</p>
  56
  57     <ul>
  58       <li>prove the feasibility of porting <a href="http://dev.apache.org/">the Apache HTTP server</a> to
  59       this platform</li>
  60
  61       <li>find a "worthy and capable" successor for the venerable
  62       <a href="http://www.w3.org/Daemon/">CERN-3.0</a> daemon
  63       (which was ported a couple of years ago), and to</li>
  64
  65       <li>prove that Apache's preforking process model can on this
  66       platform easily outperform the accept-fork-serve model used
  67       by CERN by a factor of 5 or more.</li>
  68     </ul>
  69
  70     <p>This document serves as a rationale to describe some of the
  71     design decisions of the port to this machine.</p>
  72
  73   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  74 <div class="section">
  75 <h2><a name="design" id="design">Design Goals</a></h2>
  76
  77
  78
  79     <p>One objective of the EBCDIC port was to maintain enough
  80     backwards compatibility with the (EBCDIC) CERN server to make
  81     the transition to the new server attractive and easy. This
  82     required the addition of a configurable method to define
  83     whether a HTML document was stored in ASCII (the only format
  84     accepted by the old server) or in EBCDIC (the native document
  85     format in the POSIX subsystem, and therefore the only realistic
  86     format in which the other POSIX tools like <code>grep</code> or
  87     <code>sed</code> could operate on the documents). The current
  88     solution to this is a "pseudo-MIME-format" which is intercepted
  89     and interpreted by the Apache server (see below). Future versions
  90     might solve the problem by defining an "ebcdic-handler" for all
  91     documents which must be converted.</p>
  92
  93   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  94 <div class="section">
  95 <h2><a name="technical" id="technical">Technical Solution</a></h2>
  96
  97
  98
  99     <p>Since all Apache input and output is based upon the BUFF
 100     data type and its methods, the easiest solution was to add the
 101     conversion to the BUFF handling routines. The conversion must
 102     be settable at any time, so a BUFF flag was added which defines
 103     whether a BUFF object has currently enabled conversion or not.
 104     This flag is modified at several points in the HTTP
 105     protocol:</p>
 106
 107     <ul>
 108       <li><strong>set</strong> before a request is received
 109       (because the request and the request header lines are always
 110       in ASCII format)</li>
 111
 112       <li><strong>set/unset</strong> when the request body is
 113       received - depending on the content type of the request body
 114       (because the request body may contain ASCII text or a binary
 115       file)</li>
 116
 117       <li><strong>set</strong> before a reply header is sent
 118       (because the response header lines are always in ASCII
 119       format)</li>
 120
 121       <li><strong>set/unset</strong> when the response body is sent
 122       - depending on the content type of the response body (because
 123       the response body may contain text or a binary file)</li>
 124     </ul>
 125
 126   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 127 <div class="section">
 128 <h2><a name="porting" id="porting">Porting Notes</a></h2>
 129
 130
 131
 132     <ol>
 133       <li>
 134         <p>The relevant changes in the source are <code>#ifdef</code>'ed
 135         into two categories:</p>
 136
 137         <dl>
 138           <dt><code><strong>#ifdef
 139           CHARSET_EBCDIC</strong></code></dt>
 140
 141           <dd>
 142             <p>Code which is needed for any EBCDIC based machine.
 143             This includes character translations, differences in
 144             contiguity of the two character sets, flags which
 145             indicate which part of the HTTP protocol has to be
 146             converted and which part doesn't <em>etc.</em></p>
 147           </dd>
 148
 149           <dt><code><strong>#ifdef _OSD_POSIX</strong></code></dt>
 150
 151           <dd>
 152             <p>Code which is needed for the SIEMENS BS2000/OSD
 153             mainframe platform only. This deals with include file
 154             differences and socket implementation topics which are
 155             only required on the BS2000/OSD platform.</p>
 156           </dd>
 157         </dl>
 158       </li>
 159
 160       <li>
 161         <p>The possibility to translate between ASCII and EBCDIC at
 162         the socket level (on BS2000 POSIX, there is a socket option
 163         which supports this) was intentionally <em>not</em> chosen,
 164         because the byte stream at the HTTP protocol level consists
 165         of a mixture of protocol related strings and non-protocol
 166         related raw file data. HTTP protocol strings are always
 167         encoded in ASCII (the <code>GET</code> request, any Header: lines,
 168         the chunking information <em>etc.</em>) whereas the file transfer
 169         parts (<em>i.e.</em>, GIF images, CGI output <em>etc.</em>)
 170         should usually be just "passed through" by the server. This
 171         separation between "protocol string" and "raw data" is
 172         reflected in the server code by functions like <code>bgets()</code>
 173         or <code>rvputs()</code> for strings, and functions like
 174         <code>bwrite()</code> for binary data. A global translation
 175         of everything would therefore be inadequate.</p>
 176
 177         <p>(In the case of text files of course, provisions must be
 178         made so that EBCDIC documents are always served in
 179         ASCII)</p>
 180       </li>
 181
 182       <li>
 183         <p>This port therefore features a built-in protocol level
 184         conversion for the server-internal strings (which the
 185         compiler translated to EBCDIC strings) and thus for all
 186         server-generated documents. The hard coded ASCII escapes
 187         <code>\012</code> and <code>\015</code> which are ubiquitous
 188         in the server code are an exception: they are already the binary
 189         encoding of the ASCII <code>\n</code> and <code>\r</code> and
 190         must not be converted to ASCII a second time.
 191         This exception is only relevant for server-generated strings;
 192         and <em>external</em> EBCDIC documents are not expected to
 193         contain ASCII newline characters.</p>
 194       </li>
 195
 196       <li>
 197         <p>By examining the call hierarchy for the BUFF management
 198         routines, I added an "ebcdic/ascii conversion layer" which
 199         would be crossed on every puts/write/get/gets, and a
 200         conversion flag which allowed enabling/disabling the
 201         conversions on-the-fly. Usually, a document crosses this
 202         layer twice from its origin source (a file or CGI output) to
 203         its destination (the requesting client): <code>file -&gt;
 204         Apache</code>, and <code>Apache -&gt; client</code>.</p>
 205
 206         <p>The server can now read the header lines of a CGI-script
 207         output in EBCDIC format, and then find out that the remainder
 208         of the script's output is in ASCII (like in the case of the
 209         output of a WWW Counter program: the document body contains a
 210         GIF image). All header processing is done in the native
 211         EBCDIC format; the server then determines, based on the type
 212         of document being served, whether the document body (except
 213         for the chunking information, of course) is in ASCII already
 214         or must be converted from EBCDIC.</p>
 215       </li>
 216
 217       <li>
 218         <p>For Text documents (MIME types text/plain, text/html
 219         <em>etc.</em>), an implicit translation to ASCII can be
 220         used, or (if the users prefer to store some documents in
 221         raw ASCII form for faster serving, or because the files
 222         reside on a NFS-mounted directory tree) can be served
 223         without conversion.</p>
 224
 225         <p><strong>Example:</strong></p>
 226
 227         <p>to serve files with the suffix <code>.ahtml</code> as a
 228         raw ASCII <code>text/html</code> document without implicit
 229         conversion (and suffix <code>.ascii</code> as ASCII
 230         <code>text/plain</code>), use the directives:</p>
 231
 232         <div class="example"><p><code>
 233           AddType  text/x-ascii-html  .ahtml <br />
 234           AddType  text/x-ascii-plain .ascii
 235         </code></p></div>
 236
 237         <p>Similarly, any <code>text/foo</code> MIME type can be
 238         served as "raw ASCII" by configuring a MIME type
 239         "<code>text/x-ascii-foo</code>" for it using
 240         <code>AddType</code>.</p>
 241       </li>
 242
 243       <li>
 244         <p>Non-text documents are always served "binary" without
 245         conversion. This seems to be the most sensible choice for,
 246         .<em>e.g.</em>, GIF/ZIP/AU file types. This of course
 247         requires the user to copy them to the mainframe host using
 248         the "<code>rcp -b</code>" binary switch.</p>
 249       </li>
 250
 251       <li>
 252         <p>Server parsed files are always assumed to be in native
 253         (<em>i.e.</em>, EBCDIC) format as used on the machine, and
 254         are converted after processing.</p>
 255       </li>
 256
 257       <li>
 258         <p>For CGI output, the CGI script determines whether a
 259         conversion is needed or not: by setting the appropriate
 260         Content-Type, text files can be converted, or GIF output can
 261         be passed through unmodified. An example for the latter case
 262         is the wwwcount program which we ported as well.</p>
 263       </li>
 264
 265     </ol>
 266
 267   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 268 <div class="section">
 269 <h2><a name="document" id="document">Document Storage Notes</a></h2>
 270
 271
 272
 273     <h3><a name="binary" id="binary">Binary Files</a></h3>
 274
 275
 276
 277       <p>All files with a <code>Content-Type:</code> which does not
 278       start with <code>text/</code> are regarded as <em>binary
 279       files</em> by the server and are not subject to any conversion.
 280       Examples for binary files are GIF images, gzip-compressed files
 281       and the like.</p>
 282
 283       <p>When exchanging binary files between the mainframe host and
 284       a Unix machine or Windows PC, be sure to use the ftp "binary"
 285       (<code>TYPE I</code>) command, or use the
 286       <code>rcp -b</code> command from the mainframe host (the
 287       <code>-b</code> switch is not supported in unix
 288       <code>rcp</code>'s).</p>
 289
 290
 291
 292     <h3><a name="text" id="text">Text Documents</a></h3>
 293
 294
 295
 296       <p>The default assumption of the server is that Text Files
 297       (<em>i.e.</em>, all files whose <code>Content-Type:</code>
 298       starts with <code>text/</code>) are stored in the native
 299       character set of the host, EBCDIC.</p>
 300
 301
 302
 303     <h3><a name="ssi" id="ssi">Server Side Included Documents</a></h3>
 304
 305
 306
 307       <p>SSI documents must currently be stored in EBCDIC only.
 308       No provision is made to convert it from ASCII before
 309       processing.</p>
 310
 311
 312
 313   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 314 <div class="section">
 315 <h2><a name="modules" id="modules">Apache Modules' Status</a></h2>
 316
 317
 318
 319     <table class="bordered">
 320       <tr>
 321         <th>Module</th>
 322         <th>Status</th>
 323         <th>Notes</th>
 324       </tr>
 325
 326       <tr>
 327         <td><code class="module"><a href="../mod/core.html">core</a></code></td>
 328         <td class="centered">+</td>
 329         <td />
 330       </tr>
 331
 332       <tr>
 333         <td><code class="module"><a href="../mod/mod_access.html">mod_access</a></code></td>
 334         <td class="centered">+</td>
 335         <td />
 336       </tr>
 337
 338       <tr>
 339         <td><code class="module"><a href="../mod/mod_actions.html">mod_actions</a></code></td>
 340         <td class="centered">+</td>
 341         <td />
 342       </tr>
 343
 344       <tr>
 345         <td><code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code></td>
 346         <td class="centered">+</td>
 347         <td />
 348       </tr>
 349
 350       <tr>
 351         <td><code class="module"><a href="../mod/mod_asis.html">mod_asis</a></code></td>
 352         <td class="centered">+</td>
 353         <td />
 354       </tr>
 355
 356       <tr>
 357         <td><code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code></td>
 358         <td class="centered">+</td>
 359         <td />
 360       </tr>
 361
 362       <tr>
 363         <td><code class="module"><a href="../mod/mod_auth_anon.html">mod_auth_anon</a></code></td>
 364         <td class="centered">+</td>
 365         <td />
 366       </tr>
 367
 368       <tr>
 369         <td><code class="module"><a href="../mod/mod_auth_dbm.html">mod_auth_dbm</a></code></td>
 370         <td class="centered">?</td>
 371         <td>with own <code>libdb.a</code></td>
 372       </tr>
 373
 374       <tr>
 375         <td><code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code></td>
 376         <td class="centered">+</td>
 377         <td />
 378       </tr>
 379
 380       <tr>
 381         <td><code class="module"><a href="../mod/mod_cern_meta.html">mod_cern_meta</a></code></td>
 382         <td class="centered">?</td>
 383         <td />
 384       </tr>
 385
 386       <tr>
 387         <td><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code></td>
 388         <td class="centered">+</td>
 389         <td />
 390       </tr>
 391
 392       <tr>
 393         <td><code>mod_digest</code></td>
 394         <td class="centered">+</td>
 395         <td />
 396       </tr>
 397
 398       <tr>
 399         <td><code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code></td>
 400         <td class="centered">+</td>
 401         <td />
 402       </tr>
 403
 404       <tr>
 405         <td><code class="module"><a href="../mod/mod_so.html">mod_so</a></code></td>
 406         <td class="centered">-</td>
 407         <td>no shared libs</td>
 408       </tr>
 409
 410       <tr>
 411         <td><code class="module"><a href="../mod/mod_env.html">mod_env</a></code></td>
 412         <td class="centered">+</td>
 413         <td />
 414       </tr>
 415
 416       <tr>
 417         <td><code class="module"><a href="../mod/mod_example.html">mod_example</a></code></td>
 418         <td class="centered">-</td>
 419         <td>(test bed only)</td>
 420       </tr>
 421
 422       <tr>
 423         <td><code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code></td>
 424         <td class="centered">+</td>
 425         <td />
 426       </tr>
 427
 428       <tr>
 429         <td><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code></td>
 430         <td class="centered">+</td>
 431         <td />
 432       </tr>
 433
 434       <tr>
 435         <td><code class="module"><a href="../mod/mod_imap.html">mod_imap</a></code></td>
 436         <td class="centered">+</td>
 437         <td />
 438       </tr>
 439
 440       <tr>
 441         <td><code class="module"><a href="../mod/mod_include.html">mod_include</a></code></td>
 442         <td class="centered">+</td>
 443         <td />
 444       </tr>
 445
 446       <tr>
 447         <td><code class="module"><a href="../mod/mod_info.html">mod_info</a></code></td>
 448         <td class="centered">+</td>
 449         <td />
 450       </tr>
 451
 452       <tr>
 453         <td><code>mod_log_agent</code></td>
 454         <td class="centered">+</td>
 455         <td />
 456       </tr>
 457
 458       <tr>
 459         <td><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></td>
 460         <td class="centered">+</td>
 461         <td />
 462       </tr>
 463
 464       <tr>
 465         <td><code>mod_log_referer</code></td>
 466         <td class="centered">+</td>
 467         <td />
 468       </tr>
 469
 470       <tr>
 471         <td><code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code></td>
 472         <td class="centered">+</td>
 473         <td />
 474       </tr>
 475
 476       <tr>
 477         <td><code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code></td>
 478         <td class="centered">?</td>
 479         <td>not ported yet</td>
 480       </tr>
 481
 482       <tr>
 483         <td><code class="module"><a href="../mod/mod_negotiation.html">mod_negotiation</a></code></td>
 484         <td class="centered">+</td>
 485         <td />
 486       </tr>
 487
 488       <tr>
 489         <td><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></td>
 490         <td class="centered">+</td>
 491         <td />
 492       </tr>
 493
 494       <tr>
 495         <td><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></td>
 496         <td class="centered">+</td>
 497         <td>untested</td>
 498       </tr>
 499
 500       <tr>
 501         <td><code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code></td>
 502         <td class="centered">+</td>
 503         <td />
 504       </tr>
 505
 506       <tr>
 507         <td><code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code></td>
 508         <td class="centered">+</td>
 509         <td />
 510       </tr>
 511
 512       <tr>
 513         <td><code class="module"><a href="../mod/mod_status.html">mod_status</a></code></td>
 514         <td class="centered">+</td>
 515         <td />
 516       </tr>
 517
 518       <tr>
 519         <td><code class="module"><a href="../mod/mod_unique_id.html">mod_unique_id</a></code></td>
 520         <td class="centered">+</td>
 521         <td />
 522       </tr>
 523
 524       <tr>
 525         <td><code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code></td>
 526         <td class="centered">+</td>
 527         <td />
 528       </tr>
 529
 530       <tr>
 531         <td><code class="module"><a href="../mod/mod_usertrack.html">mod_usertrack</a></code></td>
 532         <td class="centered">?</td>
 533         <td>untested</td>
 534       </tr>
 535     </table>
 536
 537   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 538 <div class="section">
 539 <h2><a name="third-party" id="third-party">Third Party Modules' Status</a></h2>
 540
 541
 542
 543     <table class="bordered">
 544       <tr>
 545         <th>Module</th>
 546         <th>Status</th>
 547         <th>Notes</th>
 548       </tr>
 549
 550       <tr>
 551         <td><code><a href="http://java.apache.org/">mod_jserv</a>
 552         </code></td>
 553         <td class="centered">-</td>
 554         <td>JAVA still being ported.</td>
 555       </tr>
 556
 557       <tr>
 558         <td><code><a href="http://www.php.net/">mod_php3</a></code></td>
 559         <td class="centered">+</td>
 560         <td><code>mod_php3</code> runs fine, with LDAP and GD
 561         and FreeType libraries.</td>
 562       </tr>
 563
 564       <tr>
 565         <td><code><a href="http://hpwww.ec-lyon.fr/~vincent/apache/mod_put.html">mod_put</a></code></td>
 566         <td class="centered">?</td>
 567         <td>untested</td>
 568       </tr>
 569
 570       <tr>
 571         <td><code><a href="ftp://hachiman.vidya.com/pub/apache/">mod_session</a></code></td>
 572         <td class="centered">-</td>
 573         <td>untested</td>
 574       </tr>
 575     </table>
 576
 577   </div></div>
 578 <div class="bottomlang">
 579 <p><span>Available Languages: </span><a href="../en/platform/ebcdic.html" title="English">&nbsp;en&nbsp;</a> |
 580 <a href="../ko/platform/ebcdic.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 581 </div><div id="footer">
 582 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 583 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 584 </body></html>