Chapter 4: Tutorial: JCL

This tutorial takes you step by step through the process of configuring an Enterprise Server to run JCL applications, and then deploying and running a JCL application. This is intended both as an introduction to using JCL with the reUZE Developer and reUZE Server environments and as an Installation Verification Procedure (IVP) to confirm that JCL support is correctly installed.

Overview

The reUZE Server execution environment is built on top of the Micro Focus Enterprise Server technology that provides the infrastructure not just for executing COBOL, CICS, IMS, DB2, VSAM and JCL, but also for deploying existing transactions as Web Services for easier re-use within new architectures like .NET, J2EE or SOA.

JCL applications written to run on a z/OS or VSE mainframe can be run with the reUZE Server environment. You maintain the applications in Visual Studio.

You can maintain your JCL files on the PC using any text editor.

Demonstration Application

This tutorial uses the demonstration application JCL supplied with your COBOL development system. The JCL application performs four functions:

  1. Uses IDCAMS to delete from the catalog the data set created in step 2, if it is already there.
  2. Runs a COBOL program that writes a simple data set, which is added to the catalog.
  3. Uses IEBGENER to create a temporary data set.
  4. Runs a COBOL program that reads through the data set created in step 3 and displays it.

Outline

In this tutorial you perform the steps typically required in managing, maintaining and running JCL applications. In summary, you:

  1. Configure an Enterprise Server to run JCL applications.
  2. Create a native COBOL project comprising all the parts of your application, such as the COBOL source and the JCL batch files.
  3. Associate the project with your Enterprise Server.
  4. Build the COBOL project in your IDE.
  5. Submit the JCL file on your Enterprise Server.
  6. Run the application in your Enterprise Server.
  7. View the spool and the catalog.
  8. Debug dynamically.
  9. Debug remotely.

Configure an Enterprise Server

These are the steps to create and configure an Enterprise Server to run JCL applications.

Configure an Enterprise Server for JCL Support

To enable JCL support in an Enterprise Server, you need to do the following tasks:

  1. Create a Mainframe Sub System (MSS)-enabled Enterprise Server.
  2. Enable Job Execution System (JES) in this Enterprise Server.
  3. Configure locations for programs and data files and so on.

Create an MSS-enabled Enterprise Server

To open the Enterprise Server Administration page in the IDE:

  1. Launch Visual Studio.
  2. Open the Server Explorer on the left.

    If it is hidden, display it by choosing View > Server Explorer or View > Other Windows > Server Explorer).

  3. Right-click Micro Focus Servers and choose Administration from the context menu.

To create an MSS-enabled Enterprise Server:

  1. On the Home page of Enterprise Server Administration, click Add at the bottom of the table of servers.
  2. On the first Add Server page:
    1. Type JCLDEMO in the Server Name field.
    2. Make sure 32-bit is selected in the Working Mode section.
    3. Click Next.
  3. On the second Add Server page:
    1. Click Micro Focus Enterprise Server with Mainframe Subsystem Support.
    2. Click Next.
  4. On the third Add Server page:
    1. Delete the check marks by Create TN3270 listener and Create ISC listener.
    2. Type Server for JCL in the Description field (near the bottom of the page).
    3. Click Add.
  5. The Home page is redisplayed, and a row for the new Enterprise Server is visible in the table of servers.

Enable JES

To enable the JES support within MSS:

  1. Click Edit next to the JCLDEMO row in the table of servers.

    The Edit page that appears contains a hierarchy of tabs.

  2. Make sure the Server and Properties tabs are selected, and click MSS and then JES.
  3. Check the Job Entry Subsystem enabled check box.

    Don't click Apply yet — there is more to do on this page.

Configuring Program Paths

