Appendix A – Connecting to the mainframe, Editing, and Submitting Programs

In which we connect to the machine, learn to navigate the operating system, submit a job, and examine the output.

The traditional way to connect to a System/z machine is by using terminal emulation software like IBM’s Personal Communications or QWS3270, or Tom Brennan’s Vista tn3270. With this software, your machine acts like an IBM 3270 terminal connected directly to mainframe. You should also know that there is another way to interact with a System/z. It’s called RDz and presents the user an Eclipse-based interface that even Yukihiro Matsumoto could appreciate. If this is your first experience on mainframes, start with a terminal emulator to learn some basics, and move to RDz later.

RDz on Z

Ramping Up This chapter is designed to get you up to speed quickly by tackling a sample working program. I’ll show you how to get on the system, examine the first program with an editor, submit the program, and review the results. You’ll need some 3270 terminal emulation software like IBM’s Personal Communications, or Vista tn3270. You’ll also have to configure your software with the target machine IP address and port number. After connecting with the terminal emulator, the first mainframe screen I get looks like the one below. Your opening screen will be different depending on your mainframe connection:

From this screen I typed “TSO” and was queried for a user ID and password. After typing these and pressing Enter, the screen below appeared.

Typically, you will see a list of information messages about the machine fly by. We will ignore these and move forward by pressing Enter whenever we see the *** prompt. Finally, we will arrive at the ISPF Primary Options Menu.

You might be wondering: What does ISPF stands for? It’s an acronym for Interactive System Productivity Facility. Dreadful name, isn’t it? Your screen might appear with a different set of numbered options. Companies can customize these ISPF panels to fit their specific needs, but for most mainframes, the first six options are pretty standard. Let’s take a moment and begin to get our bearings as we learn how to navigate the system. There are a few things you need to become aware of if you’ve never worked on a mainframe: 1) Each screen is a combination of protected areas and unprotected fields. 2) You can’t see where protected and unprotected fields start or stop. 3) If you use an arrow key to move the cursor to a protected area, pressing the Enter key will

cause the keyboard to lock. As a result, try not to use the arrow keys or the mouse as the main method for navigating a screen.

4) When the keyboard locks, you must press the system attention key to unlock it. On my

computer this is the Escape key, but this can vary depending on how your 3270 Emulator maps the keyboard. You can change the mapping within your emulator.

5) The easiest and most reliable way to move around a screen is by pressing the Tab key.

Tabbing will move you from one unprotected field to the next.

6) ISPF is a menu-driven system where selecting an option leads to another panel. The collection of panels forms a tree.

7) Pressing the F3 key moves you up one level in the menu tree. 8) A specific panel can be named by a sequence of option numbers (the numbers you would

select to get to the panel from the Primary Option Panel) separated by periods. For example 3.2 is the Data Set Utility Panel.

9) You can navigate directly to a specific panel by typing “=” followed by the sequence of option

numbers (separated by periods) in any unprotected field. For example, if you are on the Primary Option Menu, and move to the Option line, typing =3.2 will carry you to the Data Set Utility Panel. You could also get there more slowly by choosing 3 on the Option line, pressing Enter, choosing 2 on the Option line, and pressing Enter again.

10) You can return to the Primary Option Menu by typing =. (equal followed by a period) from any unprotected field. Pressing F3 several times will also return you to the Primary Option Menu.

11) If you press F3 from the Primary Option Menu, you will return to TSO where you will see

the word “Ready”. Arriving at TSO (Time Sharing Option) is sort of like being at a DOS prompt in windows. ISPF is a product that runs on top of TSO and makes life a bit easier by presenting the user a series of panels. Typing ISPF from TSO will carry you back to ISPF which is where we want to work.

12) Resist the urge to use your mouse too often (I know, it’s hard). You can make it work, but

grabbing the mouse will ultimately slow you down in many situations. Stick with Tabs and occasionally the arrow keys.

13) The terminal has its own memory where your keystrokes are recorded. The data you type is

saved in the terminal’s memory but not transferred to the mainframe until an attention-getting key like Enter is pressed. At that point, a whole screen full of information is transferred to the mainframe and another screen is typically returned to you. Keep in mind that the mainframe can support thousands of sessions concurrently. For efficiency, it only connects to a terminal when absolutely necessary. This works sort of like an HTML screen where you fill out a form and then press Send. Mainframes had this sort of server scheme worked out long before the internet was conceived – in the mainframe world it’s called CICS.

Whew! That was a long list. In order to get started, we will need to create a library in which we can store the programs we create. An IBM library is called a PDS (Partitioned Data Set) or a PDSE (Partitioned Data Set Extended). Both types of libraries are “partitioned” into two parts: 1) A directory of the “members” the library contains, and 2) The storage for PDS/PDSE members. Let’s create a PDSE. Navigate to the Data Set Utility panel by typing =3.2 and pressing Enter. That will take you to the Data Set Utility panel:

We need to allocate disk space for the PDSE, so enter your user ID in the Project field – my ID above is CSUP004. Most installations require that the high-level qualifier of every dataset you allocate must begin with your user ID. The operating system can use this as a security measure, preventing you from deleting and allocating datasets that don’t belong to you. You will also need to make up a Group name and a Type name. These names allow you to organize the work you do, so choose names that make sense to you. All three names are combined to form the name of the PDSE. My PDSE above would be called CSUP004.SOURCE.ASM. To create the PDSE, type A on the Option line and press Enter.

