June 9, 2000 - Qilan Technical Note #4
Editorial revision 1 - August 8, 2000
Subject: Remote Run of WebTemplates - Sample QRun Scripts
Here are some executable scripts that run Qilan WebTemplates. Replace the [HTMLname] with the name of the exported WebTemplate (omit the brackets). Case matters! If your exported webtemplate is in another folder, modify the path.
Except for the first line, all lines starting with a '#' are comments. The first line is required.
The script should be saved as plain text, then using the content inspector, make it executable with correct permissions. Remember, if you are running this from a browser, the user is 'WWW'.
The last line handles stdout (output). The current line does not return any output, it merely redirects it to 'null' (nothing). You might want to use this if you are performing a global update on a timed basis. If you omit this line, the 'caller' will get the output. The 'caller' is the program that initiates the script. If you start this script from Qilan (via a QRUN), the output will be sent back to Qilan. If you initiate the script from the terminal or telnet, for example, then the output will be displayed on the terminal screen.
After you save the executable, you call it by its path/name in the QRUN command line. For example: /Local/Library/ExecutableScript
NOTES:
1. All scripts need to end with a carrige return, otherwise the last line will not be processed.
2. If you are using BBEdit on the Mac OS to create your scripts, you should save them with UNIX line breaks. Click OPTIONS in the Save dialog.
••••••••••••••••••••••••••••••
This executable will run a webtemplate with qilan.cgi. It's output (stdout) will be returned to Qilan. Note: you are not limited to returning the output of a single webtemplate. The environment variable, "CONTENT_LENGTH", is used for POST requests and refers to the length of the Name/Value pairs. Because these requests use the GET method, we default the CONTENT_LENGTH to zero.
______________________________
#!/bin/tcsh
setenv PATH_TRANSLATED "/Local/Library/WebServer/Documents/[HTML_Name]"
setenv CONTENT_LENGTH "0"
/Local/Library/WebServer/CGI-Executables/qilan.cgi
••••••••••••••••••••••••••••••
This executable will run a webtemplate with qilan.cgi. No output will be returned. Useful for processes you want to occur in the background or initiated by cron or just run from a terminal window.
______________________________
#!/bin/tcsh
setenv PATH_TRANSLATED "/Local/Library/WebServer/Documents/[HTML_Name]"
setenv CONTENT_LENGTH "0"
/Local/Library/WebServer/CGI-Executables/qilan.cgi > /dev/null
••••••••••••••••••••••••••••••
The above example does not pass any data, it just runs a script. You can, of course, pass data as well. Here's how:
______________________________
#!/bin/tcsh
#Sets environmental variables
#Sets the path to the Qilan Script to be executed
setenv PATH_TRANSLATED "/Local/Library/WebServer/Documents/[HTML_Name]"
setenv QUERY_STRING "[field1name]=[field1value]&[field2name]=[field2value]"
#Names/Values inside brackets should be form encoded; omit the brackets
setenv CONTENT_LENGTH "0"
#Redirects qilan.cgi output to a null device (no output)
/Local/Library/WebServer/CGI-Executables/qilan.cgi > /dev/null
••••••••••••••••••••••••••••••
The above example passes 'static data'. That is, data which is written into the executable script itself. You can, of course, pass dynamic data via script parameters. This requires a bit of script programming, but is not really that difficult. Here's an example:
______________________________
#!/bin/tcsh
#Sets environmental variables
#Sets the path to the Qilan Script to be executed
setenv PATH_TRANSLATED "/Local/Library/WebServer/Documents/$1"
#Where '$1' is the first parameter
setenv QUERY_STRING "$2=$3&$4=$5"
#Where Names/Values are parameters
setenv CONTENT_LENGTH "0"
#Redirects qilan.cgi output to a null device (no output)
/Local/Library/WebServer/CGI-Executables/qilan.cgi > /dev/null
________________________________
After you save the executable, you call it by its path/name followed by the parameters in the proper order in the QRUN command line. For example:
/Local/Library/ExecutableScript WebTemplate FName Stephen LName Caine
Note, make sure you form encode Names/Values when you pass them as parameters.
••••••••••••••••••••••••••••••
The previous scripts use the GET method. To use the POST method, the following script should be used:
______________________________
#!/bin/tcsh
#Sets environmental variables
#Sets the path to the Qilan Script to be executed
setenv PATH_TRANSLATED "/Local/Library/WebServer/Documents/[HTML_Name]"
setenv CONTENT_LENGTH "[#]"
#The number of characters in Query String (Name/Value pairs). You can pass
#this value as a parameter, using Qilan to determine the length.
#Inputs a file to be executed by qilan.cgi
/Local/Library/WebServer/CGI-Executables/qilan.cgi < [HTML_Name]
______________________________
The POST method is used when you do not want to pass data in the QUERY_STRING environment variable, but rather pass it as standard input (stdin). The CONTENT_LENGTH is used to determine the length of the data string. Although both methods will yield the same result, the GET method is limited to approximately 1024 characters, where the POST method can handle unlimited data lengths.
Authored by: Stephen Caine.
Editorial corrections from Jeff Orrok.
|
