Version 2.1
Using NetCloak With Other CGIs
Sometimes it is useful to use NetCloak in conjunction with another server add-on tool to process a single request. For example, you might have a page that is generated by a CGI linked to a database, but would like to include NetCloak commands in that page. This is called "CGI Chaining", and is made possible by NetCloak's ability to call other CGI applications.
NetCloak can call other CGIs in one of two ways, using either the "EXEC_CGI" command, or by creating a suffix mapping so that requests for a specified file type are automatically routed through a "back-end" CGI. The EXEC_CGI command is useful when you want to run more than one additional CGI for a particular page, or when you write a CGI that returns just a part of a page. For example, you could write an AppleScript CGI that generated some random phrase to be inserted into your HTML page. Instead of returning an entire page (HTTP header and all), your script could return only the phrase it was written to create. The results of your script would then be read and inserted into the page as the page is processed by NetCloak. Any NetCloak commands in the results from the CGI will also be processed by NetCloak. For information on exactly how to use the EXEC_CGI command, see the "Commands" section of this User's Guide.
In addition to executing a CGI as simply one part of an entire page, NetCloak can also accept entire pages generated by other CGIs and parse the NetCloak commands that appear in the resulting page. For example, if you wanted to include NetCloak commands within a NetForms response page, you would set up NetForms as a "back-end" to NetCloak. Here is how it works:
When a request comes in to the Web server and is dispatched to NetCloak, NetCloak checks to see if the file should be handled by another CGI. If so, NetCloak immediately passes the request off to the appropriate CGI. The "back-end" CGI handles the request normally, but instead of returning the response page to WebSTAR, it returns the response page to NetCloak. NetCloak then receives the page, processes any NetCloak commands that appear in the page and returns the final result to the Web server, which sends the response to the client.
In the case of NetForms, there is a response file that is sent from NetForms after a form has been submitted. If NetForms is set up as a "back-end" to NetCloak, the Web server sends the form data to NetCloak, which sends the data to NetForms for processing. NetForms returns a response page to NetCloak, which processes the NetCloak commands in the page and returns the resulting page to the Web server.
To set up a back-end CGI, you must:
1. Make sure that the action that defines how your Web server is going to handle the request points to NetCloak. For example, NetForms files usually end in ".FDML". To use NetForms as a back-end CGI, the URL suffix ".FDML" must use NetCloak for their processing. Note that the Web server will be sending these requests to NetCloak, not the CGI being back-ended! All CGI actions that will be cloaked must be referred directly from the Web server to NetCloak.
2. Add a line to the "NetCloak.bsm" file. "BSM" stands for "Back-end Suffix Mapping". This file tells NetCloak where to send requests that end with a particular suffix. It is made up of a file suffix (beginning with a period) and then the name of the CGI application to be called. Here is an example ".BSM" file:
.QRY :Tango.acgi
.FDML :NetForms.acgi
.RSP :Responder.cgi
In this case, URLs with a suffix of ".QRY" will be sent to "Tango.acgi", URLs with a suffix of ".FDML" will be sent to "NetForms.acgi", and those ending in ".RSP" will be sent to "Responder.cgi". Again, note that in your Web server software, all of these suffix mappings should be directed to NetCloak so that NetCloak can hand off the request and then process the results.
A few additional notes:
1. When you give NetCloak the name of a CGI to execute in the ".BSM" file, the filename must be that of the actual application. The filename can't be a file that is to be processed by an application or an alias to the CGI. You must tell NetCloak the full, exact name of the CGI application to be executed.
If the CGI is not in the same folder as NetCloak, you must specify a pathname for the CGI. Like aliases, pathnames in the NetCloak.bsm file may be either relative paths from the Web server root or full paths starting with the volume name.
2. You may use the ".BSM" file to specify up to 8 back-end CGIs.
3. Because of the extra overhead involved, back-ending CGIs can cause a noticeable decrease performance on your server for pages served from a back-end CGI. We recommend that you use care to only use back-end CGIs when needed. If another CGI does not require the use of NetCloak commands, don't set it up as a back-end CGI.
4. URLs that call CGIs by referring to them directly can be run through NetCloak without setting up a line in the ".BSM" file. Set your Web server software to send all ".CGI" or ".ACGI" requests to NetCloak and it will automatically pass these URL requests to the specified CGI application and process the results.
Query or Post parameters specified in the URL will be preserved when NetCloak calls the back-end CGI, up to a maximum of 1024 characters. This limit is the same as in WebSTAR.
5. If the "error file" setting of your Web server is set to use a CGI, NetCloak will automatically route invalid requests to it and process any NetCloak commands in the page returned by the error CGI.
6. If you have trouble setting up a CGI as a back-end CGI, make sure that the CGI executes correctly by itself first. Set up your Web server to call it directly, without going through NetCloak. If that doesn't help solve the problem, try temporarily replacing the CGI with the "Responder.cgi" application included in the NetCloak package. Responder is handy because it shows you exactly what is being sent to the CGI. Move the CGI you are trying to back-end and copy and rename Responder in its place. If Responder works as the back-end CGI, then chances are good that your set-up is correct. If Responder doesn't return a meaningful page, then go back and check your Web server and ".BSM" settings.
You may also need to change settings in the CGI you are attempting to run as a back-end. Some CGIs require configuration changes to operate properly as a back-end to NetCloak. Tango from EveryWare Development is a notable example.
7. For up-to-date information on setting up back-end CGIs, including specific information on several popular CGIs, visit the NetCloak support area at "www.maxum.com".
Copyright © 1996 Maxum Development Corporation
820 South Bartlett Road - Suite 104
Streamwood, IL 60107
http://www.maxum.com/