Commit 750c56f0 authored by Manoj Kasichainula's avatar Manoj Kasichainula
Browse files

Submitted by: Joe Moenich and others at IBM 

Newly created files from the TPF port


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@82341 13f79535-47bb-0310-9956-ffa450edef68
parent 9a165228

docs/manual/install-tpf.html

0 → 100644
+273 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

<title>Installing Apache on TPF</title>

</head>



<a name="top"></a>

<h1 align="center">Installing the Apache 1.3 HTTP Server on TPF</h1>

<hr>

<center>[&nbsp<a href="#setup">Setup</a>

   &nbsp|&nbsp<a href="#compilation">Compilation</a>

   &nbsp|&nbsp<a href="#installation">Installation</a>

   &nbsp|&nbsp<a href="#visualage">VisualAge</a>&nbsp]

</center>

<hr>

<br>



<p>

This document outlines the steps needed to install Apache onto a TPF system.

<br><br>

You should first read src/os/tpf/<a href="readme.tpf.html">readme.tpf.html</a>

for basic information on the port of Apache to TPF including required PUT level

and supported functions &amp; modules.

</p>



<a name="setup">&nbsp;</a>

<h2 align=center>Setup</h2>

<p>

Due to the use of EBCDIC on MVS OS/390 Open Edition (later referred to simply as

"Open Edition"), we've found that the most reliable

method for loading Apache onto your system is to unzip and tar the distribution

file on your PC, and then copy the extracted files to Open Edition via an NFS client

capable of transferring the data in EBCDIC format.

<br><br>

Before moving the distribution to an

Open Edition environment, verify that the NFS drive will transfer the

filenames with upper/lower case preserved.

<br><br>

Since Open Edition is not the ultimate destination of the files,

the only required files and subdirectories that need to be moved to Open Edition

are in /src.

<br><br>

<font strong color=red>WARNING</font>:

If you are using a product such as WinZip on your PC, verify that

the <i>"TAR File Smart CR/LF Conversion"</i> option is NOT checked.

You can find this in WinZip under Options, Configuration.

Since you had to tar and unzip the file to read this document,

you need to re-tar and -unzip if the CR/LF option was checked.

This will save you lots of headaches later on.

<br><br>

<font strong color=red>WARNING</font>:

Editing files on a PC before moving them to Open Edition may result

in the loss/addition of unprintable characters.  Files of concern include shell

scripts and src/Configuration.  The most common problems are with tab characters

and CR/LF characters.  Most editors will handle the CR/LF problem correctly

but none seem to handle tab characters.  If you need to edit files, edit them

in a UNIX editor such as vi or emacs.

</p>



<a name="compilation">&nbsp;</a>

<h2 align=center>Compilation</h2>

<p>

Apache supports the notion of "optional modules".  However,

the server has to know which modules are compiled into it.  In order for

those modules to be effective, it is necessary to generate a short bit of

code ("modules.c") which simply has a list of them. If you are using the

make and Configure utility, "modules.c" will be created for you.

<br><br>

The provided scripts assume a c89 compiler and have only been tested on an

Open Edition environment.  If you are using a platform other that

Open Edition you may need to modify src/os/tpf/TPFExport and src/Configure

to match your environment.

<br><br>

Note that UNIX/Open Edition commands in this section are shown in

<tt><strong>bold</strong></tt>,

are case sensitive, and must be made from the "src" directory.

<br><br>

<ol>

<li>Overlay src/Configuration with src/Configuration.tmpl:  

    <tt><strong>cp&nbsp;Configuration.tmpl&nbsp;Configuration</strong></tt>

    <br><br>

