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