Additional information for using the Marist system


Connecting to the Marist system

In order to use the Marist mainframe system, you must first connect to it. To do that, read 1_Appendix_I_System_Login_information.doc, download Vista, and if required, use the registration name and code indicated in the document. If you prefer to use a Unix platform, instead of Vista, download x3270 from x3270.bgp.nu. With Vista or x3270, as indicated in the document, you will connect to zos.kctr.marist.edu, port 1023. Once connected, enter "L TSO" or "l tso", then enter your username (which you should now have received by email; if not, tell me), then your password (the first time you connect, you will be required to change your passord too), then press enter to get rid of the page/message "WELCOME ... ZIGZAGGING THROUGH GHOSTLAND", and you are in. Familiarize yourself with the system by follow step by step the documents 2_labB1_review_ISPF_JCL.doc and 3_labB2_edit_compile_run_V4.doc (for each document, this will take you about 2 hours). The file 4_Appendix_II_Quick_Reference_on_Using_ISPF.doc is a summary of the previous two but you I list it here in case it comes handy to you. The way the interface works seems odd at the beginning. Use the mouse (or the arrows) to fill the required data/choices at the indicated places, and then press ENTER.

To exit, use X in the main menu (and LOGOFF, if necessary) but do NOT disconnect/exit/close without logging off first because you may not be able to log on again for about 20 minutes. Same thing if you attempt to log in twice, for example by using two windows of Vista. Z/OS will also freeze for a while if in a menu you try to enter more characters than allowed (you might then have to do wait 20 minutes, i.e., until z/OS logs you out).


Transfering a file from PC to the Marist system

Go to Option 6 (COMMAND) from the ISPF main menu on the mainframe, then use the 'File Transfer --> Send to host' tool of Vista from within this menu. It is necessary to go to Option 6 in order to pass the transfer command directly to TSO, as opposed to sending the command to ISPF.
Remember that if you do not enclose a file name within single quotes, your username is automatically added as a prefix, e.g. DATASET.NAME becomes 'USERNAME.DATASET.NAME' and USERNAME.DATASET.NAME becomes 'USERNAME.USERNAME.DATASET.NAME'. Check this if you get an error message such as "Missing or incorrect TSO data name". If you get the message "Cannot begin transfer", wait a minute or two, go to another menu, come back and retry.


Compiling, linking and running Cobol programs

When following the instructions from 2_labB1_review_ISPF_JCL.doc, you have created a library called PROJECTA with sub-libraries COBOL and LOAD. Use these libraries for your developments on the Marist system.

A JCL script to compile and link a COBOL program is given in 5_labB3_DataProcessing_V1.doc. Below is an example named CL. Copy-paste or transfer it into PROJECTA.JCL(CL), that is, the script CL in the sublibrary JCL of your library PROJECTA. However, you need to replace KC03BC1 with your user id. Do not remove the space before PEND and EXEC.

//CL JOB  1,KC03BC1,NOTIFY=KC03BC1,MSGLEVEL=(1,1)
//BUILD PROC NAME=TEMPNAME 
//EXE   EXEC IGYWCL 
//COBOL.SYSIN  DD DSN=KC03BC1.PROJECTA.COBOL(&NAME),DISP=SHR 
//LKED.SYSLMOD DD DSN=KC03BC1.PROJECTA.LOAD(&NAME),DISP=SHR 
// PEND 
// EXEC BUILD,NAME=TEST1

To develop and test a program, I suggest the following steps to reduce navigation in the menus;
1) edit your COBOL program then press F3 (the program is automatically saved);
2) replace COBOL by JCL, and TEST1 by CL, in the menu (and thus edit CL);
3) enter SUBMIT in the command line of your editor (then press ENTER twice to see the command line again);
4) to see the result, press F2 (with your mouse cursor near the bottom of the screen);
5) enter 13 if you are in the main menu (otherwise go to it first);
6) enter ST (you'll then see a job named CL at the bottom line of the list);
7) press F11 twice to see the "Offs Max-RC" value for your job;
8.1) if the value is "CC 0000", press F3 (see also 8.1.1. below);
8.2) if the value is not "CC 0000" there is an error; press F10 twice, put the character s before your job (in the column NP) to access the report file and understand the problem; when understood, press F3 twice;
9) press F2 (with your mouse cursor near the bottom of the screen) and you are back in the editor for CL;
10.1) if the value was "JCL error" instead of "CC 0000", correct CL, then go to step 3 (and omit step 5);
10.2) if the value was something like "CC 0012", press F3, edit your COBOL program, come back to edit CL, then go to step 3 (and omit step 5). 10.3) otherwise, if you want to test or re-test your newly generated executable module, press F3, edit the script that does that (an example named A1 is given below) and go to step 3 (and omit step 5).