<li>Edit src/Configuration.  It contains the list and settings

    of various "Rules" and an additional section at the bottom that determines

    which modules to compile:

    <br><br>

    <ol type=a>

    <li>Adjust the Rules and <tt>EXTRA_CFLAGS|LIBS|LDFLAGS|INCLUDES</tt>

        if you feel so inclined.

    <br><br>

    <li>Comment out (by preceding the line with a "#") lines corresponding

        to those modules you DO&nbsp;NOT wish to include.

        At present the following modules MUST be commented out

        as they are not yet supported on TPF: mod_actions, mod_auth,

        mod_cgi, mod_env, mod_include, & mod_status.

    <br><br>

    <li>Uncomment (by removing the initial "#", if present) lines

        corresponding to those optional modules you wish

        to include or add new lines corresponding to any custom modules

        you have written.

        The src/os/tpf/<a href="readme.tpf.html">readme.tpf.html</a>

        document lists the modules that have been tested on TPF.

    </ol>

    <br>

<li>Overlay src/Makefile.tmpl with src/Makefile.tpf:

    <tt><strong>cp&nbsp;Makefile.tpf&nbsp;Makefile.tmpl</strong></tt>

    <br><br>

<li>Overlay src/main/Makefile.tmpl with src/main/Makefile.tpf:

    <tt><strong>cp&nbsp;main/Makefile.tpf&nbsp;main/Makefile.tmpl</strong></tt>

    <br><br>

<li>Set the TPF environment variables:

    <tt><strong>.&nbsp;os/tpf/TPFExport</strong></tt>

    <br>

    (The initial period and blank on the command are required to ensure

    the environment variables exist beyond the scope of the shell script.)

    This script will set the environment variables required to compile the

    programs for TPF.  Verify that the export variables are valid for your

    installation, in particular, the system include file directories.  The

    system include files must reside on your Open Edition system in the

    appropriate file structure similar to /usr/include and /usr/include/sys.

    DO&nbsp;NOT modify the <tt>TPF=YES</tt> export variable.  If this is changed, the

    "Configure" script will not recognize TPF.

    <br><br>

<li>Run the "Configure" script:

    <tt><strong>Configure</strong></tt>

    <br>

    The output will look something like this...

      <pre>

      Using config file: Configuration

      Creating Makefile

       + configured for TPF platform

       + setting C compiler to c89

       + setting C pre-processor to c89 -E

       + checking for system header files

       + adding selected modules

      Creating Makefile in support

      Creating Makefile in main

      Creating Makefile in ap

      Creating Makefile in regex

      Creating Makefile in os/tpf

      Creating Makefile in modules/standard

      Creating Makefile in modules/example

      $ _

      </pre>

    This generates modules.c and new versions of the Makefiles.

    <br><br>

    If you want to maintain multiple configurations, you can say, e.g.,

    <br>

    <tt><strong>Configure -file Configuration.ai</strong></tt>

    <br>

      <pre>

      Using config file: Configuration.ai

      Creating Makefile

       + configured for &lt;whatever&gt; platform

       + setting C compiler to &lt;whatever&gt;

      et cetera

      </pre>



    If you receive an error such as "<tt>Configure 146: FSUM7351 not found</tt>"

    the most likely explanation is that one or more of the make related

    files were edited on a non-UNIX platform, corrupting the end-of-line marks.

    Verify that lines ending with "\" in the flagged file do&nbsp;not have trailing

    spaces.  Using the vi editor and the sample error above as an example...

    <br><br><pre>

            pull up the flagged file:       <strong>vi&nbsp;Configure</strong>

            turn on punctuation:            <strong>:set&nbsp;list</strong>

            go to the line in question:     <strong>146G</strong>

               or find a line with a "\":   <strong>/\\</strong></pre>

    The end of line should display as "<tt>\$</tt>".  If it is displayed as

    "<tt>\ $</tt>" (with a blank between \ and $) then you should revert to the

    distributed version of the file and make the site-specific

    changes again using a UNIX compatible editor such as vi or emacs.

    Then try the Configure command again.

    <br><pre>            close the file:                 <strong>:q  </strong>(or 



<strong>:quit!</strong>)</pre>

<li>Now compile the programs: <tt><strong>make</strong></tt><br>

    The modules placed in the Apache distribution are the ones that have been

    tested and are used regularly by various members of the Apache development

    group.  Additional modules contributed by members or third parties with specific

    needs or functions are available at

    <a 



href="http://www.apache.org/dist/contrib/modules/">http://www.apache.org/dist/contrib/modules/</a



