IBM Student Mainframe Challenge

Part ThreeTime to complete – about ten hours

Help

You might find the following references useful when completing the tasks:

z/OS v1.11 Information Center:

http://publib.boulder.ibm.com/infocenter/zos/v1r11/index.jsp

WebSphere MQ v7 Information Center:

http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp

WebSphere MQ MA95 Support Pac User's Guide:

ftp://public.dhe.ibm.com/software/integration/support/supportpacs/individual/ma95.pdf

I'm very pleased with what you've done so far!You've picked up all the mainframe skills you

needed, and you're proving very useful to theorder processing team!

In this part of the challenge, we'll be doinga bit of C programming and then working

with the order processing website!I'll give you hints and tips, but this time

it's mostly up to you!

Again, I have some questions to test yourunderstanding of z/OS and the differentproducts our company is using. This time

I'm not looking for the fastest contestants,but the ones who produce the highestquality output. Bear that in mind as you

answer the questions and complete tasks!

Install a VPN

If you're using Windows...Go to http://swupdate.openvpn.org/community/releases/openvpn-2.2.1-install.exe and download the OpenVPN GUI for Windows V2.2.1. Install it by running the .exe file and following the installation instructions.

If you're using a Mac...Go to http://cid-c7f3c195a6258847.skydrive.live.com/browse.aspx/Public and download Mac_OpenVPN.dmg. This is a Mac OS X Disk Image file. It contains:

• A version of Tunnelblick (an Open VPN GUI) that has been modified by upgrading the OpenVPN binary from 2.0.9 to to 2.1rc12. This fixes a defect which prevented Tunnelblick from connecting to our mainframe.

• A read-me file that describes how to install Tunnelblick and get started.

If you're using Linux...Go to http://openvpn.net/index.php/open-source/downloads.html and download the OpenVPN 2.1_rc21 source, then find instructions for installation on different Linux distributions at http://openvpn.net/index.php/open-source/documentation/howto.html#install

Unzip and install your security certificate

When you receive your new userid and password, you will also receive an attachment containing your

security certificate. Rename the attachment to have a .zip extension and then unzip it. If you didn't

receive the attachment, get in touch with matt_kockott_2003@hotmail.com on MSN and he'll send it to

you.

If you're using Windows...Unzip the file and run install.bat

You must have Administrator access to your Windows environment. This is because

OpenVPN needs to add routes on your machine during the connection. If you don't have

Administrator access, please take a look at this article:

http://openvpn.se/files/howto/openvpn-howto_run_openvpn_as_nonadmin.html

If you're using a Mac...The read-me file in the disk image you downloaded above should contain everything you need to know about setting up and installing your security certificate on Mac OS X

We'll be using a different mainframe systemin this part of the challenge, so first I'll tell

you how to use that security certificate wee-mailed to you. We also sent you a newuserid and password, make sure you use

that instead of your old one!

If you're using Linux...Copy the *.key, *.crt and *.ovpn files you received to /etc/openvpn. Then edit the

*.ovpn file to add the correct path (/etc/openvpn) to the beginning of the file name

already specified for the ca and key settings. The command:

openvpn --config /etc/openvpn/server.ovpn(for example) should then start it up.

Additionally, you must be sure that your firewall is accepting outgoing connections to the following IP addresses/ports for the OpenVPN connection:

Subnet: 129.35.161.0/24Ports: 1194 and 1195Protocols: TCP and UDP

Configure your emulator to connect to the new system

The Host IP Name is 10.3.20.6 and the IP Port is 23.

➔ Log on to TSO

If you are using the emulator for Windows, the trial license may have expired. You can

use the following key to reactivate it:

Marist College Student License844E6D2164

Are you ready to get started with Part Three?

If you're having any system problems, you cancontact matt_kockott_2003@hotmail.com on MSN.

He's great at fixing things – if he's at his desk!He'll help you log on, but he won't give you

any tips about the tasks.

