In this assignment we will learn how to develop business transactions on the IBM CICS transaction server. We will also learn how to interact with an IBM z/OS system. IBM z/Os is the most widely used mainframe operating system. Majority of the banks and large enterprises around the world have deployed CICS on z/OS (or its predecessors) as a reliable business transactions processing infrastructure. Thus, it is of critical importance to know how transactions for CICS on z/OS can be developed.

1. Prerequisites

We have been provided with accounts on z/OS 1.7 with CICS 3.1 at Marist college. Here is the list of your user IDs. Only one member of each group is listed. All group members should share the assigned user ID. The group IDs are to be used later in the assignment to tell your programs apart from other groups.

We will use Vista TN 3270 terminal emulation program to interact with the z/OS. Please download and install the version 1.26. It comes with a free 30 days trial. There are several ways in which we can interact with z/OS and CICS. Let us explore at least two of them.

2. Unix System Shell (USS)

USS provides a unix-like interface to z/OS. USS is mounted as a hierarchical file system (HFS) on z/OS. We can use either Vista or the telnet program from the command prompt to connect to z/OS USS. Our accounts on the Marist system come with USS support enabled. When you login for the first time, you will be prompted to change your password. Note that user IDs and passwords in z/OS are *not* case sensitive, so "abc" is same as "ABC". There are a few things in z/OS that are case sensitive, such as names of the files and directories in HFS and names related to JVM such as class path and class names.

2.1 Connecting via Vista TN 3270

Start Vista TN and in your Vista session dialogue, use these details:

Login with your username and password. You should see a prompt and you can issue the standard UNIX commands to interact with z/OS.

2.2 Connecting via telnet

From the command prompt issue "telnet zos.kctr.marist.edu". At the prompt, supply your ID and password.

2.3 Exploring USS

Let us explore the USS by trying out the following commands. You can do this from both Vista and telnet. Note that in USS, you cannot use command history and have to retype the entire commands. If you are using Windows command prompt, you can copy the previous command (right click mark, select) and then paste (right click paste) it back to save typing.

3. Time Sharing Option (TSO)

TSO is the classical mainframe interface. You must use Vista to connect to TSO. On these screens, if you mistype something, just go back and overwrite it to correct it. The "pause" key clears a screen after a transaction session has ended. As described at the bottom of the screen, "F3" ends a transaction session. Note that in CICS every command is a transaction. Thus, if you end a session at any point, consistency of the system is not compromised. When you see "SEVERE" or "WARNING" at the bottom of the screen while entering information or defining transactions, "F9" will show you the actual message and "Enter" will get you back from the message screen. You can use arrow keys or "tab" key to navigate the screens. When the list of attributes is longer than one screen, you can use "page up" and "page down" to navigate the attributes.
  1. In the Vista session dialog, set the port to 1023 and keep the other settings from USS. You should see the welcome screen of z/OS.
  2. From this screen you can enter the CICS console or the TSO console as described at the bottom of the screen.
  3. Issue "L C001" to enter the CICS console.
  4. Enter your ID and password, leave the other fields blank, and hit "Enter". You should now see a blank screen. This is where you issue transaction commands. CICS picks up the first four letters from the top-left corner to be the name of the transaction. In CICS, all transactions are four-characters long.

3.1 Exploring CICS via TSO

Each CICS transaction invokes a program. The programs may be written in COBOL, C, C++, or Java. We will only deal with Java in this assignment. Each transaction, program, or file is a CICS resource. z/OS organizes resources in groups. Thus, each resource belongs to a group. The resources you define for this assignment should belong to the group IDs we have provided you. Let us try some transactions out at the CICS console.

4. Using FTP to transfer files to and from z/OS

From the command prompt "ftp zos.kctr.marist.edu", enter your user ID and password. Issue "cd /u/your uid". Issue "bin" to make all transfers binary. Use "put" and "get" commands to transfer files. If you are not familiar with FTP, this is a good start.

5. CICS Programming with Java