>.

    There are instructions on that page for linking these modules into the core Apache

    code.

    <br><br>

    If during compilation you get a warning about a missing 'regex.h', set

    <tt>WANTHSREGEX=yes</tt> in the src/Configuration file and start back at the

    <tt><strong>Configure</strong></tt> step.

</ol>

</p>



<a name="installation">&nbsp;</a>

<h2 align=center>Installation</h2>

<ol>

<li>After compilation, you will have all the object files required to build an

  "httpd" loadset.  The next step is to link the object files and create a loadset to be

  stored in a PDS.  Sample JCL for linking and loadsets has been included in

  src/os/tpf/samples as "linkdll.jcl" and "loadset.jcl".  You can submit these jobs

  from CMS or directly from Open Edition if you have the proper authority.  After

  the jobs have completed, you can <tt>ZOLDR LOAD</tt> them to your TPF system.

  <br><br>

  NOTE: The <tt>mod_<i>xxx</i>.o</tt> files in the linkdll.jcl file must correspond to the

  <tt>mod_<i>xxx</i>.o</tt> lines in the src/Configuration file.

  <br><br>

<li>

  Apache requires a configuration file to initialize itself during activation.

  (Previously three configuration files were used.)

  Copy the distribution version, /conf/httpd.conf-dist, to /conf/httpd.conf and then

  edit the /conf/httpd.conf copy with your site specific information.  This first release

  of Apache for TPF only runs under the "inetd" model so you

  <font strong color=red>must</font> change <tt>ServerType</tt> from <tt>standalone</tt>

  to <tt>inetd</tt>.

  <br><br>

  General documentation for Apache is located at

  <a href="http://www.apache.org/docs/">http://www.apache.org/docs/</a>

  and in the HTML pages included with this distribution under the

  /htdocs/manual directory.

  <br><br>

<li>On TPF activate ZCLAW and update INETD using ZINET entries, the common case:

    <br><br>

    <pre>

    ZINET ADD S-TFTP   PGM-CTFT PORT-69 PROTOCOL-UDP MODEL-NOWAIT

    ZINET ADD S-APACHE PGM-<i>pppp</i> PORT-80 PROTOCOL-TCP MODEL-NOWAIT</pre>

  Please refer to <i>IBM Transaction Processing Facility Transmission Control

  Protocol/Internet Protocol Version 4 Release 1</i> for more information

  on ZCLAW, INETD, and TFTP.

  <br><br>

<li>Prior to sending a request to your Apache server from a browser,

    TFTP the configuration file, log, icons and web pages to your TPF system.

    A typical directory structure for Apache is as follows:

<pre>     /usr/local/apache/conf

     /usr/local/apache/logs

     /usr/local/apache/icons

     /usr/local/apache/htdocs</pre>

    The logs directory must exist in order to avoid an

    <code>fopen</code> error while running Apache.  TFTP an empty file into

    the logs subdirectory to create it.  All gif, jpg, and zip files should be

    TFTP'd as binary; conf files and html pages should be TFTP'd as text.

</ol>

<a name="visualage">&nbsp;</a>

<h2 align=center>Compiling with VisualAge TPF</h2>

<p>

  It is not required that "make" be used to compile Apache for TPF:

  Individual programs may be compiled using IBM's VisualAge TPF product.

  This is particularly useful when compiling selected programs for the Debug Tool.

  <br><br>

  The following VisualAge compile settings are required:

  <ul>

  <li><i>"DEFINE - Define preprocessor macro name(s)"</i> must include

     <tt><strong>TPF, CHARSET_EBCDIC, _POSIX_SOURCE,</strong></tt> and

     <tt><strong>USE_HSREGEX</strong></tt>

  <br><br>

  <li><i>"LSEARCH - Path for user include files"</i> must include

     <tt><strong>../src/include</strong></tt> and <tt><strong>../src/os/tpf</strong></tt>

  <br><br>

  <li><i>"DLL - Generate DLL code"</i> must be checked

  <br><br>

  <li><i>"LONGNAME - Support long names"</i> must be checked

  </ul>

</p>

<hr>

