
Readme file for PL/I - CGI Sample Application - V1.0

This sample application demonstrates how PL/I programs can be
used as CGI (Common Gateway Interface) scripts in a WWW Server
environment.

Brief Description:

  The initial HTML page, DoWine.htm, is displayed in the browser.
The user chooses a wine variety, the price and location preferences
of this variety, their name and where they are from (optional), and
whether they want the debug window displayed.  When the 'Place Query'
button is pressed, the browser builds a string containing the values
in the form and posts this information to the WWW server.
  The WWW server passes this information and control to the first
PL/I program, gVariety.pli.  gVariety reads and processes the
information from the server's environment variables.  gVariety first
calls parseIt.pli to parse the input string and build a link list of
Name/Value pairs.  gVariety then calls gList.pli to get a list of
wines of the requested wine variety.  For the purposes of this simple
sample, this information is in an include file, winebase.cpy.  In the
real world this data would most likely be in a database which would be
accessed at this point.  After gathering the informaiton, gVariety
builds the next web page by writing out a series of HTML character
strings to standard output.  The server passes these strings back to
the browser which displays the new web page.
  The user then chooses which wine they want to know more about and
whether they want to see the debug window.  When 'Submit Query' is
pressed the browser sends this information to the next PL/I program,
gInfo.pli.  gInfo then calls gDetail.pli to get the details on the
selected wine.  Again, in the real world this would be a call to a
database.  gInfo uses the detail information to build the next, and
last, web page which is then displayed in the browser.
  There are extra things going on that might be of interest to the
user.  Each webpage has links to another web page (the PL/I home page
of course), a call to the mailto function of the browser, and a link
that displays the PL/I source of the program that built the web page.
The values of three environment variables, SERVER_SOFTWARE,
GATEWAY_INTERFACE, and SERVER_PROTOCOL are displayed in the footer of
the web pages.  The values entered for the 'first name' and 'where
are you from' fields are placed in Hidden Variables and passed through
the second web page to be displayed on the last web page.  While these
fields are hidden, they are not invisible and can be viewed using
View->Page Source while on the second web page.  Lastly, the
'Show Debug Info' button causes a window with debug variable information
to be displayed.  This window is created by a JavaScript function
that is added to the generated web page.
  The goal of this sample application is to demonstrate to the user
how PL/I fits into the WWW-CGI environment.  The 'extra things' were
added to show that there really is no limit to what can be done from
a PL/I CGI program.  Many other WWW techniques such as cookies and
redirection can easily be added.

This sample application requires VisualAge PL/I for Windows NT V2.1
FixPak #6 or later to run properly.  To run on OS/390 it requires
VisualAge PL/I for OS/390 V2R2 Full Function Offering.


Sample application Parts:

    gVariety.pli
    gInfo.pli
    parseIt.pli
    gTag.pli
    gList.pli
    gDetail.pli
    gVariety.txt
    gInfo.txt
    winebase.cpy
    DoWine.htm
    makefile
    buy-now.gif
    grapesbw.gif
    vapli390.jpg
    readcgi.txt

Setup Instructions:

    - Set up or get access to a WWW server with CGI capability
    - Unzip the contents into a directory of your choice
    - Run the makefile to build the parts
    - Copy the *.exe and *.dll files to the /cgi-bin/ (or
        equivalent) directory of the WWW server
    - Copy the PL/I runtime DLLs (ibmw*20.dll, hepw*20.dll, ibmw*tb.dll)
        to the /cgi-bin/ (or equivalent) directory of the WWW server
    - Copy DoWine.htm and the *.txt files to the /htdocs/ (or equivalent)
        directory of the WWW server
    - Copy the *.gif and *.jpg files to the /htdocs/images/ (or
        equivalent) directory of the WWW server.  You may need to create
        an /images directory if one does not already exist.
    - Bring up http://localhost/DoWine.htm in your browser and be amazed

Deploying on OS/390:

    - This sample application can also be deployed on the MVS HTTP server
        using the new VisualAge PL/I for OS/390 product.

        The programs gVariety.pli and gInfo.pli contain conditional
        MACRO logic to accomodate the different ways the HTTP server handles
        imbedded images on each platform.  The URLs on the MVS side of this
        logic must be updated to match the URLs of your MVS HTTP server.
        Doing a find on 'stplex4b' in these two program will show you all
        the places that need to be changed.

Help or Comments:

    - Please send your comments, questions, or suggestions to either
        teampli@vnet.ibm.com or balk@us.ibm.com