Please go through Chapters 1 through 6 of [1] for step by step instructions on how to develop and install java programs as CICS transactions. Make a directory under /c001prof named after your assigned group name. We will call this your group directory in the following. Use this directory (instead of the samples directory) for storing your programs. Specifically, it is useful to read these sections:
  1. 1.4.1, 1.4.2: page 27
  2. 2.1: page 30
  3. 2.3.2: page 33
  4. 4: page 55
    1. Our z/OS has CICS 3.1 installed. The redbook talks about CICS 2.3. Set the environment variables accordingly and make adjustments in the following accordingly.
    2. Set and export the requisite environment variables in .profile in your home directory. Next time when you login, they will be set.
    3. Use vi editor from a telnet login to create the .profile. If you are not familiar with vi, this is a good start.
    4. Copy the HelloWorld.mak and CICS examples directory to your group directory.
    5. Modify the HelloCICSWorld program to print a message containing your group ID.
    6. If the "make" program does not work, compile the HelloWorld.java and HelloCICSWorld.java manually by issuing "javac -deprecation -classpath .:$CICS_HOME/lib/dfjcics.jar examples/HelloWorld/your java file.java"
    7. Create your own JVM profile under /c001prof/JVMProfiles named "your_group_idJVMPR". Also create a JVM properties file under /c001prof/props named "your_group_idjvmpr.props". You can start from the DFHJVMPR file and customize it as described below.
    8. Customize the JVM profile.
      • "WORK_DIR": Create a directory "workdir" within your group directory and specify its full path here.
      • "REUSE": Set to "NO". This will ensure that a JVM is created for every program. This is not efficient but it is quite simple and error-prone. See Chapter 2.3 in [1] for the various JVM modes.
      • "JVMPROPS": Point to your own JVM profile.
      • "CLASSPATH": Directory in which your java packages are located.
      For explanation of these and other parameters of the JVM profiles, see Chapter 20 in [3].
    9. Customize the JVM properties file: For now, we do not need any customization to this file. It is a good idea to see what properties are specified in it. For explanation of these and other parameters of the JVM properties, see Chapter 20 in [3].
  5. 4: page 61, "install the required CICS resource definitions"
    1. Use CEDA to define a new program, named after "your_group_idJHE2". Replicate the attributes we saw for the program NVDJHE2.
    2. Use CEDA to define a new transaction named after "your_group_idA". Replicate the attributes we saw for the transaction NVD1.
    3. Use CEDA to install your group.
    4. Use CEDA to check that your group contains your program and your transaction
  6. Issue your transaction and see that it prints your message.
  7. Check the files in your workdir. The CICS JVM logs various events to these files.
  8. If you change your definitions via "CEDA ALTER", you need to reinstall your group via "CEDA INSTALL" for the changes to take effect.
  9. Thats it! You just learned how to develop CICS transactions with Java.

6. CICS Documentation

There is a lot of documentation available on CICS and z/OS. Try googling your topic and look for an IBM redbook that matches your query. Below are some of the redbooks that are central to CICS applications programming.
  1. CICS Java programming guide
  2. CICS resource definition guide
  3. CICS system definition guide
  4. CICS supplied transactions
  5. CICS application programming guide
  6. CICS application programming reference
  7. Java applications in CICS
  8. CICS Web services guide

7. CICS Commands

  1. To display all resources defined in a group: CEDA DISPLAY GROUP (group name)
  2. To install all resources defined in a group: CEDA INSTALL GROUP (group name)
  3. To define a program: CEDA DEFINE PROG(program name) GROUP(group name)
  4. To define a transaction: CEDA DEFINE TRANSACTION(transaction name) GROUP(group name)
  5. To view the attributes of the already defined transactions and programs: "CEDA VIEW..."
  6. To change the attributes of the already defined transactions and programs: "CEDA ALTER..." followed by edits and "Enter"

8. Submission

Once you are done and your transaction is working, do the following to prevent unauthorized access to your directories.
  1. Change the permissions of your group directory to 700. This way, only you can access it. Remember, your CICS transaction will not run when this is done.
  2. Submit a file containing your group name, z/OS user ID, and password. This is the only deliverable. For testing, we will login to your account, open up access to your directory, and run your transaction.
This protects your group directories. Regarding your CICS definitions, all commands issued from the CICS console are logged automatically and violators can be tracked down.