Tags: view all tags

Combining CGI Script and APPX ILF

Now that you are generating HTML from within APPX, wouldn't it be nice to generate the new documents directly in response to web server requests? Not a problem. With some simple CGI scripting and some special APPX ILF routines, you can easily use APPX as a realtime backend to any web server.

The CGI Script

With this in mind, take a look at the following shell script. If you have any unix experience at all, then this should not look too foreign.

#!/bin/ksh
APPX_RESULT=/tmp/$RANDOM.html
export APPXPATH=/users/appx/data
/users/appx/appx -a=WWW -d=WWW -t=OUTPUT -p=APPX_HOME_PAGE >/dev/null
echo "Content-type: text/html"
echo ""
cat $APPX_RESULT
rm $APPX_RESULT

Note: If you are running on an APPX Promotional license, or any other license type that presents a start-up message screen (Release 4.1.8 and higher), the command above that invokes APPX must also include the "session flag", entered as -session or -s. It should look like this:

/users/appx/appx -a=WWW -d=WWW -t=OUTPUT -p=APPX_HOME_PAGE -s >/dev/null

This will suppress all attempted screen displays by internally issuing an END option whenever a screen is presented. Two cautions: (1) If you're invoking a job that includes a disposition process, the END issued when the disposition runs will cancel the job, so be sure to remove any disposition processes from the job that you execute; (2) Release 4.1.8 had a bug that caused this to cancel the entire session, so upgrading to a newer release is required.

You can call this script appxhome.cgi and when it is requested by a browser, the server will run the script to get the document. There is a little bit of trickery going on within the APPX process to get the print file back to the server. So, let us review the script a line at a time:

This tells the computer we want to execute this script using the "ksh" shell.
This generates a random filename in the /tmp directory. Our APPX process will check the value of this environment variable. Then it will move the output print file to this location right before it exists. That way, our script can find the document file. For now, this is a process that the application must perform using ILF code.
Set our APPXPATH.
Run our APPX output process. We direct stdout to /dev/null. We DO NOT want any APPX screen IO going to the web server. This would get picked up as part of the document.
Send the first required line to the server/browser. This tells the browser what format the document is in.
Send a blank line. Required after the Content-type line. These could also be generated by APPX as part of the output process.
Dump the resulting printfile to the screen. There is no screen, but the server is pretending it is the screen and will capture everything written to it. This is what will get sent back to the browser.
We are done, so remove the temp file. We don't need it anymore.

Not too ugly. The CGI script is just acting as a wrapper around our APPX process. Now you could build a new CGI script for each document you want to publish on you Web page. But you can easily modify this script to run ANY appx process. Or better yet, always make it run the SAME generic process. In this last case, you can set up an APPX Subroutine process that accepts the request, executes the requested process family, and takes care of moving the resulting print file into the correct location. This can be done with a change to the URL and the CGI script as follows:

New URL = "/appx.cgi?DOCID=APPX+HOMEPAGE"

#!/bin/ksh
APPX_RESULT=/tmp/$RANDOM.html
export APPXPATH=/users/appx/data
/users/appx/appx -a=WWW -d=WWW -t=SUBR -p=APPX_WEB_SERVER >/dev/null
cat $APPX_RESULT
rm $APPX_RESULT

We have moved the Content-type lines into APPX for more control. That way, we are not limited to a certain document type. The APPX process can now decide if we are serving text/plain or text/html. Another thing you may seem to be missing here. How does the APPX subroutine know what document is being requested? This information will be pulled from the value of the DOCID field referenced in the URL ('APPX+HOMEPAGE' in this case).

You may also notice that our URL in this example does not contain the Application / Database / Process-Type / Process Name of the APPX process we want to run. We could do this, but creating a translation table file within your APPX server application makes the document less complex and increases security. This way, someone can't edit your document source within their browser and run some process you don't want them to run.

The APPX Server Subroutine

Now that we have our CGI script in place, we need to focus on building a generic APPX subroutine to handle processing the requests. Our subroutine need to perform the following functions:

Import the parameters from the URL
Use the DOCID as a key to find out what APPX process to run.
Possibly do some security checking.
Run the process
Move the resulting print file to $APPX_RESULT so the server can find it.

Importing Parameters