<center>[&nbsp<a href="#top">top</a>

   &nbsp|&nbsp<a href="#setup">Setup</a>

   &nbsp|&nbsp<a href="#compilation">Compilation</a>

   &nbsp|&nbsp<a href="#installation">Installation</a>

   &nbsp|&nbsp<a href="#visualage">VisualAge</a>&nbsp]

</center>



</body>

</html>

docs/manual/platform/readme-tpf.html

0 → 100644
+222 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

<title>The Apache TPF Port</title>

</head>



<a name="top"></a>

<h1 align="center">Overview of the Apache TPF Port</h1>

<hr>

<center>[&nbsp<a href="#configuration_files">Configuration Files</a>

   &nbsp|&nbsp<a href="#auto_generated_files">Auto Generated Files</a>

   &nbsp|&nbsp<a href="#whats_available">What's Available</a>

   &nbsp|&nbsp<a href="#porting_notes">Porting Notes</a>&nbsp]

</center>

<hr>

<br>



<p>

   This version of Apache includes changes allowing it to run on

   IBM's EBCDIC-based

   <a href="http://www.s390.ibm.com/products/tpf/tpfhp.html">TPF</a>

   (Transaction Processing Facility) operating system.

   Unless otherwise noted TPF version 4.1 PUT08 and APAR PJ25589 are required.

   <br><br>

   Refer to src/os/tpf/<a href="install.tpf.html">install.tpf.html</a>

   for step-by-step installation instructions.

   <br><br>

   As this is the first cut at making Apache run on TPF,

   performance tuning has not been done.

   <br><br>

   This port builds upon the

   <a href="http://www.apache.org/docs/ebcdic.html">EBCDIC changes</a>

   previously made to Apache.

   <br>

</p>



<a name="configuration_files">&nbsp;</a>

<h2 align=center>Apache Configuration Files</h2>

<p>

   The distributed configuration files (httpd.conf-dist and

   mime.types, both located in the conf subdirectory)

   work on TPF with only a couple of operating system specific changes

   to httpd.conf:<br>

   <ul>

   <li>ServerType needs to be "inetd" since TPF does not yet support

       "standalone" mode.

   <li>Performance considerations may dictate setting KeepAlive to "Off"

       (the default is "On") or lowering the Timeout value from the default

       300 seconds (5 minutes) in order to reduce the number of active ECBs on your system.

   </ul>

</p>



<a name="auto_generated_files">&nbsp;</a>

<h2 align=center>Automatically Generated Files</h2>