If you get disconnected and can't log back on because your userid is still in use, this procedure may

help:

Put the following command in a file (for example cancelLogon.txt)

/*$VS,'C U=ZCONxxx' (where ZCONxxx is your new userid)

Then log into an FTP session at 10.3.20.6 and enter these commands:

quote site filetype=jesput cancelLogon.txt

This will send the command in the file to JES, which schedules jobs on the mainframe. You should then

be able to log onto the mainframe again.

GETTING STARTED

In Part Two, you were given some questions to answer while you completed the various tasks. In this

part of the contest, there is a further set of questions to tackle in exactly the same way. Once again,

these are available in a question and answer sheet in the sequential data set called

ZOS.CONTEST1.ANSWER.SHEET.

➔ Using ISPF create a copy of this data set called ZCONxxx.ANSWERS with the same

attributes as the original data set.

You will be advised when you should be able to answer each of the questions, but please read the

comments at the top of the answer sheet carefully before proceeding.

➔ Fill in your z/OS userid (i.e. ZCONxxx) in the space provided above question 1.

If you've forgotten how to do this, refer backto what I told you in Part Two!

AUDITING ORDERS

The CICS transaction was used to view and update the status of orders as they were processed by the

company's staff. As a result of a number of complications with customer orders, the company has

decided that they must keep an audit trail of when orders are updated, and by whom. Although the

audit information could be kept in the same database, the company has another program that they

already use to keep similar data for their accounts, and so they have decided to use WebSphere MQ to

connect the two systems together. The CICS transaction has been updated to put a message onto a

queue every time an order update is attempted. The audit records can then be periodically retrieved

and imported to their auditing application.

In Part Two you saw how we tracked customerorders – using a CICS transaction and a DB2

database. You had to fix some orders becausethey had been changed by accident. I'd like

you to put in place some auditing so we can seewho is making all these mistakes!

In this part of the challenge, we will use JCL to run a batch application, and then make some changes

to that application. The batch application is written in C, and can be used to browse messages on the

audit queue.

Introduction to WebSphere MQ

WebSphere MQ is IBM's premier messaging product. It can be used to send formatted data,

in the form of messages, between disparate applications via an asynchronous message

delivery mechanism. These applications can be written in different programming languages

and be running on different hardware and operating systems. Being able to connect these

applications together can save customers a lot of time and money!

Messages are placed on queues in storage, so that programs can run independently of each

other, at different speeds and times, in different locations, and without having a logical

connection between them. WebSphere MQ allows multiple and interchangeable applications

to access the same, or different, queues, which can help customers to develop a flexible and

scalable infrastructure that includes redundancy, and thus reduces the risk of failure.

Many of the largest companies in the world have WebSphere MQ at the very heart of their

business.

Running the audit queue browsing application

➔ Use ISPF to create two new PDSEs called ZCONxxx.PRTTHREE.JCL and

ZCONxxx.PRTTHREE.C.

They should be allocated in tracks (TRKS)

They should have a primary quantity of 1 and a secondary quantity of 1The record format should be FB (fixed block) and the record length should be 80The block size should be 32000The data set type should be LIBRARY

➔ Create another PDSE called ZCONxxx.PRTTHREE.LOAD

It should be allocated in tracks (TRKS)

It should have a primary quantity of 1 and a secondary quantity of 1The record format should be U (undefined) and the record length should be left blank

The block size should be 32000The data set type should be LIBRARY

Your first task is to compile and run the application. The jobs to build and execute it are in members

BLDAUDIT and RUNAUDIT of ZOS.CONTEST1.JCL.

The application source is in the member AUDITAPP of ZOS.CONTEST1.C and will need to be copied in

to your C data set before you attempt to compile the application.

➔ Copy the application source in to your C data set.➔ Copy the jobs in to your JCL data set.➔ Substitute the place-holders in the jobs – the queue manager is called MQ04 and the audit

queue is named SALES.AUDIT.

➔ Compile and run the audit queue browsing application

➔ Fix the RUNAUDIT job to resolve the JCL error.

You should know by now that nothingaround here ever works first time!

WebSphere MQ has been set up to restrict access to the audit queue, so that only the company's

auditors can remove messages from it. Unfortunately, the AUDITAPP application is requesting access

to destructively get messages from the queue when it attempts to open it, and is therefore being

denied access.

➔ Fix the AUDITAPP application so that it browses the messages on the audit record

queue instead of trying to remove them.

The application should now be running successfully.

There are two additional parameters supported by the application: -f to display only the audit failures,

and -o <order number> to display only the audit records for a particular order.

➔ Run the application with -f as an additional parameter

You'll need to change both the MQOPENand MQGET function calls so that you onlyrequest browse access to the queue whenyou open it, and so that you browse each

message on the queue in turn.

When a message is put onto a queue, you can give it a unique message identifier, or request that one

be created automatically for you. This allows you to retrieve that specific message at a later date.

Messages can also have a correlation identifier, which can be used to represent a relationship between

multiple messages.

Although we are not interested in the message identifier in this instance, the messages on the audit

queue have had their correlation identifier set to the order number to which they relate. If we place

the order number in the message descriptor before we issue an MQGET, WebSphere MQ will only look

for messages that match this, and ignore the remaining messages on the queue.

The code to handle the -o parameter hasn'tbeen implemented properly yet – but I knowof a feature in WebSphere MQ that can do

the work for us!

The correlation identifier is 24 bytes long. To represent an order number in this field we treat it as a 24

digit number and store it as an EBCDIC string (each character in the string occupies 1 byte).

For example, the order 12345 would be represented as 000000000000000000012345.

➔ Update the C application so that if a non-zero order number is specified, it only browses messages on the queue with a correlation identifier matching that order.

C programming tips

To convert a C number (int) into a fixed length character string with leading zeros, you can use the

following sprintf statement:

int myNum = 24;char myString[10];

sprintf (myString, “%0*d”, 10, myNum);

The contents of myString are "0000000024".

➔ Now answer questions 1 and 2.

Each order can have multiple audit records,so make sure all of them are displayed bythe application and not just the first one!

This is looking good! I'll review your applicationalongside the answers to your questions, so

please make sure you're happy with yoursolution before you continue!

CREATING WEB PAGES

Overview

In this section, we will introduce IBM HTTP Server and create a couple of web pages for the Sports

Marketplace company. Instead of using static HTML files the web pages will be generated by Common

Gateway Interface (CGI) scripts, written in REXX, and will use WebSphere MQ messages to drive a

CICS transaction that interacts with DB2 to allow an end user to place, view and cancel product orders.

The CGI scripts used by IBM HTTPServer are stored in a UNIX filesystem

mounted on the mainframe. Thisis also where the configuration files

for IBM HTTP Server are kept.

Introduction to UNIX System Services (USS)

The UNIX System Services (USS) element of z/OS is a UNIX operating environment,

implemented within the z/OS operating system. The interface will be familiar to anyone who

has experience of using UNIX.

The z/OS UNIX file system, like other UNIX systems, is a hierarchical one. Files are

members of a directory, and each directory can in turn be a member of another directory.

The highest level of the hierarchy is the root directory. Your home directory in USS is located

at /u/zconxxx. This is where you should create any files that you need to complete this

task.

Although you do not deal directly with data sets from within USS, the content of the USS file

system is actually stored in a number of data sets that are each mounted at a certain point

in the hierarchy by the system administrator. There are two special types of data sets for this

purpose - HFS (Hierarchical File System) and zFS (zSeries File System). For example, the

HFS file system ZCONxxx.HFS is mounted at /u/zconxxx, and contains all the data stored

under your home directory.

Logging on to USS

There are two ways of entering USS. The first is to use Telnet to connect to the system.

To log on to USS using this method, use a Telnet client (such as PuTTY for Windows) to connect to

10.3.20.6 port 1023. When you log on you will see a copyright statement followed by the command

prompt.

To log off USS type exit.

Editing files in USS

To edit files in USS when you have logged in using Telnet, you can use the vi editor. This is a

commonly used editor on UNIX systems and you may already be familiar with it. However if you are

not, don't worry as you'll only need to know the basics in order to complete this task.

To start editing a file in vi enter vi <filename> on the command line. If the file doesn't exist

already, it will be created for you.

The vi editor has two modes – command mode and insert mode. Command mode allows you to enter

commands to manipulate the text in the file, while insert mode allows you to type text into the file.

When you start vi it will be in command mode.

The most common ways of getting into insert mode is to type either i (to enter text at the cursor's

position) or o (to start a new line) while in command mode. Anything you type will then be inserted

into the file. To return to command mode, use the escape key.

These are some useful commands that can be entered while in command mode:

:q! Exit without saving

:wq Save and exit

:w Save (without exiting)

D Delete the rest of the line after the cursor

dd Delete the entire line

:nn Move the cursor to line nn

uu Undo last action

The other way to enter USS is to enter the TSO OMVS command in ISPF. You will have to exit OMVS to

run other ISPF commands, but if you find it difficult to edit files with vi, you may want to enter USS

using this method as it allows you to edit files with the ISPF editor you have already used.

To edit a file enter oedit <filename> on the OMVS command line. This will open the file in the ISPF

editor.

➔ Now answer questions 3 and 4.

There are loads of tutorials and referencesites for vi on the Internet – it was (and

still is) a very popular editor!

INTRODUCTION TO IBM HTTP SERVER

IBM HTTP Server on z/OS provides a web server environment for scalable, high performance web

serving applications that you can access from a web browser. It allows web pages written in HTML, or

generated by programs (CGI scripts), to be served to web browsers.

Starting and Stopping IBM HTTP Server

IBM HTTP Server runs as a z/OS started task, which you can consider to be like a system

service. A started task uses JCL in exactly the same way as a batch job but does not get run

by an initiator – it is run immediately as a result of a START command. Started tasks run

under a pre-configured userid, are generally used for critical applications, and are often

started automatically when a z/OS system is IPL'd.

Carlos has set up an instance of IBM HTTPServer for you, and you'll need to customise

it to complete this part of the challenge.The name of your server's started task isWEBSxxx – where your userid is ZCONxxx

The JCL for a started task is located via a data set list known as the procedure library (PROCLIB). The

JCL for your HTTP server is defined in a member called the same name as your started task, and can

be found in the PDS called CENTER.PROCLIB.

Before you can start your HTTP server you will need to copy a couple of files that the started task JCL

refers to into your USS home directory. Issue the following commands in USS to copy the files to your

home directory.

➔ cp /etc/web.conf ~/web.conf➔ cp /etc/websrv.envvars ~/web.env

The tilde character (~) can be used as an aliasfor your USS home directory (i.e. /u/zconxxx)

The web.conf file specifies configuration information for the HTTP server, including which

files you wish to serve and how you wish to serve them. The web.env file can be used to

specify the environment variables that should be defined for the HTTP server.

➔ Issue /S WEBSxxx from within SDSF

You should then be able to see it running via Display Active Jobs (DA). If you look at the output

for this job you should be able to see two messages:

IMW3534I PID: <process id> SERVER STARTING IMW3536I SA <process id> 0.0.0.0:8xxx * * READY

The 8xxx identified in the IMW3536I message is the port number that you can use to connect to your

HTTP server.

➔ Go to the following address in your web browser: http://10.3.20.6:8xxx

Now you've created those config files inyour home directory, you should be able

to start your HTTP server!

We'll have a closer look at the config fileslater on.

We will now make some configuration changes and so first let's stop your HTTP server.

➔ Issue the command /P WEBSxxx from within SDSF

You should see the HTTP server's job end after issuing the following messages:

IMW3540I SA <process id> 0.0.0.0:8xxx * * STOPPING WORK IMW3541I SA <process id> 0.0.0.0:8xxx * * TERMINATING NOW

Is it displaying a basic confirmation page?Awesome! Your server is running!

Configuring IBM HTTP Server

Take a moment to look at the documentation for HTTP Server in the z/OS Information Center, including

Appendix B which details the configuration directives that can be used in the web.conf file you copied

earlier.

➔ Copy /etc/contest1/htdocs/ and everything underneath it to /u/zconxxx/htdocs/➔ Similarly copy /etc/contest1/cgi-bin/ to /u/zconxxx/cgi-bin/

I can give you a template home page,stylesheet and a couple of CGI scripts I

wrote in REXX. They'll need a bit of work...

Use cp -R <source> <dest> to copy everything!

Edit your web.conf configuration file so that your HTTP server serves content from your htdocs directory instead of content from /etc.

Restart your web server and check that your home page now displays the following:

Now update your configuration file again so that http://10.3.20.6:8xxx/store/scriptname executes the REXX script called scriptname in your cgi-bin directory (where scriptname can be

anything). Further to this if scriptname is omitted, the vieworders script should be run.

➔ Update your configuration file.

Restart your web server and check that you get the following:

➔ Now answer question 5.

CORRECTING THE CGI SCRIPTS

The RXMQxxx functions are provided by the MA95 MQ-REXX Support Pac. This provides support for

calling WebSphere MQ from with REXX programs, such as the CGI scripts that you have copied into

your cgi-bin directory. Unlike C, REXX is not a strictly typed language and so the MQI structures,

such as the message descriptor (MQMD), are represented using REXX stem variables. The Support Pac

also abbreviates the names of the structure fields but you should be able to identify which ones they

are.

The RXMQINIT function cannot be called because z/OS does not know where to load MA95 from when

running the vieworders CGI script. z/OS loads modules from a number of locations, but the data sets

to search for modules are typically specified in JCL with a DD (data definition) called STEPLIB. In

UNIX, the equivalent of STEPLIB is usually an environment variable called LIBPATH (or

LD_LIBRARY_PATH). In USS, you use an environment variable called STEPLIB to specify data sets

outside the hierarchical file system.

➔ Change the definition of STEPLIB in your web.env file to specify the following list of

data sets to look in to find load modules – you can delete the existing value of CURRENT.1. WMQ.V701.SCSQAUTH

2. WMQ.V701.SCSQANLE

3. WMQ.MA95.LOAD

➔ Restart your HTTP server and check that the RXMQINIT function can now be loaded.

You should now find that you get a different error, indicating that you are not authorised to connect to

the MQ04 queue manager. If you look at the top of the generated web page you should see that you

are logged in as a user called PUBLIC. This is because HTTP Server has been configured to run under

this userid in its configuration file.

When you shop online, you normally have to create an account on each site so that the online retailer

knows who you are, where to deliver your orders to, and how to bill you. The website that you are

setting up for the company is a development prototype to test their backend processing and drive

transactions, and so we do not need to configure accounts in the same way. To keep things simple, we

will use your z/OS userid and password to log in to the website instead.

Those first two datasets are used to loadsupport for WebSphere MQ, and the third

is for the MA95 Support Pac.

➔ Change HTTP Server to prompt for a z/OS userid and password when you go to the website, instead of logging you in as the PUBLIC userid.

You should then see that the web page reports the user id that you are logged in as, and that you now

encounter an error opening the request queue instead.

At this point you'll want to set permissionson your home directory (/u/zconxxx) to 700.

Use the chmod command!This is to prevent other students taking part

in the challenge from seeing the changes you're making to your scripts!

Security on z/OS

Security Server (RACF) is an optional feature of z/OS and lets you control access to

protected resources. Security Server maintains information about who has access to which

resources and what level of access they have – it is not responsible for securing the system

itself. The various components of z/OS and other z/OS applications or services, such as

WebSphere MQ, implement security by using an application programming interface (API)

that communicates with Security Server. Whenever you wish to access a resource, such as a

data set, or attempt to issue a command, Security Server can be asked whether you are

allowed to do the action that you are attempting to perform.

For example, the WebSphere MQ queue manager, MQ04 checked with Security Server and

determined that the userid called PUBLIC should not be allowed to connect to it, but that

access for your userid has been granted. Similarly, in the first section of this part of the

mainframe challenge, Security Server reported to WebSphere MQ that you were allowed

access to browse the audit queue, but not remove messages from it.

Security Server maintains this information using named profiles that represent one or more

resources. Users or groups can then be associated with these profiles to identify what level

of access they should have, be it read access only or the ability to perform updates as well.

There are other levels of access, including no access at all, which is usually the default.

➔ Now answer questions 6 and 7.

Before we correct that error with your requestqueue, let's make a slight digression and take a

brief look at security on the mainframe.

Setting up WebSphere MQ

To rectify the error opening the request queue, we need to define it on the MQ04 queue manager. This

queue is used by the REXX CGI script to send a message to a CICS transaction, which will in turn

access DB2 to select information about the orders that have been placed.

WebSphere MQ provides ISPF panels to help you administer queue managers. These can be found

under IBM Products - WebSphere – MQ.

You should be presented with a screen as below:

➔ Define your request queue

Remember you can press the PF1 keyon any panel to get context-sensitivehelp about the field your cursor is on!

The queue should have the following properties, so that when your request messages are placed on it

the CICS transaction is automatically run to process it for you.

A trigger message should be generated every time a message is placed on the queue.

The trigger message should be placed on the CICS01.INITQ initiation queue.

The name of the process to call is WEBPRT3.

To understand triggering in WebSphere MQ, see the topic entitled 'Starting WebSphere MQ applications

using triggers' in the WebSphere MQ Information Center. You can find this topic in the Application

Programming Guide under 'Writing a WebSphere MQ application'.

The REXX CGI script uses a second queue to receive replies for the requests that it sends to CICS. This

queue doesn't need any special attributes set – the standard defaults are sufficient.

➔ Define your reply queue appropriately

You should then find that your web page is generated successfully and displays an empty table because

you have not yet placed any orders.

➔ Now answer questions 8 and 9.

Placing Orders

To place an order, you can use the CGI script called neworder, which can be run in exactly the same

way as vieworders.

➔ Fix the first error that is preventing the request queue from being opened successfully

You should now find that the products on order can be correctly retrieved, but none of the prices have

a decimal place. For example, the book called Soccer Greats is actually on sale for 9.99 GBP, not 999

GBP.

➔ Correct this so that a decimal place is inserted before the last two digits of each price.

➔ Place a few orders for products to test that the orders are displayed correctly.

➔ Now answer questions 10 and 11.

This script has bugs too...

… but you've nearly finished!

That's brilliant! We'll deploy your siteinternally and run it for a few weeksto gather feedback from members ofthe team. If what you've made works

well, and you've answered the questionscorrectly, you'll be in the running to win

the main prize!

COMPLETING THE MAINFRAME CHALLENGE

You should ensure that your auditing application works correctly, and your web site looks right and lists

some test orders. These will be checked for correctness and deployed in due course!

If you're looking for a graduate job, why not consider applying to IBM's labs? They're

currently hiring more graduates than ever before!

http://www.ibm.com/start

Once you have completed the web page, reviewyour answers to the questions and leave youranswers data set where it is so I can check it.

Congratulations! You've done a fantastic job!our customers will be pleased, and you've

gained a good amount of mainframe experience!

I hope you've enjoyed your experienceon the mainframe in the IBM Student

Mainframe Challenge!

We'll be in touch!