hello world
Creating Virtual HTML
Creating a virtual HTML document is simply a matter of displaying valid HTML to standard output. The example program below, which we’ll call hello1.cbl, is very simple CobolScript code that will do just this, without any conditions or input processing.
To run the example, first place it in your web server’s cgi-bin directory. Then, if you are running your browser and your web server on the same machine, and 127.0.0.1 is your web server’s loopback address (the IP address that a machine typically uses to refer to itself), execute the program by typing http://127.0.0.1/cgi-bin/cobolscript.exe?hello1.cbl in your browser’s URL window. If your web server is on a different machine than your browser but you know your server IP address, just substitute that address for 127.0.0.1.
You can also run this program from a command line by simply typing the following at the command prompt:
cobolscript.exe hello1.cbl
This will display the raw HTML output to your command line screen.
Here’s the hello1.cbl code:
DISPLAY `Content-type: text/html `.
DISPLAY LINEFEED.
DISPLAY `<HTML><BODY>`.
DISPLAY `<CENTER>Hello World</CENTER>`.
DISPLAY `</BODY></HTML>`.
GOBACK.
You can see that the first text we display is the MIME header, which is this exact literal:
`Content-type: text/html`
Ü
This is followed immediately by the display of a LINEFEED character. Displaying a MIME header, followed by a linefeed, indicates to the web server that the program output that will follow the header will be a certain MIME type of input. In this case (and in the vast majority of your CGI programming), the MIME type is text/html, which means that we intend to output HTML content. The web server will recognize this MIME type and pass the remainder of our output on to the browser as HTML.
It’s very important to remember to display the correct MIME header, followed by a line with only a linefeed, in the beginning of your CobolScript CGI programs. Failing to do this may prevent anything at all from displaying in your browser when you attempt to run your programs; depending on how your web server is configured, you may or may not get an appropriate error message in your browser window.
After the program has displayed all of the HTML (which is then transferred by the web server to the browser), it executes the GOBACK command to terminate processing, and your browser window will have the phrase “Hello World” in it.
Creating an HTML Form
If you want to create a web page that will allow your users to enter data, the simplest way to do this is by using an HTML form. Forms allow you to create text boxes, text areas, list boxes, check boxes, and radio buttons to collect data, reset buttons to clear data entries, and submit buttons to submit the data to a receiving program. See Chapter 7 for a detailed discussion on how to use each of the form components in programs.
The FORM tag, along with its end tag, are used to demarcate the form, which is essentially a data input area inside an HTML document. Every form has an associated action; this action is specified in the ACTION component of the FORM tag. The ACTION argument is an URL that names a CGI program that will be executed when the browser user submits the form. In the case of the program below, which we’ll name hello2.cbl, the action is /cgi-bin/cobolscript.exe?hello2.cbl. In this example, when you submit the form on your web browser, it will run the hello2.cbl program again. Of course, since incoming data is not processed by this program, the data typed in the text box is lost after the form is submitted.
Here’s the code for hello2.cbl:
DISPLAY `Content-type: text/html`.
DISPLAY LINEFEED.
DISPLAY `<HTML><BODY>`.
DISPLAY `<CENTER>Hello World</CENTER>`.
DISPLAY `<FORM ACTION=”/cgi-bin/cobolscript.exe?hello2.cbl” `
& `METHOD=POST>`.
DISPLAY `<INPUT TYPE=TEXT NAME=”my_variable”>`.
DISPLAY `<INPUT TYPE=SUBMIT VALUE=”Click here to Submit”>`.
DISPLAY `</FORM>`.
DISPLAY `</BODY></HTML>`.
GOBACK.
The program above uses a simple text box (created by INPUT TYPE=TEXT) to collect information. You’ll notice that the text box has a NAME argument associated with it, and that the name is my_variable; this is the CGI field name. The CGI field name is the name of a CGI variable that will hold the contents of the text box when the form is submitted from the web page.
Capturing Input Data from a Web Page
At this point, you’re probably wondering how the data from the CGI variable gets into a variable in a CobolScript program. In CobolScript, when your program needs to get form data from a web page, you just use a special form of the ACCEPT statement called ACCEPT DATA FROM WEBPAGE. Here’s an example:
ACCEPT DATA FROM WEBPAGE.
This command will get the CGI data that was submitted, parse it, decode it, and place the contents in CobolScript variables that have the same names as the incoming CGI variables.
To accept data from a CGI form into a CobolScript program, you must define variables to capture the contents of the incoming CGI variables. The CobolScript variables must have the same names as the CGI variables. The program in this section, which we’ll call hello3.cbl, accepts a CGI variable called “my_variable” into a like-named CobolScript 40 byte alphanumeric variable that we’ll define here:
1 my_variable PIC X(40).
1 content_length PIC 9(05).
If you look at our hello3.cbl code segment below, you’ll notice that we use the GETENV command before we accept the CGI data from the web page. This command gets the value of the web server environment variable that is specified as the GETENV argument and places its contents into a CobolScript variable. The environmental variable CONTENT_LENGTH holds the CGI query string’s actual length. The query string is the raw data stream that the POST method uses to send data to a target program, so if this the length of this string is greater than zero, we know that there is data to accept. It’s good practice to get the value of CONTENT_LENGTH at the beginning of your CobolScript program, because by doing this, you know whether or not there is CGI data waiting for you to process. If the value of CONTENT_LENGTH is zero, then you know that the user is simply running your web based application for the first time and has not submitted a form on it. If CONTENT_LENGTH is greater than zero, then you know that the user has submitted a form from your application.
The ACCEPT DATA FROM WEBPAGE command handles all of the parsing of the POST method-submitted data internally, so you don’t have to worry about decoding the CGI data passed to the web server.
Here’s the rest of the code for hello3.cbl:
GETENV USING `CONTENT_LENGTH` content_length.
IF content_length > 0
ACCEPT DATA FROM WEBPAGE
END-IF.
DISPLAY `Content-type: text/html`.
DISPLAY LINEFEED.
DISPLAY `<HTML><BODY>`.
DISPLAY `<CENTER>Hello World</CENTER>`.
DISPLAY `my_variable: ` & my_variable.
DISPLAYLF `<FORM ACTION=”/cgi-bin/cobolscript.exe?hello3.cbl” `
& `METHOD=”POST”>`
DISPLAY `<INPUT TYPE=”TEXT” NAME=”my_variable” VALUE=”`
& my_variable & `”>`.
DISPLAYLF `<INPUT TYPE=”SUBMIT” VALUE=”Click here to Submit”>`
DISPLAYLF `</FORM>`.
DISPLAY `</BODY></HTML>`.
Again, if CONTENT-LENGTH is greater than zero, there is CGI data waiting to be accepted, and therefore the ACCEPT DATA FROM WEBPAGE statement should be executed. This statement will look at the CGI data stream being sent from the web server, decode it, and match the CGI form variable names with CobolScript variable names. That is why both the CobolScript variable and the form field are named my_variable. Because these two names correspond, the data associated with the form field my_variable will be moved to the contents of the CobolScript variable my_variable. All decoding and parsing of the CGI data stream is performed automatically.
Ü
Important note: The maximum elementary variable size in CobolScript is 2,000 bytes. If you happen to have an individual CGI field that has contents greater than 2,000 bytes, only the first 2,000 bytes of data will be stored in any target CobolScript variable that is an elementary data item. The rest will be truncated.