Writing an LCGI NLM

This chapter explains how to write an LCGI NLM and describes the associated header and source files.

Guidelines for Writing an LCGI NLM

To write an LCGI NLM, you must be familiar with the ANSI C programming language and know how to write an NLM. The Web Server and its extensions use the SRM.CFG configuration file to map a URL request to an NLM.

The \WEB\SAMPLES directory contains two directories for use with LCGI NLMs:

• CGIPARSE contains samples for writing NLMs that use parsed headers
• CGINPH contains samples for writing NLMs that use non-parsed headers

Each directory contains samples of the files that you must use when developing an LCGI NLM. The LCGI header file, CGIAPI.H, is located in the INC subdirectory of both the CGIPARSE and CGINPH directories, and the LCGI template file, CGIMAIN.C, is located in the SRC subdirectory of both the CGIPARSE and CGINPH directories.

The LCGI Template

The LCGI NLM template file, CGIMAIN.C, contains a skeleton program that you can modify by adding statements to complete the processing necessary for your unique web page. The source code for the parsed header LCGI NLM template, \WEB\SAMPLES\CGIPARSE\SRC\CGIMAIN.C, includes the following:

• Performs all startup processing, which goes from the initial main statement to the call to xxDbgHookSysMsg in the CGIMAIN.C file.
• Calls SysMsgTblInit, which is used for Web Server control system messages and message numbers to provide extra functionality and management of the NLM. Call this function, which is defined in CGIMAIN.C, if you want to take advantage of this feature.
• Registers a routine as the LCGI request handler by calling CgiExtReg.
• Performs all required work when the NLM receives a request by calling the RequestHandler function. In this template CgiStrmPrintf outputs data, and CgiEnvListCreate and CgiEnvListDestroy process environment variables.
• Handles unload processing by calling SigTermHandler and UnloadHandler. You do not need to modify these functions.

The non-parsed header LCGI NLM template, \WEB\SAMPLES\CGINPH\SRC\CGIMAIN.C, performs similar functions.

Modifying the Template

The CGIMAIN.C file contains the skeleton of a C program that creates an LCGI NLM. As delivered, CGIMAIN.C contains a simple RequestHandler function that returns an HTML page that prints out the message "This is a new test". It then retrieves all of the environment variables by calling CgiEnvListCreate and destroys Cgi_t by calling CgiEnvListDestroy. Edit this function to perform the processing needed to generate your web pages.

Compiling and Building an LCGI NLM

After you have finished writing the LCGI NLM, you can use the makefile in toSRC\MAKEFILE.MAK compile and build it. The makefile is stored in both the CGIPARSE and CGINPH directories. You can store the finished NLM in any directory on the NetWare Web Server.

Editing the SRM.CFG File

To define the LCGI NLM to the server, add a LoadableModule directive to the SRM.CFG file. Refer to Mapping a Request to an LCGI NLM for details. For example, suppose you want to define an LCGI NLM named STKQTE.NLM that is stored in WEB/SAMPLES/ETC to the server. If you do not want the client to have to specify the NLM name in the URL, add the following directive to the SRM.CFG file:

LoadableModule /LCGI1  SYS:WEB/SAMPLES/ETC/STKQTE.NLM

The corresponding URL is

HTTP://SERVER/LCGI1?data=somedata

If you want to require the client to specify the NLM name in the URL, add the following directive to the SRM.CFG file:

LoadableModule /LCGI1  SYS:WEB/SAMPLES/ETC/

The corresponding URL can be

HTTP://SERVER/LCGI1/STKQTE.NLM?data=somedata

Starting the LCGI NLM

The NetWare Web Server loads and unloads LCGI NLMs as required. When the Web Server receives a URL referencing your NLM, it will load and register your NLM for execution.

Testing the LCGI NLM

To test the LCGI NLM, type its URL in a browser and check the web page that is returned. The NetWare Web Server will load the NLM when it finds that the NLM is not already running. For example, type

http://www.websvr/lcgi1/etc/mortgage?princ=300000

Examine the resulting web page to be sure that all functions perform properly.