Problem solve Get help with specific problems with your technologies, process and projects.

Implementing a browser interface in COBOL: Creating your graphic Web page

Learn how to use the CGI API, Write Standard Output (QtmhWrStout) to make a visual browser interface in segments, and use the COBOL STRING command to develop the segments. Then see how the Out-Data field is filled in, and how a PERFORM of the Write-Out routine will work.

Rich Loeber

In my initial article on implementing a browser interface to your System i application in COBOL, I demonstrated how to read a simple HTML form page and extract the data shown on the form. In that article, the form was a simple logon screen with two fields, a user profile and password.

Once you've logged onto a system, you will need to present your browser user with a Web page that they can work with. You may want to present a series of options to choose from, like a menu. Or, you may want to display some contents of a database, or a combination of these things.

In my application, I chose the latter and ended up displaying a series of records from a database file along with a series of action buttons. Some of the buttons apply to specific records in the database while other are more global in nature. In this example, I'll concentrate on what you need to do to create your Web page for display in your browser session and how to send that information from your COBOL program.

Creating a Web page for display
To create a Web page for display, you will need to use the CGI API known as Write Standard Output (QtmhWrStout). The API is quite easy to use and only has three parameters. These are a text field that contains what you want to put to the Web page, a length factor that is coded in binary form (Comp-4) and the ubiquitous API error field. In my application, I have these three fields coded as follows:

       01  Out-Data    Pic x(4000) Value Space. 
    01  Out-Len     Pic s9(8)   Value Zero Comp-4.
    01  API-Error.
        03  E-BytesP   Pic s9(10) Comp-4 Value 64.  
        03  E-BytesA   Pic s9(10) Comp-4 Value Zero.
        03  E-MsgId    Pic x(7).                    
        03  E-Reserved Pic x(1).                    
        03  E-Data     Pic x(40). 

The output data text field should be large enough to contain the most information that you will be placing on the Web page in a single call. Keep in mind that you can call the API multiple times to build your Web page in segments. So, the field only needs to be as large as the largest segment. The output length is a number that represents the total number of characters that you are putting to the page during the call. The API error code is a standard format that can be used for all calls.

In my application, I found that the COBOL STRING command was most helpful and useful in building Web page segments. Here is an example of how to get your page started by writing the opening HTML statements. This HTML shows the TITLE parameter that you want used and starts the BODY section of your page:

       String  'Content-type: text/html', cr-lf, cr-lf,
                 '<TITLE>iFileAudit Work With Files</TITLE>',
                 '<BODY>', cr-lf, '|'
                 delimited by size into Out-Data.
        Inspect Out-Data tallying Out-Ctr for characters 
            after '|'.
        Compute Out-Len = 4000 - Out-Ctr - 1.
        Call linkage type is procedure 'QtmhWrStout'
                   using Out-Data, Out-Len, API-Error.
        Move space to Out-Data.
        Move zero to Out-Len, Out-Ctr.

Note the use of the upright bar (|) marker character to show where the end of the data to be written is located. This is used in the Write-Out routine to calculate the exact length of the data being written to your web page. The INSPECT verb will count the number of blank characters in the Out-Data field that follow the marker and place it in the program field called Out-Ctr. This is then used in the following COMPUTE statement to calculate the exact length of the data being sent to your web page. If your data stream has any legitimate uses of the upright bar character, you will have to pick a different character to use for your marker.

Also, note the use of a field named cr-lf. This is used to help with the readability of the HTML presented for your Web page and represents a single character carriage-return, line-feed defined with a value of X'15'. Its use is entirely optional, but I found it helpful when looking at the generated HTML source from within my browser during debug testing.

Finishing the Out-Data field
Once you have gotten this far, it is just a matter for filling the Out-Data field with more HTML to complete the information you want shown on your Web page. The key to this process is understanding how the Write Standard Output API works. All subsequent writes to your Web page can be accomplished by a simple PERFORM of the Write-Out routine shown here.

For example, the following might be used to place a graphic in the center of the body section of your page and then add some page title text:

   String '<center>',
             '<IMG SRC="/page_head.gif" BORDER=0><p>',
          '<h2>Welcome To My Application</h2>', cr-lf, 
          '</center>', '|' 
            delimited by size into Out-Data.
    Perform Write-Out.

In my next article, I will show a you how you can display a list of records from an IBM i database file on your Web page.

If you have any questions about this topic, you can reach me at, I'll give it my best shot. All email messages will be answered.

ABOUT THE AUTHOR: Rich Loeber is president of Kisco Information Systems Inc. in Saranac Lake, N.Y. The company is a provider of various security products for the IBM i market.

Dig Deeper on iSeries COBOL programming