Sample Module Code (mod_hw)
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0802 Edition 6 | |
| E0701 Edition 5 ♥ | |
| E0400 Edition 4 |
mod_hw.c
Mod_hw.c is a simple Apache module. It calls pow() (in the math library, /lib/libm) and helloworld() in hw.c. This example is designed to illustrate the use of external function calls.
shell/iX> cat mod_hw.c
#include <stdlib.h>
#include <math.h>
#include "httpd.h"
#include "http_config.h"
#include "http_core.h"
#include "http_log.h"
#include "http_protocol.h"
/* here's the content handler */
static int hw_handler(request_rec *r) {
double root = 12;
double power = 2;
r->content_type = "text/html";
ap_send_http_header(r);
helloworld(r);
ap_rprintf(r, "\nresult of %.2lf**%.2lf is %.2lf",
root, power, pow(root,power));
return OK;
}
/* Make the name of the content handler known to Apache */
static handler_rec hw_handlers[] =
{ {"hw-handler", hw_handler},
{NULL}
};
/* Tell Apache what phases of the transaction we handle */
module MODULE_VAR_EXPORT hw_module =
{ STANDARD_MODULE_STUFF,
NULL, /* module initializer */
NULL, /* per-directory config creator */
NULL, /* dir config merger */
NULL, /* server config creator */
NULL, /* server config merger */
NULL, /* command table */
hw_handlers, /* [7] content handlers */
NULL, /* [2] URI-to-filename translation */
NULL, /* [5] check/validate user_id */
NULL, /* [6] check user_id is valid *here* */
NULL, /* [4] check access by host address */
NULL, /* [7] MIME type checker/setter */
NULL, /* [8] fixups */
NULL, /* [9] logger */
NULL, /* [3] header parser */
NULL, /* process initialization */
NULL, /* process exit/cleanup */
NULL /* [1] post read_request handling */
};
hw.c
This file defines a function called helloworld().
shell/iX> cat hw.c
#include "httpd.h"
#include "http_config.h"
#include "http_core.h"
#include "http_log.h"
#include "http_protocol.h"
helloworld(request_rec *r)
{ ap_rputs("<HTML>\n", r);
ap_rputs("<HEADER>\n", r);
ap_rputs("<TITLE>Hello There</TITLE>\n", r);
ap_rputs("</HEADER>\n", r);
ap_rputs("<BODY>\n", r);
ap_rprintf(r, "<H1>Hello World!</H1>\n");
ap_rputs("</BODY>\n", r);
ap_rputs("</HTML>\n", r);
}
APXS Default Makefile (mod_hw)
This is the Makefile auto-generated by apxs -g -n hw.
##
## Makefile -- Build procedure for sample hw Apache module
## Autogenerated via ``apxs -n hw -g''.
##
# the used tools
APXS=apxs
APACHECTL=apachectl
# additional defines, includes and libraries
#DEF=-Dmy_define=my_value
#INC=-Imy/include/dir
#LIB=-Lmy/lib/dir -lmylib
# the default target
all: mod_hw.so
# compile the shared object file
mod_hw.so: mod_hw.c
$(APXS) -c $(DEF) $(INC) $(LIB) mod_hw.c
# install the shared object file into Apache
install: all
$(APXS) -i -a -n 'hw' mod_hw.so
# cleanup
clean:
-rm -f mod_hw.o mod_hw.so
# simple test
test: reload
lynx -mime_header http://localhost/hw
# install and activate shared object by reloading Apache to
# force a reload of the shared object file
reload: install restart
# the general Apache start/restart/stop
# procedures
start:
$(APACHECTL) start
restart:
$(APACHECTL) restart
stop:
$(APACHECTL) stop
Modified APXS Makefile (mod_hw)
This Makefile is a modified version of the apxs auto-generated Makefile. It shows how to call gcc for compiling and LinkEditor for linking. The APXS variable was also changed to contain a fully qualified path to apxs. Apxs is used for getting the correct defines and includes. It is also used for installing the new module in the libexec/ directory. Make sure to use tabs (instead of spaces) when adding callci and gcc to the MakeFile.
shell/iX> cat Makefile
##
## Makefile -- Build procedure for sample hw Apache module
## Autogenerated via ``apxs -n hw -g''.
##
## 3/01 Modified Makefile to replace apxs by gcc and linkedit for
## compile and link the used tools
APXS=/APACHE/PUB/bin/apxs
APACHECTL=/APACHE/PUB/bin/apachectl
# defines, includes and libraries
DEF=`$(APXS) -q CFLAGS`
INC=-I`$(APXS) -q INCLUDEDIR`
LIB=/lib/libm.a,/lib/libc.a
# the default target
all: mod_hw.so
# link the shared object file
mod_hw.so: mod_hw.o hw.o
callci "linkedit 'buildxl xl=./mod_hw.so;limit=5'"
callci "linkedit 'addxl from=./mod_hw.o,./hw.o \
;to=./mod_hw.so ;rl=$(LIB);merge;share'"
# compile the object files
mod_hw.o: mod_hw.c
gcc -o mod_hw.o $(DEF) $(INC) -c mod_hw.c
hw.o: hw.c
gcc -o hw.o $(DEF) $(INC) -c hw.c
# install the shared object file into Apache
install: all
$(APXS) -i -a -n 'hw' mod_hw.so
# cleanup
clean:
-rm -f mod_hw.o mod_hw.so hw.o# simple test
test: reload
lynx -mime_header http://localhost/hw
# install and activate shared object by reloading Apache to
# force a reload of the shared object file
reload: install restart
# the general Apache start/restart/stop
# procedures
start:
$(APACHECTL) start
restart:
$(APACHECTL) restart
stop:
$(APACHECTL) stop
Extended Apache Programming Interface (EAPI)
Apache 1.3.9 and later are built with an extended set of Apache APIs. This means that Apache 1.3.9 and later expects these EAPIs to be built into any DSO they call. This EAPI feature is included in Apache so that a DSO can be used by either Apache or WebWise, since WebWise requires EAPI for its SSL functionality. When creating DSOs, you must compile with the -DEAPI option. This will include the necessary EAPI header files. These header files are distributed with Apache 1.3.9 and later and reside in the /APACHE/PUB/include directory. This include directory also contains the README.EAPI file. The README.EAPI file describes additional functionality that is available with EAPI such as more features in the mod_rewrite, mod_status, and mod_proxy modules. DSOs created with apxs will automatically include the -DEAPI option. DSOs created without -DEAPI may operate successfully but may generate a warning message in the error_log file.
Troubleshooting
For any kind of trouble with Apache, first look in the error log. Execute a tail command on the error_log to look at the last few entries. The last entry will be the most recent entry: shell/iX> tail /APACHE/PUB/logs/error_log For troubleshooting Apache at the source code level, the Apache program file can be run with the MPE/iX debugger. It is best to run it with the -X (capital "X") option to prevent the parent Apache process from creating child processes: :run httpd.pub.apache;info="-X";debug
Unsupported Functionality
HP does not support Apache binaries or DSOs built by individuals or organizations outside of HP. HP supports the htpasswd and apxs utilities in the /APACHE/PUB/bin directory but not the other scripts and programs in the bin directory.
Performance
For best performance, files returned to the user should be in bytestream format. For example; .html, .htm, .shtml, .shtm, .txt, .gif, .jpeg, and .jpg files should be in bytestream format instead of in the MPE/iX type format. Bytestream files are more compatible with Apache and with other POSIX applications than are MPE/iX type files. If a web page calls many images which are not in bytestream format (BA), the page will appear to load all the way with all the content visible, yet the browser will appear hung and the activity icon will keep moving. If any files under the document root (htdocs), or in other locations that are storing and accessing web server content, are MPE/iX fixed ASCII (FA), MPE/iX variable ASCII (VA), or MPE/iX variable binary (VB) files, consider converting them to bytestream files using the "tobyte" utility. Program files (fixed binary (FB) files with an NMPROG filecode) should never be converted. A file's filetype can be determined using either the POSIX file command or the CI listfile command:
shell/iX> file index.html
index.html: commands text
shell/iX> callci listfile ./index.html,2
PATH= /APACHE/PUB/htdocs/
CODE ------------LOGICAL RECORD-------- ----SPACE---- FILENAME
SIZE TYP EOF LIMIT R/B SECTORS #X MX
1B BA 1622 2147483647 1 16 1 * index.html
The index.html file in the previous example is a bytetream file. The following
files are MPE/iX type files:
shell/iX> file index*.html
index.html: MPE/iX 256-byte variable length binary (filecode: 0)
index1.html: MPE/iX 80-byte fixed length ascii (filecode:0)
shell/iX>callci listfile ./index.html,2
PATH= /APACHE/PUB/htdocs/
CODE ------------LOGICAL RECORD------- ----SPACE---- FILENAME
SIZE TYP EOF LIMIT R/B SECTORS #X MX
128W VB 19 204800 1 32 1 8 index.html
80B FA 54 204800 1 32 1 8 index1.html
To convert an ASCII-type file (.htm*, .shtm*, or .txt), use
the tobyte utility with the -at option.
If it is a binary-type file (such as .jpeg, .jpg, or .gif), do not
use the -at option:
shell/iX>tobyte -at /APACHE/PUB/htdocs/index.html /APACHE/PUB/htdocs/newindex.htmlFor more information on the "tobyte" utility, consult the POSIX help facility (i.e., man tobyte). If the Apache web server seems slow in responding, you might try running the Apache job stream file, JHTTPD, in the C queue instead of in the default D queue. The changes shown below allow Apache to run in the C queue while keeping the default execution level for jobs in the D queue. The jobpri command can be executed on the console or in a systart file.
!job JHTTPD,www.apache;pri=cs;outclass=,2 !jobpri cs
Additional Documentation
Much of the public information available on Apache can be used for administrating Apache on MPE/iX, especially the description and usage of the Apache configuration directives. Sources for additional information include:
The Apache documents at http://docs.hp.com which contain MPE/iX specific information.
The Apache online manual pages distributed as part of the Apache product at http://yourserver.com/manual/index.html.
The Apache Software Foundation's online documentation at http://www.apache.org/docs.
Apache books, published by various publishers, such as O'Reilly and Associates, Inc. and IDG Books Worldwide, Inc.
Writing Apache Modules with Perl and C, by Lincoln Stein and Doug MacEachern, published by O'Reilly & Associates, ISBN 1-56592-567-X.
The web site for this book is http://www.modperl.com.
http://modules.apache.org is a repository of Apache modules. New modules are continually added. These modules are available from a wide-variety of sources with different types of licenses. Some modules are free (e.g., available under the Apache license), some have license restrictions, and some are commercial products.
The Perl interpreter and the gnu tools can be downloaded via the Jazz server, http://jazz.external.hp.com.
http://httpd.apache.org/docs/programs/apxs.html is the apxs manual page. It describes how to use apxs for building DSOs.
http://httpd.apache.org/docs/dso.html explains DSOs and how they can be created.
|
Major Components |
Appendix A Samba for MPE/iX Sample Comfiguration File |