Turning zFS files into web sites in 3 easy steps - using explorer connection file as an example
JoeWinchester 110000DQA0 Visits (1948)
When the web was first created its goal was to store and link documents for scientists to browse without having to go into dusty libraries. The way this occurs is that each web address is unique and points to a file somewhere on a server. What this blog is going to show is how to turn zFS files into web addressable documents using a CICS region. Because this blog is about the z/OS Explorer I'm going to use this in the context of the scenario to host a connections.pref file containing a list of z/OS and CICS systems. In its own this is pretty cool because it allows the list of hosts and ports for explorer connections to be maintained centrally and stored on z/FS and each user to be able to have the most "up to date" list by pointing their explorer workspace to the web address that routes to the z/FS file. I put the catchy "3 easy steps" on the blog title to try to show how easily this can be done, so I'm going to avoid too much waffle and chit chat (for now) and stay focused on the task at hand.
Step 1 - Choose a file that you want to share
This is the easy part - the file I want to share is called connections.pref and it's a list of connections I made using the CICS Explorer to a bunch of systems. I want to share this file with my friends and hosting it on z/FS, using a CICS region to turn this into an http:// address, and then having my friends point to this is my goal for the next few minutes. If you want to learn more about z/OS Explorer connections then there's a bl
I'm going to put the file into a directory called winchj (that's me) beneath a directory called wakelin (which belongs to Phil - cheers Phil - I owe you a donut). To get the file contents into zFS I can use the z/OS Explorer view to create the file and then I pasted in the contents from my clipboard.
I like pictures, and I like the z/OS Explorer, so to combine these two here's a picture of the file showing it in z/FS.
Step 2 - Create a TCP/IP service in a CICS region that defines the post you're going to use
Now that we have our file in z/FS we need to create two CICS resources to turn it into a web address that folks can point to. The first of these is a TCP/IP service and it is used to specify the port that we're going to use - I've chosen 65432 because it's easy to remember. To create a TCP/IP service we need to create a TCP/IP service definition and set the port attribute to 65432. I've also changed the socketclose value to be five seconds - the default is zero and making it larger gives the CICS region more time to get its act together and retrieve the file before it issues a timeout. More about timeouts later in the helpful "troubleshooting" section at the end of the blog.
Again - because pictures are cool and CICS Explorer is cool - how cool would it be if we had a picture of the CICS Explorer and the TCP/IP service definition showing the values that we've changed from their defaults ?
If you've not created a a TCP/IP service definition in the CICS Explorer before, use the New TCP/IP Service Definition wizard from the File -> New -> Other menu, or on CICS Explorer 5.1.1 type New TCP/IP into the Quick Access box on the title bar.
The definition can be in a CSD or a CPSM Data Repository - however nothing is going to happen until we install it - something you can do from the twisty on the top of the editor which will bring up the equivalent of doing a right mouse click pop-up menu from a TCP/IP Service Definition in the definitions view. Now we have a TCP/IP service that says "hey - I'm listening on port 65432" and we have a file in z/FS.
The third and final step is to link the two - something that is done by creating a URI map resource.
Step 3 - Create a URI Map in the CICS region that points to the TCP/IP service and has a type of zFS
The URI map is defined and installed into the same CICS region that the TCP/IP service was installed into. You can think of the URI map as a kind of glue - it points to the path of the zFS file - it points to the TCP/IP service - and it also specifies the web address that you're going to tell folks to access the file through.
There are three attribute that we need to set on the URI Map definition to achieve this:
HFS File: This does what it says on the tin - it's the location of the file that we want the web address to point to. Earlier we put our connections.pref file in the directory /wakelin/winchj so this is the path we're going to specify. Note the leading / in the path name - if we got this wrong we'd get a 404 file not found.
Path: This is the trailing part of the web address - which will be cics
Tcpipservice: This points to the TCP/IP service that we created earlier that specifies the port. We called this JOE01 so that's the value we enter.
For the host attribute we could have entered a web address, such as "joe
Install the URI Map and that's all. Everything is done !!!
We should probably test it though - open our favourite browser and enter the IP address of the CICS region and the port of the TCP/IP service and we'll see the connections file.
You can then add this as a connection import link in the Host Connections view of a CICS Explorer of everyone you want to share the connections with.
If you manage to do this first time give yourself a huge pat on the back (or get a friend to do it - I've always wondered how you can pat your own back) - or better still buy you and your friend a donut and a latte and enjoy some quality time together playing cards or swopping stories about funny things that your pets have done recently.
If however something went wrong - then you'll need to read the helpful "troubleshooting" bit below.
Sorry to hear you're reading this section and things didn't go perfectly first time. No worries - they didn't for me either when I was creating the data for this blog article - so you're in good company. Let's take a look at what went wrong.
When you created the TCP/IP service for port 65432 and connected to it - did you get a page like this ?
If so then what happened is that port 65432 was reached on your CICS region - but the URI map was either not installed, or the path statement in the URI map wasn't a / character. The 404 CICS URL not found message is the TCP/IP service accepting the request - but when the CICS region tries to match the path, in our case nothing so it's a / statement on its own, it doesn't find a URI map so it returns the helpful error message above.
If you didn't even get this far, and the browser says "I can't find this page" - in much the same way as if you'd entered "Joe
If the TCP/IP service is installed - and the URI map is installed OK - then it's possible that CICS was unable to actually get the file specified in the HFS path attribute of the URI map. One of these reasons could be that the socketclose attribute on the TCP/IP service was left at the default of zero and the request timed out. I tend to be forgetful and often don't increase this value and get a 408 response, so if this happens just close and disable the TCP/IP service - increase the number of seconds on the TCP/IP service definition and reinstall it.
The most common error is probably security - where the user ID that the CICS region is running under doesn't have sufficient permission to access the file on zFS. When you first see a 403 Not Authorized you might think "hey - it's me the user of the browser that isn't powerful enough to access stuff" - however that's not the case - it's the CICS region trying to get at the zFS file and failing.
The CICS region's user ID needs authority to read and execute not only the file itself - in our case connections.pref, but also all of the parent directories. We pointed the URI map at /wak
If the users are different - which they are in my case because the region's job is running under the user ID MQTEST, then if the security manager has WINCHJ and MQTEST in the same group then the Group permission would be checked.
If you don't know the user ID that a region is running under - the z/OS Explorer's Jobs view shows you this against the job (which has the same name as the region) in brackets. You can select the job and we'll show more stuff in the properties view including the user ID, however we think that the user ID is such a useful attribute to see we helpfully show it in brackets after the active job's name. (Note that expanding the job shows the steps which you can open - this is because I'm using z/OSMF and therefore don't need to use the more traditional SDSF command to see the region's spool - more about that in a later blog).
If the owner of the zFS file or folder isn't in the same security group as the user of the CICS region, then the check is done against the other set of permissions.
That's it I think. To recap - you put the resource you want to publish through an http:// address into a zFS file. You make sure that the file and its parent directories all the way up to root have their permissions such that the CICS region you're going to use to surface the file through have read and execute permission. You create a TCP/IP service with the port number you want to use and a timeout that's > the default of zero and install this and make sure it's open. You then create a URI map that points to the TCP/IP service and also points to the zFS file and also has the path statement to match the trailing part of the web address you want to use - / is a good default as it means that it's just IPaddress:port.
I hope this makes sense - in a future blog I'll show how you can surface much more than files through a CICS region - including an actual CICS Explorer instance itself using Java Web Start. This is really cool - and it's a beautiful way to deploy the CICS Explorer itself to end users without having to worry about desktop installs or using shared network drives which can suffer performance issues across slow connections.