Package: RXICAPI
Author: W. David Ashley
IBM Global Services
dashley@us.ibm.com
Version: 1.02.01
This package provides an ICAPI interface to Object Rexx under Windows NT.
It assumes that you have written ICAPI programs before in C/C++. This package
is not an ICAPI tutorial/reference.
rxicapi.dll -> x:\www\bin
or
x:\ibm\www\bin (for Net.Commerce)
test.rex -> x:\www\bin
or
x:\ibm\www\bin (for Net.Commerce)
or
somewhere else in the NT system path
In the http.cnf file (located in x:\winnt) insert the following line:
service /cgi-bin/rexx/* C:\www\bin\rxicapi.dll:CALLREXXYou may need to modify the line above if your WWW server bin subdirectory is not located in the specified place. Note that CALLREXX is case-sensitive.
Now restart the WWW server.
To test that the package is working start your browser and enter the following URL (where xxx is the name of your server):
http://xxx/cgi-bin/rexx/test.rexThis should execute the REXX program test.rex and a sample/test HTML page should be displayed.
To build your own Rexx ICAPI programs just code your program and place it somewhere in the Windows NT system path. The interface will automatically locate the file in the path and execute the program.
The package was tested using Lotus Domino Go Webserver version 4.6.2.3, Object Rexx for Windows 95/NT version 1.02 and Windows NT version 4.o with Service Pack 3 installed.
Date Author Description
-------- ----------- -----------------------------------------------------
12/01/98 WD Ashley v1.00.01 Initial Release
12/04/98 WD Ashley v1.01.01 Fixed problem where WWW server fails after
the Rexx procedure reports an error. Also added error
messages from a failed Rexx procedure to the
httpd-error log file and also report them to the page
returned to the browser.
12/08/98 WD Ashley v1.02.01 Added the balance of the HTTPD functions.
Created the HTML documentation.
The following are the HTTPD functions available to the Rexx ICAPI programmer. Each of these external functions is automatically available at program startup. The Rexx programmer does not have to register them before using them.
Extracts the attributes of a file. Valid in all steps.
return_code = HTTPD_attributes(handle, name, value);
Authenticates a userid/password. Valid only in PreExit, Authenticate,and Authorization steps.
return_code = HTTPD_authenticate(handle);
Executes a script to satisfy this request. Valid in PreExit, Service, NameTrans, and Error steps.
return_code = HTTPD_exec(handle, name)
Extracts the value of a variable associated with this request. The valid variables you can use for the name parameter are the same as those used in the CGI. This function is valid in all steps, though not all variables will be.
return_code = HTTPD_extract(handle, name, value)
Sends a file to satisfy this request. Valid only in PreExit, Service, NameTrans, Error, and DataFilter steps.
return_code = HTTPD_file(handle, name)
Writes a string to the server’s error log. Valid in all steps.
return_code = HTTPD_log_error(handle, value)
Writes a string to the server’s trace log. Valid in all steps.
return_code = HTTPD_log_trace(handle, value)
Makes a proxy request. Valid in PreExit and Service steps.
Note: This is a completion function; the response is complete after this function.
return_code = HTTPD_proxy(handle, url, request)
Reads the body of the client’s request. Uses HTTPD_extract for headers. Valid only in the PreExit, Service and Data Filter steps.
return_code = HTTPD_read(handle, value)
Restarts the server after all active requests have been processed. Valid only in ServerInit and ServerTerm steps
return_code = HTTPD_restart()
Translates a file system path to a URL. Valid in all steps.
return_code = HTTPD_reverse_translate(handle, name, value)
Sets the value of a variable associated with this request. The valid variables you can use for the name parameter are the same as those used in the CGI. Valid in all steps.
Note that you can also create variables with this function. If any variables you create are prefixed by HTTP_, they will be sent as headers in the response, without the HTTP_ prefix. For example, if you want to see a Location header, use HTTPD_set() with the variable name HTTP_LOCATION.
This function is valid in all steps, though not all variables will be.
return_code = HTTPD_set(handle, name, value)
Provides the Webserver with a PICS label that was generated or retrieved during the PICSDBLookup step.
Valid only during the PICSDBLookup step.
return_code = HTTPD_supply_label(handle, value)
Translates a URL to a file system path. Valid in all steps.
return_code = HTTPD_translate(handle, name, url, path, query)
Writes the body of the response. Uses HTTPD_set and HTTPD_extract for headers. Valid in the PreExit, Service, NameTrans, Error, and Data Filter steps.
If you do not use HTTPD_set() to set the content type before the first time you call this function, the server will assume you are sending a CGI data stream.
You may need to use HTTPD_set() to set the CGI environment variable CONTENT_ENCODING to the appropriate code page for the content of your response (for example ebcdic) before you send the data to the client.
This function may be called multiple times.
return_code = HTTPD_write(handle, value)
The following is a very simple Rexx ICAPI program.
/*-- REXX --*/
/* set some global variables */
lf = x2c('0a') /* line-feed character */
/* get the HTTPD handle */
handle = arg(1) /* always the first and only argument to the program */
/* set and send the content-type header */
call httpd_set handle, "Content-type", "text/html"
/* start the HTML page */
/* demonstrate the HTTPD_write function */
call httpd_write handle, "<HTML>" || lf
call httpd_write handle, "<HEAD>" || lf
call httpd_write handle, "<TITLE>Sample HTML Page From Rexx</TITLE>"" || lf
call httpd_write handle, "</HEAD>" || lf
call httpd_write handle, "<BODY>" || lf
call httpd_write handle, "<H1>Sample HTML Page From Rexx</H1>" || lf
call httpd_write handle, "<P>Hello from Rexx" || lf
/* demonstrate the HTTPD_attributes function */
file = "c:\config.sys"
call httpd_write handle, "<BR><H3>Test HTTPD_attributes</H3>" || lf
attrib = ""
call httpd_attributes handle, file, "attrib"
call httpd_write handle, "The attributes of <B>"file"</B> are <B>"attrib"</B>" || lf
/* demonstrate the HTTPD_extract function */
call httpd_write handle, "<BR><H3>Test HTTPD_extract</H3>" || lf
call httpd_write handle, "The following are some common values of variables" || lf
call httpd_write handle, "<UL>" || lf
var = "URL"
value = ""
call httpd_extract handle, var, "value"
call httpd_write handle, "<LI>"var "=" value || lf
/* close the HTML page */
call httpd_write handle, "</BODY>" || lf
call httpd_write handle, "</HTML>" || lf
return