Set up third party modules for HTTP Server (powered by Apache)

This topic provides information about how to set up third party modules for your HTTP Server.

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center for more information.

The HTTP Server (powered by Apache) can extend its functionality in specific areas of your server using modules. For example, a module could be configured to create a new type of authentication that is not available with the shipped HTTP Server (powered by Apache). The Apache Software Foundation (ASF) Link outside Information Center provides basic information for writing your own modules.Before the module can be used by your HTTP Server (powered by Apache), it must be compiled and saved in the QSYS directory. In addition, the LoadModule directive must be entered in your server configuration file along with any specific context required information.

As of i5/OS™ V5R4, modules must be recompiled with a UTF locale. This creates an environment where locale-dependent C runtime functions assume that string data is encoded in UTF-8. Any hardcoded constants can be encoded in UTF-8 by adding a #pragma convert(1208) statement in the module. Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is. Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required. APR and HTTP APIs as of V5R4, expect data in UTF-8. Note that several APIs have additional functions that allow a CCSID to be set to indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added. Be sure to review APIs used by your module to be aware of current changes.

Follow the below directions to compile and use a new module.

1. Save the source code

Save the source code in your QSYS or IFS directory. All objects created from compiling and creating the service program must be placed in the QSYS directory.

2. Compile the source code

Compile the source code using the CRTCMOD command. Before you compile the program, make sure you have the correct programming language compiler installed on your iSeries™ (the most common programming language used is C). Replace the text in the parenthesis ( ) with your own information. 

CRTCMOD MODULE(Destination module name and library for the compiled module object.)
Any Apache modules will need to be changed in order to run as a UTF-8 based server module as opposed to an EBCDIC based server module. There are 2 steps required:
  1. The module owner needs to add this statement to the beginning of the part, immediately after the header: #pragma convert(1208). This change causes any constant strings defined in the module to be encoded in the UTF-8 CCSID, and not in the EBCDIC CCSID. Existing functions now expect UTF-8 or ASCII string data. In some cases, parallel functions are being added that have an additional CCSID parameter. This allows data to be tagged with any CCSID and passed to these same functions. The functions handle any conversions required by system interfaces.
  2. The modules need to be compiled with different options.
    • For ILE C use: 
      CRTCMOD MODULE(MYLIB/MOD_TEST) SRCSTMF('/mydir/mymodule/source/mod_test.c') DEFINE(AS400 AS400_UTF8) LOCALETYPE(*LOCALEUTF) TERASPACE(*YES) INCDIR('/qibm/proddata/httpa/include')
    • For C++ use:
      CRTCPPMOD MODULE(MYLIB/MOD_TEST) SRCSTMF('/mydir/mymodule/source/mod_test.c') DEFINE(AS400 AS400_UTF8) LOCALETYPE(*LOCALEUTF) TERASPACE(*YES) INCDIR('/qibm/proddata/httpa/include')
    Notice the change in the LOCALETYPE parameter. Using LOCALETYPE(*LOCALEUTF) does the following: Program objects created with this option use the locale support provided by *LOCALE objects. Wide-character types contain four-byte UTF-32 values. Narrow character types contain UTF-8 values. The effect of this change enables the locale dependent C runtime functions to work on UTF-8 strings. See ../books/c092712331.pdf for more information.

Correct any errors found while compiling. Continue to compile the source code until there are no errors. Save the compiled module in the QSYS directory.

3. Create a service program

Create a service program using the CRTSRVPGM command. Replace the text in the parenthesis ( ) with your own information. 

CRTSRVPGM SRVPGM(Destination service program name and library.) 
   MODULE(Module or modules to be built into the service program. Same as CRTCMOD above.) 
   EXPORT(Name of the data item to be exported.) 
   BNDSRVPGM(Specifies other service programs needed to bind to when creating the service program.)
Note: The EXPORT field can only have the value of either *ALL or *SRCFILE. If *SRCFILE is used, you will need to have an export source file defining which data items or procedures need to be exported and contain the name of the module structure (for example, cgi_module).

The BNDSRVPGM field must have, at a minimum, the following: (QHTTPSVR/QZSRAPR QHTTPSVR/QZSRCORE QHTTPSVR/QZSRXMLP QHTTPSVR/QZSRSDBM ). These values will cover all the HTTP Sever (powered by Apache) APIs that may be used when building the service program.

4. Add LoadModule to HTTP Server (powered by Apache) configuration file

Using the IBM® Web Administration for i5/OS interface, manually add the LoadModule directive to your HTTP Server (powered by Apache) configuration.

  1. Start the IBM Web Administration for i5/OS interface.
  2. Click the Manage tab.
  3. Click the HTTP Servers subtab.
  4. Select your HTTP Server (powered by Apache) from the Server list.
  5. Expand Tools.
  6. Click Edit Configuration File.
  7. Add the following, where PATH is the directory in the QSYS directory and MODULE is the name of your module:
    LoadModule Module /QSYS.LIB/PATH/MODULE.SRVPGM
  8. Add any additional directives needed to the configuration file. Note that the compiled service program, MOD_FOOTER, is located in the QSYS directory. The " . " represent existing lines in the configuration file.

    Example (replace MYLIB.LIB with your library name):

    LoadModule footer_module /QSYS.LIB/MYLIB.LIB/MOD_FOOTER.SRVPGM
.
.
.
<Directory "/www/mydocs/htdocs">
   SetOutputFilter FOOTERFILTER
   FooterFile footer.hf
</Directory>

    The FOOTERFILTER output filter and the FooterFile directive are defined in MOD_FOOTER, the module that was compiled and configured.

  9. Click OK.
Parent topic: Programming