Moving the web application to CICS
I recently realized that many people are uncertain how relative links work in web pages and more specifically how to use these in CICS. This article will attempt to demonstrate how relative links work.
I will also show how to use multiple PDS datasets within a CICS region for those that are not using HFS for the location web pages yet.
Finally, this example will demonstrate the flexibility of the URIMAP definition that is available since CICS TS3.1.
Relative links or URLs are simply put a way of referring to another page or object within a page by the relative offset of that object from the current page.
For demonstration purposes imagine that a web page is located on your personal computer in a folder called RelativeLinks. Lets assume the page is called Hello.html. The structure now looks like this:
RelativeLinks/Hello.html
Inside the page we want to refer to a style sheet that this web page will use. This will cause the
web browser to load that external file as well. The style sheet will live in a subfolder of the
RelativeLinks folder.
This subfolder is called css. The style sheet file is called special.css. We can refer to the style sheet as follows:
<link href="C:/RelativeLinks/css/special.css"rel="stylesheet" type="text/css">
The href attribute will inform the browser which file to load. However if we now move the whole web application to another location on the computer or more importantly want to move the file to CICS the link above will be broken. So how do we fix this?
All the web browser really needs to know about the file that it is about to load is where that file is relative to the current page. If we look at it from that perspective the file will always be located in a subfolder called css and the file will always be called special.css. Everything else is determined by where this web application lives. We therefore change the link too look like this:
<link href="css/special.css"rel="stylesheet" type="text/css">
The web browser will take the current location of the web page and add the relative link above to it. The resulting location will be exactly the same as the first link.
Some people have difficulty to migrate static web artifacts from the computer where these files are designed. Of course there are some of us that edit web pages on the host but more complex web pages need to be authored using graphical tools. For this we need to design the page off the host and then migrate it to CICS. It is therefore imperative that we use the relative link concept described above to avoid having to change the web page as we move it onto the mainframe.
In this example I reluctantly use PDS datasets to show how artifacts can be stored in different datasets. However I want to strongly suggest that web artifacts need to be stored in HFS files on the mainframe. This will substantially decrease the complexity and intensity of maintaining the web artifacts.
However in our example we will use the following datasets:
//HTML DD DSN=CICS.HTML,DISP=SHR
//CSS DD DSN=CICS.CSS,DISP=SHR
//JSCRIPT DD DSN=CICS.JSCRIPT,DISP=SHR
The datasets are added to the CICS JCL so that we can refer to them using document templates. Note that we could also use one PDS to store the artifacts but this is a way to group the artifacts according to type if you so desire. (Please refer to my comment on HFS files above for the right way of doing things)
We now will code an HTML file called Hello.html. The code of the web page is shown here:
<html>
<head>
<link href="css/special.css"rel="stylesheet" type="text/css">
<script type="text/javascript"src="javascript/myscript.js"></script>
</head>
<body onload="isactive();">
<p class="special">This paragraph should have special green text.</p>
</body>
</html>
Note the relative links that are highlighted. We will also invoke a JavaScript in this page. The first step is to store the HTML file in the CICS.HTML PDS.
The next thing we need to do is decide what our web application name will be. For this I chose the arbitrary name called samplepds because this originally started out being a demonstration of how to use multiple PDS datasets in a CICS region. To set up the link that people can use to load the HTML page we create the following URIMAP:
DEFINE URIMAP(HELLO) GROUP(SAMPPDS)
STATUS(ENABLED) USAGE(SERVER) SCHEME(HTTP) HOST(mvstech)
PATH(/samplepds/Hello.html) ANALYZER(NO) MEDIATYPE(text/html)
CHARACTERSET(iso-8859-1) HOSTCODEPAGE(037) TEMPLATENAME(HELLO)
REDIRECTTYPE(NONE)
The URIMAP will fulfill two important things.
The document template definition can look like this:
DEFINE DOCTEMPLATE(HELLO) GROUP(SAMPPDS)
TEMPLATENAME(HELLO) DDNAME(HTML) MEMBERNAME(HELLO)
APPENDCRLF(YES) TYPE(EBCDIC)
This covers same basic material but the document template will now cause CICS to load the PDS member called HELLO from the PDS with the DDNAME HTML. That takes care of the web page the next step is to load the style sheet and the JavaScript.
The style sheet will alter the color of the text on the page. The style sheet looks like this:
P.special {
color : green;
border: solid red;
}
Upload the style sheet to the .CSS PDS. Next we need a URIMAP that will allow the relative link in the web page to succeed.
DEFINE URIMAP(SPECIAL) GROUP(SAMPPDS)
STATUS(ENABLED) USAGE(SERVER) SCHEME(HTTP) HOST(mvstech)
PATH(/samplepds/css/special.css) ANALYZER(NO)
MEDIATYPE(text/css) CHARACTERSET(iso-8859-1) HOSTCODEPAGE(037)
TEMPLATENAME(SPECIAL) REDIRECTTYPE(NONE)
Note how the PATH allows references to the style sheet as if it is in a separate folder. The URIMAP instructs CICS to load the document template called SPECIAL.
The document template definition looks like this:
DEFINE DOCTEMPLATE(SPECIAL) GROUP(SAMPPDS)
TEMPLATENAME(SPECIAL) DDNAME(CSS) MEMBERNAME(SPECIAL)
APPENDCRLF(YES) TYPE(EBCDIC)
The document template instructs CICS to load the member called SPECIAL from the PDS with the DDNAME CSS whenever the special.css style sheet is referenced.
In a similar fashion the JavaScript will be loaded. The script will be loaded and executed by the web page. The script looks like this:
function isactive()
{
alert("Javascript is active");
}
The script is loaded with a relative link that refers to the folder called javascript. The URIMAP that will allow this link follows:
DEFINE URIMAP(MYSCRIPT) GROUP(SAMPPDS)
STATUS(ENABLED) USAGE(SERVER) SCHEME(HTTP) HOST(mvstech)
PATH(/samplepds/javascript/myscript.js) ANALYZER(NO)
MEDIATYPE(text/javascript) CHARACTERSET(iso-8859-1)
HOSTCODEPAGE(037) TEMPLATENAME(MYSCRIPT) REDIRECTTYPE(NONE)
The URIMAP instructs CICS to load a template called MYSCRIPT whenever the highlighted path is in a reference.
The document template definition follows:
DEFINE DOCTEMPLATE(MYSCRIPT) GROUP(SAMPPDS)
TEMPLATENAME(MYSCRIPT) DDNAME(JSCRIPT) MEMBERNAME(MYSCRIPT)
APPENDCRLF(NO) TYPE(BINARY)
The document template will instruct CICS to load the script from the MEMBER MYSCRIPT and the DDNAME JSCRIPT whenever this script is referenced.
This is the most simple example that I could get together to demonstrate everything that I wanted to show.
The files used in this demonstration will be attached to this note.