8.1.1) if the value is "CC 0000" for the execution of A1, press F3 until you reach the main menu, then enter 2 and edit TEST1O (with an "O", not a zero) to see if the result is good. For your testing, you can create other input and output files: TEST1I1, TEST1O1, TEST1I2, TEST1O2, etc.

Here is a example of script to execute the COBOL program that you have complied and linked (you need to replace KC03BC1 with your user id):

//A1 JOB 1,KC03BC1,NOTIFY=KC03BC1,MSGLEVEL=(1,1) 
//STEP1 EXEC PGM=TEST1 
//STEPLIB DD DSN=KC03BC1.PROJECTA.LOAD,DISP=SHR 
//TEST1I  DD DSN=KC03BC1.PROJECTA.TEST1I,DISP=SHR 
//TEST1O  DD DSN=KC03BC1.PROJECTA.TEST1O,DISP=SHR 


Here are some examples of programs using a sequential file as input and that work on our z/OS system.


Two additional notes.
1) If the z/OS editor stops letting you enter characters because of some overflow (this happens to me very often), one way I found to go on is to use the up arrow to move the cursor round the screen (i.e., to the top of the screen and a bit more), then press F3 (now, the editor will alow it) and get into the editor again. If you know or find a better solution, tell me.
2) If you get the message "Cannot begin transfer" when you use File Transfer in Vista or x3270, do something else for a few minutes and retry.


Compiling and linking sub-programs

The following JCL shows one way to compile and link a program named TEST2 and its subprogram named SUB2. These are the same instructions as for CL except for the use of LKED.SYSLIB. (Click here for a longer alternative CL2).

//CL2   JOB  1,KC03BC1                                        
//STEP1 EXEC IGYWCL                                            
//COBOL.SYSIN  DD DSN=KC03BC1.PROJECTA.COBOL(SUB2),DISP=SHR    
//LKED.SYSLMOD DD DSN=KC03BC1.PROJECTA.LOAD(SUB2),DISP=SHR     
/*                                                             
//STEP2 EXEC IGYWCL                                            
//COBOL.SYSIN  DD DSN=KC03BC1.PROJECTA.COBOL(TEST2),DISP=SHR   
//LKED.SYSLMOD DD DSN=KC03BC1.PROJECTA.LOAD(TEST2),DISP=SHR    
//LKED.SYSLIB  DD DSN=KC03BC1.PROJECTA.LOAD(SUB2),DISP=SHR      
//             DD DSN=KC03BC1.PROJECTA.COBOL(TEST2),DISP=SHR    
//             DD DSN=KC03BC1.PROJECTA.JCL.OBJ(TEST2),DISP=SHR  
//

Then, a script like A1 can be re-used to execute the result. For example, with the file names required for Assignment 2, we can have the following A2.

//A2 JOB 1,KC03BC1                                
//STEP1 EXEC PGM=TEST2                            
//STEPLIB DD DSN=KC03BC1.PROJECTA.LOAD,DISP=SHR   
//TEST2I  DD DSN=KC03BC1.PROJECTA.TEST2I,DISP=SHR 
//TEST2IO DD DSN=KC03BC1.PROJECTA.TEST2IO,DISP=SHR
//TEST2O  DD DSN=KC03BC1.PROJECTA.TEST2O,DISP=SHR 
//TEST2E  DD DSN=KC03BC1.PROJECTA.TEST2E,DISP=SHR 
//TRAN2E  DD DSN=KC03BC1.PROJECTA.TRAN2E,DISP=SHR 


Creating VSAM files (that is, indexed files)

Details on VSAM files (indexed files on IBM mainframes) can easily be found on the Web. A VSAM file can be created manually (click here for some steps) or using JCL scripts (see again these steps, or this JCL adapted from http://www.simotime.com/utldat01.htm, or this one).

When you have created a VSAM file and display its "Data Set Information", you should see something like
000001 /* IDCAMS COMMAND */
000002 LISTCAT ENTRIES(KC03BC1.PROJECTA.TEST2IO)

Even after being defined, a VSAM file is unavailable if it has never contained a record. Hence, it should first be initialised by a program which writes into it in a sequential way ("access is sequential"). You may or may not be able to re-initialise a VSAM file if it has already been created (this may depend on the priviledges you have been given on the mainframe). If you cannot, in the script of a COBOL program that initialises a VSAM file, call a script that deletes and re-creates the VSAM file.


Finally, note that the call to a "sort" statement may sometimes only work if you use a "display" statement just before the "sort".