Using CGI to Interface with the Web

APPX understands how to parse CGI data into APPX variables. It picks apart the CGI data string and looks for variable NAMEs that match an APPX variable name and sets the variable accordingly. This acts as a SET statement where the sender is always alpha. So, if you use the ALPHA representation of a DATE field, then when APPX fills the date field from the CGI data, it will do the correct conversion from the ALPHA value.

Here is an example of how it works:

APPX expects to receive the list of CGI variables on its "stdin", when it is invoked as the action of a form. If you use METHOD=POST for your form, the web server will put the variables into stdin automatically. You just run APPX with desired command line arguments as your ACTION. With METHOD=GET for form CGI data posting, you have to get the variables into "stdin" yourself. On a UNIX web server, you would need to do an

echo $QUERY_STRING|appx -d=.....

and on a Windows web server, the precise command to do that would depend on your particular server's CGI language.

There is also an environment variable, CONTENT_LENGTH, that controls the length of the APPX variable parser. This is not specifically an APPX variable. Rather, it is set automatically by the web server, and APPX checks it to see how far to parse. If you are setting this manually, just make sure it is set equal to or greater than the length of your CGI string. If it is set longer, APPX will stop parsing when it reaches a NULL (0x00). If you use "echo" and also set this length greater than the size of you data string, you will have to be careful of trailing 0x0A characters that "echo" will append for you. There is usually a flag you can give "echo" to tell in not to do this. "man echo" should tell you this if you need it. On some UNIX systems, it is "echo -n".

The format of your CGI NAMEs for variables needs to match a pattern that APPX understands. Here is what the parser knows how to decode into APPX variable names:

AAA:BBBB BBB(CCC)=DdDdDdDd

AAA: is optional. It is the application ID of the APPX variable. If left off, it will default to the application ID of the currently running process at the point the RT_IMPORT_CGIDATA call was made. You can make this call as many times as you like from as many processes as you like. The first time it is called, it actually parses out the CGI names and values into memory. Then it checks the memory array trying to match up APPX variable names. So, if you call it again later, it skips the actual parse/import step and just re-tries to match up and fill APPX variable.

The default application ID is not kept from call to call, so you can call it from application AAA and it will try looking in the AAA dictionary. Later if you call it again from application XXX it will try looking in the DD for XXX if no app id was given in the CGI data. Clear as mud?

BBBB BBB is the variable name and is required. The embedded spaces can be specified as underscores also and APPX will treat them as spaces.

(CCC) is optional and tells APPX which occurrence of a field to set. If used, it should use leading zeroes. So it should be (002) and not (2).

These can be given in lower case. APPX will convert to upper case before trying to lookup APPX Dictionary names.

The application ID and variable name should be separated by a colon ":" and have no spaces before or after the colon.

The occurrence number should be wrapped in parentheses with no embedded spaces or spaces between the variable name and the leading parenthesis.

You can use application "---:" also. APPX will understand that you want internal APPX PDFs if it sees this.

Once inside the APPX process, you just do:

GOSUB --- .IMPORT CGI DATA

If you are running a version of APPX prior to Release 5.1, then use:

CALL ,RT_IMPORT_CGIDATA RESIDENT? Y END? N FAIL 0

You can so this anywhere in your code where you need to fill variables from CGI data. You can do it as many times as you need from as many processes within the same APPX session.

For debugging, you can set APPX_CGIDATA_LOG=/tmp/cgi.log and APPX will log it's parsing and variable lookup steps and results.

In your script that invokes APPX on the web server, be sure that you have specified APPXPATH and any other variables (like APPX_PD_SIGNS or ORAHOME) that you normally need to specify when running APPX.


> What do I need to do to get Box A to issue CGI requests to APPX running on Box B and then get the resulting HTML file back to Box A to display on the users browser.

Try "rsh" which runs a UNIX shell command on another system and gets back the output for you. We have our web server running on a separate machine from our APPX server and use the following scripts to handle the "rsh" execution.

#!/bin/sh
##
## srvr-post.cgi
##
## Web server CGI script residing on our web server
## machine to handle CGI POST requests.
##
export QUERY_STRING=`head -c $CONTENT_LENGTH`
rsh mozart "appx_server \"$QUERY_STRING\" $REMOTE_HOST"

#!/bin/sh
##
## srvr-get.cgi
##
## Web server CGI script residing on our web server
## machine to handle CGI GET requests.
##
rsh mozart "appx_server \"$QUERY_STRING\" $REMOTE_HOST"

#!/bin/ksh
##
## appx_server
##
## Shell script residing on our APPX server machine
## to handle running APPX and returning the resulting
## HTML data back to the calling script on the web
## server machine
##
export APPX_QUERY_STRING="$1"
export REMOTE_HOST="$2"
export APPXPATH=/supp/ecr/data
export TERM=vt320-k
export APPX_HTML_FILE=$RANDOM.html
/supp/ecr/appx -a=cts -d=cts -t=subr -p=web_server >/dev/null 2>&1
##
## See if the resulting file is already in HTML format.
## If not, tag with a standard HTML header/trailer.
##
head /tmp/$APPX_HTML_FILE|grep "Content-type:" >/dev/null 2>&1
if [ "$?" = "1" ]
then
cat header.html
tail -c+2 /tmp/$APPX_HTML_FILE
cat trailer.html
else
tail -c+2 /tmp/$APPX_HTML_FILE
fi
rm /tmp/$APPX_HTML_FILE

-- JoeOrtagus - 2012-02-13