You need to specify the directories and other details needed for the Enterprise Server to find deployed programs. To do this:

  1. Enter values into the fields on the JES > General tab, as shown in the table below. The paths you enter here point to the directory of your project.
    Field Value to enter: Details
    JES Program Path c:\tutorials\jcl\bin\x86\Debug Path for the directory containing executable files to be run by your JCL jobs. This is the path to the Debug folder of your project that contains the .dll files. For debugging, the .idy and .cbl files are used.
    System Catalog c:\tutorials\jcl\catalog\catalog.dat Path and name of the system catalog. This is a file that holds the details of data files, their attributes and locations.
    Default Allocated Dataset Location c:\tutorials\jcl\catalog\datasets The default path for the directory where new data sets are to be created, if you do not specify a directory.
    System Procedure Library SYS1.PROCLIB Set of cataloged PDS data set names that will be searched to resolve JCL procedure names.
  2. Click Apply.
  3. Click Home on the Enterprise Server Administration.
Enable the Console Window

It is useful to have the character-mode console daemon window showing when the JCLDEMO region is running. To enable the console window:

  1. Click Edit next to JCLDEMO.

    The Edit page that appears contains a hierarchy of tabs.

  2. Make sure the Server, Properties and General tabs are selected.
  3. If Show Local Console is already checked, click Cancel. If it isn't, check it and then click OK.
Enable Dynamic Debugging
  1. Click Edit next to the JCLDEMO row in the table of servers.

    The Edit page that appears contains a hierarchy of tabs.

  2. Make sure the Server and Properties tabs are selected, and click General.
  3. Check Allow Dynamic Debugging.
  4. Click OK.

Start Your Enterprise Server

You can now start JCLDEMO:

  1. Click Home on the Enterprise Server Administration.
  2. Click Start in the Status column of the JCLDEMO server.

    If Start server is disabled, click Stop server instead, and when JCLDEMO has stopped, restart it.

  3. Click OK.
  4. If the Auto-refresh Interval field on the Enterprise Server Administration Home page contains a number, the page will refresh automatically at intervals of the stated number of seconds. Otherwise, click the Refresh button every few seconds, until the Current Status column shows Started.

Define Batch Initiators and Printers

You can run JCL with the following kinds of Service Execution Processes (SEPs):

You can define initiators and printers to start up automatically whenever the Enterprise Server is started, and you can also create ones that last only for the current session.

To define an initiator to start automatically:

  1. On the home page of Enterprise Server Administration, click Edit next to JCLDEMO.
  2. Make sure the Server and Properties tabs are selected, and click MSS > JES.
  3. Define a batch initiator as follows:
    1. Click Initiators > Add.
    2. Enter values in the fields as shown in the following table:
      Field Value Comment
      Name INITAB Not case sensitive — gets folded to upper case
      Class AB Not case sensitive — gets folded to upper case
      Description Initiator for class A and B jobs
    3. Click Add.
  4. Click Home on the Enterprise Server Administration.

Create and Build a JCL Application

These are the steps to create a Visual Studio project comprising all the parts of your application, such as the COBOL source and the JCL batch files. We build the demonstration application in Visual Studio, deploy and run it on an Enterprise Server configured to run JCL applications and debug it dynamically.

Create a Project

To create a native COBOL project to hold the JCL demonstration program:

  1. Create a working folder on your machine such as c:\tutorials.
  2. Start Visual Studio.
  3. Click File > New > Project > COBOL Projects > Native > Mainframe Subsystem Application.
  4. Specify a name for your project such as jcl.
  5. Specify your working folder in the Location field. This is the folder you defined in step 1 above.
  6. Disable Create directory for solution.
  7. Click OK.

    This creates a jcl folder in your working folder that holds your solution and project.

  8. Right-click the solution in Solution Explorer and choose Open Folder in Windows Explorer.
  9. Using Windows Explorer, copy the demonstration files from the subfolder Examples\Visual Studio Integration\Mainframe\JCL in your reUZE Developer installation folder. Copy the files to your project folder, c:\tutorials\jcl.
  10. Using Windows Explorer, create a catalog folder in your project folder — c:\tutorials\jcl\catalog.

    Note: Your project folder needs to have the catalog folder created beforehand in order to submit the JCL successfully.

