URIMAP appreciation: Using relative links in a CICS Web application

Submitted by Corneel on Wed, 2007-08-01 08:54.


Using relative links in a CICS Web application

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
»