Skip to main content

URIMAP appreciation: Using relative links in a CICS Web application

No replies
Corneel
Offline
Joined: 2006-03-07

 

 

URIMAP appreciation Using relative links in a CICS Web application

 

Introduction

Relative links

Moving the web application to CICS

The last word

 

 

Introduction

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 of us that are not using HFS to store web pages yet.

 

Finally, this example will demonstrate the flexibility of the URIMAP definition that is available since CICS TS3.1.

Relative links

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". Let's 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.

 

Moving the web application to CICS

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.

 

  • If any user requests a page that has a URL of  “/samplepds/Hello.html" this URIMAP will provide the information to CICS of what to load.
  • CICS will follow the instruction of the URIMAP and load the document template called “HELLO".

 

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.

 

The last word

This is the most simple example that I could get together to demonstrate everything that I wanted to show.

 

  1. The URIMAP is a powerful tool that allows CICS developers to keep the links or references in web pages as they are. This is very important for maintenance purposes.
  2. Relative links are not an option, it really is the only way to design a professional looking web application.
  3. It is possible to use multiple locations to store web artifacts‚ whether PDS datasets or HFS locations.

The files used in this demonstration will be attached to this note.

 

 

 

AttachmentSize
Readme.html.txt17.29 KB
Hello.html.txt286 bytes
CSD.txt1.24 KB
CICSJCL.txt114 bytes
special.css_.txt54 bytes
Rename_to_myscript.js_after_copy.txt58 bytes