Import the Files from the Demonstration Program

To import the files from the JCL demonstration program into your Visual Studio project:

  1. In Solution Explorer, right-click your project and select Add > Existing Item.
  2. Set Objects of type filter to All Files (*.*).
  3. Select the .jcl and the two .cbl files in the project folder.
  4. Click Add.

Specify Project Properties

To specify the project properties:

  1. In Solution Explorer, double-click the Properties folder.
  2. On the COBOL tab, make sure Source Format is set to Fixed.
  3. Make sure Enterprise COBOL for z/OS COBOL dialect is selected.
  4. In the Additional Directives field, type charset(ascii).
  5. On the Debug tab, select JCL from the drop down list for Choose Active Setting.
  6. Click the JCL tab on this page — there is no need to specify any settings on it at this point.
  7. Press CTRL + S to save the changes in the project properties.

Associate Your Project with the JCL Enterprise Server

The IDE enables you to associate your project with the running JCLDEMO Enterprise Server. To associate your project with the JCL server that you created, JCLDEMO, you need to:

  1. Open Server Explorer on the left.

    If it is hidden, display it from View > Server Explorer or View > Other Windows > Server Explorer.

  2. Start JCLDEMO by clicking Start in the Status column.
  3. Right-click JCLDEMO in Server Explorer and choose Associate with project > your project.

Build the Solution

To build the solution:

  1. Right-click the solution in Server Explorer.
  2. Choose Build Solution from the context menu.

The application .dll and .idy files are created in the output Debug folder in your project directory.

Deploy to Enterprise Server

You do not need to deploy the application to your Enterprise Server as you configured the Enterprise Server search path to be the Debug folder in your Visual Studio project directory. Enterprise Server automatically finds the application files that it needs to run.

Submit and Run a JCL Job

To submit the JCL application to the running JCL configured Enterprise Server:

  1. In the IDE, right-click the .jcl file in Solution Explorer.
  2. Choose Submit JCL.

See the output messages in the Enterprise Server Console Daemon for the result of running the JCL job.

View the Spool Queues

The Enterprise Server Monitor and Control (ESMAC) works in conjunction with Enterprise Server Administration and enables you to view and control Enterprise Servers, and the services, packages, and handlers that run on those servers. The spooler is another name for the job entry subsystem, JES. It maintains a number of spool queues, showing the status of jobs in the system.

The IDE enables direct access to the Spool and Catalog on the ESMAC pages.

To see the spool queues:

  1. In Server Explorer, right-click JCLDEMO under Micro Focus Servers.
  2. Select Show spool from the context menu.

    The page that appears shows one of the spooler queues. Select a queue to display using the radio buttons.

  3. Click Output.

    This displays the Output Queue. It contains the output from the job you have just run.

  4. Select the check box to the left of the JCLTEST entry, and click Display.

    This shows details of the job.

  5. You can view details of a particular step. For example, click Details on the line for the READ step.
  6. On the same page, click Display to view the output from the step.

    The output from this step consists of a small number of simple records.

  7. Right-click in the window and select Back to return to the ESMAC pages.

View the Catalog

The catalog file holds the details of data sets needed for the JCL jobs that run in an Enterprise Server. To view the catalog:

  1. In Server Explorer, right-click JCLDEMO and choose Show catalog.

    The page that appears shows the catalog file, MFIJCL.OUTFILE.DATA, created by the example job.

  2. Select the check box in front of the catalog file.
  3. Click Details.
  4. Select EBCDIC from the drop down list next to Codeset.
  5. To view the file, click Display on the page showing the catalog entry.

    The file contents are displayed as a page in the browser.

Debug Dynamically Under Enterprise Server

The IDE enables you to debug a job running under Enterprise Server. It’s not possible to debug the JCL file but you can debug the programs that are invoked by the job that is EXEC PGM=PROG.