<p>

   Some files that are automatically generated by Makefile on other platforms

   are included in the src/os/tpf directory...

   <ul>

   <li>test_char.h

   <li>uri_delims.h

   </ul>



   These files could not be automatically created for TPF because the

   Makefile platform is not the same as the run-time platform.

   (That is, you don't run Makefile on TPF itself.)

</p>



<a name="whats_available">&nbsp;</a>

<h2 align=center>What's Available in this Version</h2>



   (The Apache organization provides

   <a href="http://www.apache.org/docs/">online documentation</a>

   describing the various modules and components of the server.)



<h3>Components/modules tested on TPF:</h3>



   <multicol COLS=3><ul>

   <li>alloc.c

   <li>ap_cpystrn.c

   <li>ap_fnmatch.c

   <li>ap_signal.c

   <li>ap_slack.c

   <li>ap_snprintf.c

   <li>buff.c

   <li>buildmark.c

   <li>ebcdic.c

   <li>http_config.c

   <li>http_core.c

   <li>http_log.c

   <li>http_main.c

   <li>http_protocol.c

   <li>http_request.c

   <li>http_vhost.c <a href="#note_2">*</a>

   <li>mod_access.c

   <li>mod_alias.c

   <li>mod_asis.c

   <li>mod_autoindex.c

   <li>mod_cern_meta.c

   <li>mod_dir.c

   <li>mod_example.c

   <li>mod_expires.c

   <li>mod_headers.c

   <li>mod_imap.c

   <li>mod_info.c

   <li>mod_log_agent.c

   <li>mod_log_config.c

   <li>mod_log_referer.c

   <li>mod_mime.c

   <li>mod_negotiation.c

   <li>mod_setenvif.c

   <li>mod_speling.c

   <li>mod_userdir.c

   <li>mod_usertrack.c

   <li>os.c

   <li>os-inline.c

   <li>regular expression parser

   <li>util.c

   <li>util_date.c

   <li>util_uri.c

   </ul></multicol>

   Please keep in mind that some major pieces are not yet in place including

   standalone mode, pipes, password/group files, CGI scripts, and MD5 support.

   <br>

   <a name="note_2">&nbsp;</a>

   <br>

   * virtual hosting requires TPF version 4.1 PUT09



<h3>Components/modules not (yet?) supported on TPF:</h3>



   <multicol COLS=3><ul>

   <li>htpasswd.c

   <li>md5c.c

   <li>mod_actions.c

   <li>mod_auth.c

   <li>mod_auth_anon.c

   <li>mod_cgi.c

   <li>mod_digest.c

   <li>mod_env.c

   <li>mod_include.c

   <li>mod_mime_magic.c

   <li>mod_proxy.c

   <li>mod_rewrite.c

   <li>mod_status.c

   <li>mod_unique_id.c

   <li>proxy_cache.c

   <li>proxy_connect.c

   <li>proxy_ftp.c

   <li>proxy_http.c

   <li>proxy_util.c

   <li>rfc1413.c

   <li>util_md5.c

   <li>util_script.c

   </ul></multicol>



<h3>Components/modules that don't apply or that probably won't ever be available on TPF:</h3>



   <multicol COLS=3><ul>

   <li>gen_test.char.c

   <li>gen_uri_delims.c

   <li>mod_auth_db.c

   <li>mod_auth_dbm.c

   <li>mod_auth_db.module

   <li>mod_mmap_static.c

   <li>mod_so.c

   </ul></multicol>



<a name="porting_notes">&nbsp;</a>

<h2 align=center>Porting Notes</h2>

<p>

   <h3>Changes made due to differences between UNIX and

   TPF's process models:</h3>

   <ul>

   <li><b>Signals</b>: On TPF a signal that is sent to a process

      remains unhandled until the process explicitly requests that signals

      be handled using the <code>tpf_process_signals()</code> function.

      Additionally, the default action for an alarm on TPF is to take

      an OPR-7777 dump and exit.  (On UNIX the default is the equivalent

      of <code>exit()</code> with no dump taken.)

      These differences necessitated a few modifications:

      <br><br>

      <ul>

      <li>bypass the use of <code>ap_block_alarms()</code> &amp;

         <code>ap_unblock_alarms()</code>

      <li>add <code>tpf_process_signals()</code> calls

      <li>add <code>select()</code> calls in buff.c to prevent blocking.

      </ul>

   <br>

   </ul>



   <h3>Find that function...</h3>

   <p>Some simple functions &amp; definitions needed to be added

      on TPF, such as <code>FD_SET()</code>.

      We've put these in src/os/tpf/os.h for now.

   </p>



   <h3>EBCDIC changes:</h3>

   <p>TPF-specific conversion tables between US-ASCII and

      EBCDIC (character set IBM-1047 to be exact) were created

      and put into ebcdic.c in the src/os/tpf directory.

   </p>



   <h3>Miscellaneous, minor changes:</h3>

   <p>Various minor changes (such as casting) were made due to

      differences in how some functions are implemented on TPF.

   </p>



   <h3>Temporary changes:</h3>

   <p>Lastly, we needed to bypass sections of Apache processing

      since this first cut for TPF doesn't include

      Standalone mode, pipes, forking, et cetera.

   </p>



<hr>

<center>[&nbsp<a href="#top">top</a>

   &nbsp|&nbsp<a href="#configuration_files">Configuration Files</a>

   &nbsp|&nbsp<a href="#auto_generated_files">Auto Generated Files</a>

   &nbsp|&nbsp<a href="#whats_available">What's Available</a>

   &nbsp|&nbsp<a href="#porting_notes">Porting Notes</a>&nbsp]

</center>



</body>

</html>