In Release 5.1 and higher, you can simply use the Import CGI Data API. In older releases, you have to call the import routine yourself via:

      CALL ,RT_IMPORT_CGIDATA RESIDENT? Y END? N FAIL 0

Refer to the documentation on the Import CGI Data API for a discussion of how APPX will map the variables on the URL to APPX fields.

After this step, the APPX work field DOCID in the current application will contain 'APPX+HOMEPAGE'

Looking Up the Process ID

Now that we have imported our CGI data, we can use the value in our work field DOCID as a key into another file that tells us what APPX process to run. The layout of our hypothetical file could be something like:

WEB-99  web server                                                       Page: 1

JPN 04/05/16 14:58                        Files / Fields Technical Documentation

                                                                      -Options--
File     Descriptive Name               Org     File Type             T DP AA RP
======== ============================== ======= ===================== ==========
DOCUMENT Server Documents               INDEXED PERMANENT

Added by PHB on 5/1/1998 12:02     Changed by GLR on 4/20/2000 14:38

                               Fld                   D --Stored---   -Options--
Seq No  Field Name             Typ Format            S Start   Len   D DL AA KC
------- ---------------------- --- ----------------- - ----- -----   ----------
100     DOCUMENT ID            Dom X(30)             1     1    30           P
200     DOCUMENT AP            Dom X(3)              1    31     3
300     DOCUMENT DB            Dom &&&               1    34     3
400     DOCUMENT TYPE          Dom X(10), Tbl        1    37     1
500     DOCUMENT NAME          Dom X(30)             1    38    30
600     DOCUMENT ACCESS        Dom X(20)             1    68    20           A

End of Technical Documentation (Files / Fields)

Run the Requested Process

Once we know what process needs to be run, it is time to run it. Here is that code:

      SET      --- NEXT APPLICATION           =  WEB DOCUMENT AP
      SET      --- NEXT PROCESS NAME          =  WEB DOCUMENT NAME
      SET      --- NEXT DATABASE              =  WEB DOCUMENT DB
      *
      IF       WEB DOCUMENT TYPE              EQ     JOB
T     JOB                                           RELATED      END? N  FAIL 0
      IF       WEB DOCUMENT TYPE              EQ     OUTPUT
T     OUTPUT                                        RELATED    END? N  FAIL 0
      IF       WEB DOCUMENT TYPE              EQ     UPDATE
T     UPDATE                                        RELATED      END? N  FAIL 0
      IF       WEB DOCUMENT TYPE              EQ     STATUS
T     STATUS                                        RELATED      END? N  FAIL 0
      IF       WEB DOCUMENT TYPE              EQ     SUBROUTINE
T     SUBR                                          RELATED      END? N  FAIL 0
      RETURN

Notice that we aren't testing for Input, Menus, etc. There is no reason to invoke any interactive process via CGI, so we skip those. It only makes sense to invoke a process that can create a file to return to the web server.

Moving the Printfile into Place

Now, we need to put the resulting printfile in the place our CGI script expects to find it. First, we need to get the value of the environtment variable APPX_RESULT:

      PASS         APPX_RESULT                FIELD            SHARE? Y
      PASS     --- TEMP 256                   FIELD            SHARE? N
      GOSUB    --- .ENV GET ENV VARIABLE

We are using the .ENV GET ENV VARIABLE API to get the value. If you are running a pre 5.1 version of APPX, you can use the ,RT_GETENV call. This will return the value of APPX_RESULT into --- TEMP 256.

Now we can move our print file to the location the web server is expecting:

      PASS     --- TEMP 80                    FIELD            SHARE? Y
      PASS     --- PRINT FILE PATHNAME        FIELD            SHARE? N
      PASS     --- TEMP 256                   FIELD            SHARE? N
      GOSUB    --- .FILE MOVE

We are using the .FILE MOVE API to move the file for us. If you are running a pre 5.1 version, you can use the following (assuming a Linux/Unix host):

      SET      --- TEMP 132                   =      mv
      APPEND   --- TEMP 132                   1  --- PRINT FILE PATHNAME
      APPEND   --- TEMP 132                   1  --- TEMP 256
      APPEND   --- TEMP 132                   1      >/dev/null 2>&1
      SET      --- NEW PAGE AFTER             =      N
      RUN      --- TEMP 132                                END? N  FAIL 0

Topic revision: r5 - 2020-05-12 - JeanNeron