Before proceeding, stop any Enterprise Server region that may be running.

Enable Enterprise Server Debugging

Before you can debug within the IDE, you must enable the dynamic debugging feature within your Enterprise Server. This option is available on the General properties page within Enterprise Server Administration.

Ephemeral Ports

By default, Enterprise Server uses ephemeral ports for its communication listeners, to prevent clashes occurring with other network software on your machine when a listener starts. However, this can make debugging more complex, since Enterprise Server is likely to be assigned a different port each time it starts.

To force Enterprise Server to use a fixed port number for debugging purposes:

  1. In the IDE, open Server Explorer.
  2. Right-click Micro Focus Servers and choose Administration from the context menu.
  3. On the row for JCLDEMO on Enterprise Server Administration page, click Details for the Listeners in the Communications Processes column.
  4. Click Edit on the row for Web Services and J2EE.
  5. The existing setting should be *:*.
  6. The second * indicates use an ephemeral port number.
  7. Change the Endpoint Address to *:5055 in order to use a fixed port.
  8. Click OK.
  9. Click Home on the left to return to the Enterprise Server Administration page.
  10. Start the Enterprise Server.

During the startup sequence, watch for a mention of dynamic debug enabled. If you missed it, check the Enterprise Server Console in the Server Diagnostics page of Enterprise Server Administration.

Associate Project with New Listener Port

Now that you have a fixed port, you should reassociate the region with your project in Server Explorer in Visual Studio.

Start Debugging

Debugging requires no changes to your program code. It requires that your project is associated with the JCLDEMO Enterprise Server and that the Enterprise Server is configured to enable dynamic debugging, which you performed in the previous steps.

  1. Double-click any of the .cbl files in Solution Explorer.
  2. Choose Debug > Start Debugging or press F5.

    The debugger enters a wait state.

  3. Introduce a breakpoint in the procedure division section of the code.

    If you now submit the JCL file, the debugger stops in your JCLCREATE program.

  4. Step through a few lines and press F5 to continue.

    The debugger should stop again in the JCLREAD program.

  5. Once you’ve completed your debug session, select Debug > Stop Debugging.

Notice the messages that have appeared in the Enterprise Server console window.

The debugger offers you a number of choices when specifying what you want to debug. You may choose a Job Name, a Job Number, a Step Name or the top-level program on the Debug tab of the project properties.

These choices enable you to perform remote debugging, to support multiple users debugging on the same region.

Given that you’re running Enterprise Server locally and no one else is connecting to it, you do not need to specify any options and the debugger debugs any debuggable program that it finds.

View the List of Attached Debuggers

You can view the list of debuggers waiting to attach to your region using ESMAC:

  1. Click Edit on the row for JCLDEMO in Enterprise Server Administration.
  2. Click the Control tab under Server.
  3. Click ES Monitor & Control.

    This opens the ESMAC page.

  4. Click the Dyn-Dbg button at the bottom left of the page.

You can also remove these debuggers from the list.

Debug Remotely Under Enterprise Server

You can submit JCL to a region working on the remote machine, to enable it to access Enterprise Server. For this purpose the remote machine must have Enterprise Server with JCLDEMO configured and working.

Make sure the firewall is not working on the remote machine to be able to access Enterprise Server.

  1. In the IDE, right-click Micro Focus Servers in Server Explorer.
  2. Select MFDS Configuration.
  3. Type the name of a remote machine in the Host name field, or specify its IP address in the IP Address field.
  4. Click OK.
  5. Refresh the Micro Focus Servers group.
  6. Right-click JCLDEMO on the remote machine and choose Associate with project > your project.
  7. In Solution Explorer, right-click the .jcl file and choose Submit JCL.
  8. See if you can debug the JCLCREATE and JCLREAD applications running on the remote machine.

More Information

For more information about using reUZE Developer, refer to the Help either in the product or on the Micro Focus Web site.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.