Jun 10 ’14
The Simple Path to Web-Enabling a Legacy CICS Application
How to access CICS transactions from a web browser has been the topic of numerous articles and training sessions. However, if you just want to get your feet wet in the CICS web swamp, where do you start? This is the bare bones story—the absolute minimum—to web-enable a web-unaware (i.e., an application that doesn’t understand HTTP or HTML) legacy CICS application using the CICS 3270 bridge. We won’t delve into explaining HTML, SOAP or any other protocol, as there are numerous resources available on those topics. Also, we won’t describe the many flavors of web access or CICS Web service commands.
Let’s assume there’s a CICS application using basic mapping support (BMS) in a CICS test region on an MVS LPAR that has a TCP/IP started task running. By the end of this article, you should be able to display that BMS map on a web browser and enter information to execute at least part of the transaction.
If you’re fortunate enough to be both a systems programmer and an application developer, you’ve completed the first step, as CICS Web services must be installed and a CICS green-screen server application is needed to execute. If you’re one or the other, this is a good time to find a partner in the other discipline.
To access anything from a web browser, you will need a valid URL that points to some web application on some application server. You will need the IP address of a mainframe LPAR and the port of a CICS region on that LPAR. The IP address is specified at start-up of the TCP/IP STC. Most likely, the systems programmer will use the “friendly” name that will be translated by a Domain Name Service server into the actual numeric address. If there’s a web-enabled CICS region available, most of that work is done. If not, you will have to create a region using the instructions in the CICS/TS for z/OS Installation Guide for the level of the CICS region. Without all the details, TCPIP=YES is required in the system initialization table (SIT), or as an override, and a TCPIPSERVICE with the port number assigned to the region is required for the listener, along with some additional IBM-provided Web service resource definition online (RDO) definitions and programs in the relocatable program library (RPL). The complete URL will look like: http://mvsipaddr:port/converter/aliastransid/bridgeprogram/apptransid.
An existing CICS green-screen application using BMS is considered “web-unaware.” To overly simplify, it won’t have any CICS Web service commands and wouldn’t know what to do with web input. Such input needs to be converted into a form a CICS program understands at the start of the transaction and into the form HTTP understands at the end of a transaction. This is handled within the CICS web interface by the Business Logic Interface (BLI) program DFHWBLLI, which is linked to by DFHWBA. DFHWBA is called the “alias program” and is run under an alias transaction with the default name of CWBA. Without getting into why it’s called alias, it’s only necessary to know that an alias transaction is started for each web access request coming to the region from TCP/IP. The URL now looks like: http://mvsipaddr:port/converter/cwba/bridgeprogram/apptransid.
CICS supplies the bridge program as DFHWBTTA. (When specified in the URL, make sure it’s in uppercase.) That program will start the CICS bridge transaction that will execute DFHWBLT, the bridge exit program, to initiate the application transaction, ATRN for illustration, and the last value in the URL: http://mvsipaddr:port/converter/cwba/DFHWBTTA/ATRN.
Now to step back to the converter, which is a program the Business Logic Interface (BLI) uses to perform encode and decode functions. The decode function converts an HTTP stream into the standard CICS COMMAREA interface, and the encode function converts the COMMAREA into an HTTP stream. In this simple presentation, the input to the application is a BMS map, not a COMMAREA, so even though the application isn’t web-aware, the converter isn’t required. Specifying “CICS” as the converter program name indicates the converter functions aren’t required. The URL is now complete: http://mvsipaddr:port/cics/cwba/DFHWBTTA/ATRN.
The remaining issue is how to turn a CICS BMS map into something a web browser can understand. IBM provides for that with a DOCTEMPLATE, which are HTML representations of the BMS map that are created through an additional step in the assembly of the BMS map source macros using DFHMSD TYPE=TEMPLATE. The output isn’t a load module, so it can’t go in the RPL. Instead, a new library, //DFHHTML DD DISP=SHR,DSN=doctemplatepds, will be added to the CICS start-up jobstream. A 'DOCTEMPLATE' RDO definition is also required. The next question should be, “Is it really that simple?” Well, it can be. What we’ve provided here is sufficient information to enter a URL, start a CICS transaction and have that task send a map for the browser to display. Depending on the application, you may not be able to do any more without additional modifications.
A Real-World Example
Our job was to web-enable a portion of an existing green-screen, menu-driven application. Only one of the menu selections was to be enabled (the one that reads a VSAM key sequence data set [KSDS] file both sequentially and randomly) and the record contents displayed on a formatted screen. To web-enable that task, we needed two maps: the main menu and the record contents display screen. From a previous project, we had a standalone CICS test region that had our test application and all the necessary IBM web software installed. We requested a port number from the network team, built our own doctemplate PDS and asked the CICS team to add it to the region start-up deck (don't forget security access) and to override the SIT TCPIP parameter. Since it was “our” CICS region, we were permitted to create our own TCPIPSERVCE and DOCTEMPLATE RDO definitions.
We typed the URL on our web browser screen and, like magic, a representation of sorts of the application menu (Figure 1 for the web interpretation of the green screen in Figure 2) appeared, with the cursor at the top entry. We moved the cursor to the BROWSE RECORDS selection, clicked on ENTER and the first record on the file appeared (see Figure 3). For the most part, it really was that simple.
Our application used PF7 and PF8 keys to sequentially browse the file. As a web application, it doesn’t respond to PF or PA keys. We also used cursor positioning under certain protected screen locations as an indicator to display additional information (see Figure 4). It wasn’t possible to select those protected fields on the browser screen, so we needed another means to provide the functions. As part of the HTML output of the TYPE=TEMPLATE assembly is a table of input buttons (see Figure 5) to simulate those keys. They aren’t part of the map assembly, so they aren’t seen on the green screen, but only from the browser. Like everything else currently in the web world, they work by point and click. We had to add code to our program to additionally respond to PF keys (IF EIBCPOSN = OR EIBAID =) and modify the HTML in the doctemplate in the DFHHTML member for that map to show which PF key referenced which data item. We recompiled my program, placed the modified (not reassembled) template in the DFHHTML library and success (see Figure 6). The one exception: If the map had to be changed, the PF key information in the new doctemplate would have to be manually recoded.
IBM conveniently provides for this customization with two macros, DFHWBOUT and DFHMDX, that can be added to the BMS MAPSET definition source. The DFHMDX macro permits specifying web browser instructions while the DFHWBOUT macro allows you to write HTML within the BMS MAPSET source copy member, topics beyond the scope of this article. Neither of these macros are recognized by the TYPE=MAP or TYPE=DSECT assemblies, only the TYPE=TEMPLATE, so they can be added without affecting the green-screen functioning of the application.