Recently, we decided to create a browser-based front end to one of our software applications. Since I was going to be responsible for the project, I decided to do the implementation in ILE COBOL.
A friend recommended to look at Bradley Stone's book, e-RPG, Building AS/400 Web Applications with RPG before I got started. And while starting a COBOL implementation using a book written for RPG programmers might sound strange, for the IBM midrange, it makes sense.
The protocol for programming behind a browser Web page is called common gateway interface (CGI). There is some work you need to do to get an HTTP server instance configured for CGI and you need to know something about HTML coding too. There are good resources available for both of these. But, my objective here is to show you how to get started implementing COBOL interface programs.
Implementing a logon page in a Web interface
Our application needs to be restricted to only certain user profiles, so the first project that I looked at was to implement a logon page. To do this, I had to code a FORM in HTML and then create a CGI program to process the form fields. The HTML for the body of the logon page that we're using looks like this:
<body>
<h2>MyApplication Log-on</h2>
<p>
Enter your user profile and password.
<p>
<FORM action="/cgibin/MYLOGON" method="post">
User ID: <INPUT type="text" name="USRPRF" size=10>
<p>
Password: <INPUT type="password" name="PSWD" size=10>
<p>
<INPUT type="submit" value="Logon">
</form>
</body>
The FORM statement starts the definition of fields that will be passed to your CGI program. It also tells the server what program to call, in this case the program is named MYLOGON. Two fields are defined with INPUT statements and an action button is defined with a third INPUT statement. When the submit button in pressed the two fields in question will be passed to your program.
Creating a logon program using CGI APIs
Your MYLOGON program has to do a little housekeeping at the very start to get the variables passed into it. These are not passed like normal parameters, but are passed as receiver variables. Getting the variables is normally a two step process, first to get all the variables into your program and then to extract them into normalized field formats.
To do this, you use two CGI API's. The first is called "read standard input" (QtmhRdStin) and the second is "convert to database" (QtmhCvtDb). The API's are available to you in the service program set named QZHBCGI which must be copied into your CGI application library from the QHTTPSRV library in the operating system. You will also need a binding directory in your CGI application library with an entry in it that points to this service program. When you ILE COBOL programs are compiled, you must include the BNDDIR(MYLIB/CGIBNDDIR) parameter.
To use the read standard input API, I have the following coded in MYLOGON program:
01 in-data pic x(1000) value space.
01 in-len pic s9(8) value 1000 comp-4.
01 in-lenr pic s9(8) value zero comp-4.
02 API-Error.
02 E-BytesP pic s9(10) comp-4 value 64.
02 E-BytesA pic s9(10) comp-4 value zero
02 E-MsgId pic x(7).
02 E-Reserved pic x(1).
02 E-Data pic x(40).
.
.
call linkage type is procedure 'QtmhRdStin'
using in-data, in-len, in-lenr, API-Error.
After this call, which is the first statement in the procedure division, the data from the form fields will reside in the in-data field. The data will be in a form that is difficult to work with, requiring extensive parsing. To simplify this, the second API will extract the individual fields into a normalized database format.
In MYLOGON, the following call statement immediately follows the one above with the indicated additional program variables used:
01 data-file.
02 filler pic x(10) value 'USRPWD'.
02 filler pic x(10) value 'MYLIB'.
01 db-out pic x(20).
01 db-len pic s9(8) value 20 comp-4.
01 db-lenr pic s9(8) value zero comp-4.
01 db-resp pic s9(8) value zero comp-4.
.
.
call linkage type is procedure 'QtmhCvtDb'
using data-file, in-data, in-lenr,
db-out, db-len, db-lenr, db-resp, API-Error.
Creating a DDS file for form fields
The data-file parameter points to a DDS described database file that contains the two fields from the FORM. You will need to create this DDS and compile it to your library. The field names used in your DDS must match up with the field names specified in the "name" parameter on the "input" line in the HTML. After this call is done, the two ten character fields described in your FORM HTML will be stored in the db-out program variable. You can then proceed to validate them and either reject the logon attempt or move on with your application.
My next COBOL tip installment will continue the process from this point.
If you have any questions about this topic, you can reach me at rich@kisco.com, I'll give it my best shot. If you need help with HTTP configuration, let me know and I may be able to help you. 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 iSeries market.