You should be taken to the Allocate New Data Set panel, but the entries above will be missing. The Volume Serial field you supply will depend on your specific installation, and names the Volume Serial number/name of a disk drive on your system. (Ask locally what disk drive is available for your use.) Since we are allocating space for a library, I choose CYLINDER for the allocation unit size. The Primary Quantity field indicated that initially the PDSE will contain 2 cylinders of empty space on the disk drive. The Secondary Quantity field indicates that if we use up the initial space in the PDSE, additional cylinders will be supplied one at a time. Since we are allocating a PDSE, we indicate 0 for the Directory Blocks field. Each record in the library will have a length of 80 bytes as indicated in the Record Length field. The records are blocked together with a block size of 32,720 bytes. A block is the size unit of data transfer for disk drives. This number could vary based on the type of disk drive. The choice of LIBRARY in the Data Set Name Type field indicates the library will be a PDSE. When you have filled in the required information, press Enter. You should see the Data Set Utility panel again, but with a message in the top right corner: Data set allocated. We now have a library where we can store programs (members). Navigate to the Edit Entry Panel by typing =2 and pressing Enter.

Fill in the name of the new PDSE in the Project, Group, and Type fields. Press Enter. Normally pressing Enter would bring us to a member selection screen, but our new PDSE is empty, so we see the message “No members in data set” appear. Type “program1” in the Member name field and press Enter. This will carry us to the ISPF Editor screen.

Tab down until the cursor appears under the word “-Warning-“ Type “line 1” on the first line (being careful not to press Enter). Use the tab key to move to the second line. Type in four more lines, and the screen will look like the one below.

Pressing Enter will cause the screen to compress:

At this point, you can always move back to a line and change it by overtyping.

You can also delete a line by typing D anywhere inside the line number that appears to the left of the line. Pressing Enter deletes the line

To put the line back, type an I (insert) in the line number area of line 2.

Pressing Enter opens a new editing area for the line.

Type some text and press Enter.

At this point, you can add another line or just press Enter to compress the screen. You can copy a block of lines by typing CC on the first line to be copied, CC on the last line to be copied, and A (after) or a B (before) a line outside the block, and pressing Enter.

The block command above produces this screen:

Continue copying lines until there are more lines than will fit on the screen. You can navigate upward in the document by pressing F7. F8 scrolls downward in the document. F10 and F11 move left and right. When you are done editing, press F3 to exit the editor and carry you back to the Edit Entry panel.

Pressing Enter from this screen will bring you to a member selection list.

Type an S beside the member and press Enter to go back into edit mode on that member:

We have only scratched the surface of the ISPF editor. The ISPF Help menus can assist you in becoming a more sophisticated user. For the moment, you have enough skills to enter the program listed in the screens that follow. In order to make things simple, I’ve wrapped the program with JCL (Job Control Language) statements that are used to create a job that runs on my system. The JCL statements, particularly the Job card, will need to be altered for your system. Delete the lines in the current member by typing DD … DD as a block command, and enter the following program from the next set of screens. Perhaps your instructor will take pity and give you the program fully formed. Also keep in mind that the JOB card can vary from installation to installation. Ask for a valid JOB card format from your system administrator. The beginning JCL statements (the ones that start with //) must be entered exactly as they appear. Don’t add spaces where there are none. You will need to change the user ID from mine to yours, and you can enter your name in place of mine. Once you get past the JCL, there is a format for the assembler instructions you write. I’ll mention the most important points: 1) Symbols must start in column 1. 2) Lines that begin with * are comments. 3) Each line can have these parts: Symbol Operation Operands Comment.

4) Each part is separated by one or more spaces. 5) Operands are not separated by spaces. Here is the program you need to copy.

The executable part of the program starts on line 3900 above.

Typing M on the command line and pressing F7 will carry you all the way back to the top.

Type “sub” in the command line. Pressing Enter will submit the job for execution.

Notice at the bottom of the screen above that the job is assigned a number as it is submitted. You can use that number to help you identify the job in the system spool queue. After waiting a few moments I pressed Enter.

The following notice appeared indicating the job had completed. MAXCC=0 indicates the job ran without errors. I pressed Enter.

Navigate to the spool queue by typing =sd;o (that’s an Oh) and pressing Enter . You might need to type =sd;h depending on your system. (Finding the spool queue on your system may require invoking a different spool manager.)

Type s beside your job. Press Enter, and the entire job output will be displayed.

Here’s the start of the job.

The job consisted of three steps: C (compile) with a return code of 00, L (link) with a return code of 00, and G (Go) with a return code of 00. Since all the return codes were 00, the job ran to completion normally. You can use F7 and F8 to scroll through the job listing. When you are done, press F3 to back out one level.

Type ? beside the job to display the job broken up into sections.

Type s beside the part of the job you would like see. Press Enter.

The program printed these lines:

When you are ready to log out of your session, from any screen, type =x and press Enter.

This will exit you from ISPF, and carry you back to TSO.

Type “logoff” to exit TSO.

The only thing left to do is close your terminal emulator.