Chapter 10: JCL Walkthrough

This chapter 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 in reUZE Server, and as an Installation Verification Procedure (IVP) to confirm the JCL support is correctly installed.

If you are not familiar with reUZE Serverr, Mainframe Subsystem support, or CICS, see the chapters:

Overview

JCL applications written to run on a z/OS or VSE mainframe can be run under Enterprise Server. You maintain the applications in Net Express.

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

Demonstration Application

This chapter uses the demonstration application ESJCL supplied with Net Express. The ESJCL application has four steps:

  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.

For your convenience we have supplied the required Net Express project.

Prerequisites

To work through this chapter, you need Net Express including reUZE Server.

Outline

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

  1. Configure an enterprise server to run JCL applications.
  2. Create a Net Express project comprising all the parts of your application, such as the COBOL source and the JCL batch files.
  3. (optional) Associate the project with your enterprise server.
  4. Compile the COBOL programs in Net Express.
  5. Deploy the application to a location accessible by Enterprise Server.
  6. Run the application in Enterprise Server.

Configuring an Enterprise Server for JCL Support

To enable JCL support in an enterprise server, you need to do the following tasks. The sections below walk you through these.

  1. Create an MSS-enabled enterprise server.
  2. Enable JES in this enterprise server.
  3. Configure locations for programs and data files, etc.

Creating an MSS-enabled Enterprise Server

To create an MSS-enabled enterprise server:

  1. On the Home page of ES Admin, click Add at the bottom of the table of servers.
  2. On the first Add Server page:
    1. Type JCLDEMO in Server Name.
    2. Click Micro Focus Enterprise Server with Mainframe Subsystem Support
    3. Click Next.
  3. On the second Add Server page:
    1. Type Server for JCL in the Description field (near the bottom of the page).
    2. Delete the check marks by Create TN3270 listener and Create ISC listener.
    3. Click Add.
  4. The Home page is redisplayed, and a row for the new enterprise server is visible in the table of servers, as shown in Figure 10-1.

Servers Page showing JCLDEMO

Figure 10-1: Servers Page showing JCLDEMO

Enabling JES

To enable the JES (that is, JCL) support within MSS:

  1. Click Edit next to the JCLDEMO row in the table of servers.
  2. The Edit page that appears contains a hierarchy of tabs. 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:

  1. Enter values into the fields on the JES > General tab, as shown in Table 10-1, replacing user-ID by the Windows user-ID you are logged in to. The paths you enter here point to directories you will create later.
    Field Value to enter: Details
    JES Program Path c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo\esjcl Path for the directory containing executable files to be run by your JCL jobs.

    You will put your .gnt and .dll files here. For debugging, you put your .int, .idy and .cbl files here.

    System Catalog c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo\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. For more information see the section Catalog Files in the chapter Files and Data Sets.
    Default Allocated Dataset Location c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo\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.
    Table 10-1: Field values for JCL support
  2. Click Apply.

Associating a Net Express Project with the JCL Enterprise Server

It is possible to view ES Admin in a window in the IDE instead of in a Web browser. If you do this, some extra functions appear on the IDE menus, for controlling an enterprise server. To use these you must have a project open that you have associated with an enterprise server - these functions then operate on that enterprise server.

We will associate the supplied Net Express project with the JCL server that we just created, JCLDEMO:

  1. Close the Web browser you've been using in the previous sections.
  2. Open Net Express in any of the usual ways, for example Start > All Programs > Micro Focus Net Express ver.
  3. In the Net Express IDE, open the supplied project install-dir\Examples\Net Express IDE\ESJCL\ESJCL.app.
  4. Click Project > Properties.
  5. Check Project uses an enterprise server.
  6. Click Browse. You see a dropdown list of enterprise servers, including JCLDEMO.
  7. Click JCLDEMO in the dropdown list.
  8. Click OK.
  9. Click Tools > Enterprise Server > Administration.

    A window displaying the Home page of ES Admin opens within the IDE.

Enabling the Console Window

It will be useful to have the character-mode console daemon window showing. It is enabled by default, and should appear when you start JCLDEMO in a moment, but if you want to make sure:

  1. Click Edit next to JCLDEMO.
  2. The Edit page that appears contains a hierarchy of tabs. Make sure the Server, Properties and General tabs are selected.
  3. If Show Local Console is already checked, simply click Cancel. If it isn't, check it and then click OK.

Starting your Enterprise Server

You can now start JCLDEMO:

  1. In the IDE, click Tools > Enterprise Server > Start server.

    Because you associated this project with JCLDEMO in the Project Properties above, this starts JCLDEMO.

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

  2. If the Auto-refresh Interval field on the ES Admin 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.

Defining Batch Initiators and Printers

There are two types of Service Execution Process (SEP):

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. We will define one initiator and one printer to start automatically. (If you do not have a printer available, you can omit the steps concerning the printer):

  1. Click Edit next to JCLDEMO.
  2. Make sure the Server and Properties tabs are selected, and click MSS > JES.
  3. Define an 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. Define a batch printer SEP as follows (if you do not have a printer available, you can omit this step):
    1. Click Printer > Add.
    2. Enter values in the fields as shown in the following table:
      Field Value Comment
      Name printer-name Use the Browse button to select a printer.
      Class AB Not case sensitive - gets folded to upper case
      Exit module   Leave this field blank
      Description Printer for class A and B jobs

      Note: For the list displayed by the Browse button to include printers accessed across a network, you need to have started the enterprise server either by using Tools > Start Server in the Net Express IDE, as we did here, or from the command line. If you start it from ES Admin (even if ES Admin is running as a window within the Net Express IDE), it runs as a system service and the network printers defined on your machine are not visible.

    3. Click Add

Building the Net Express Project

Now that we have an enterprise server configured to run JCL applications, we'll build, deploy and run the demonstration application.

To build the supplied project:

  1. In the Net Express IDE, click Project: ESJCL.APP at the bottom of the main part of the IDE.

    The project contains the two COBOL programs and the JCL file.

    The Project Properties in this project include the DIALECT(ENTCOBOL) directive, because you need to set a mainframe dialect to indicate to the File Handler that it should use mainframe-style rules for resolving the filename when the job is run in Enterprise Server.

  2. Build the project.

    If you get a message that the project directives have changed (because you earlier checked the Project uses an enterprise server check box), click Yes.

Creating Directories

When you started your new enterprise server JCLDEMO, a working directory was created for it. This directory is called c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo, where user-ID is the Windows ID you are logged in under.

Within this directory, you now need to create the directories that you configured JCLDEMO to use:

  1. Within the above directory, create subdirectories as follows:
    Name Used for
    esjcl executables to be run from JCL
    catalog system catalog location
    catalog\datasets cataloged data set location

Deploying to Enterprise Server on Windows

To deploy to Enterprise Server on Windows, you simply copy the application files to the directory where the enterprise server that will run your application expects them. Because we will be debugging later in this chapter, you need the .cbl, .idy and .int files.

  1. Copy *.int and *.idy from Examples\Net Express IDE\ESJCL\debug to the esjcl directory you created.

    These are the .int and .idy files of the two COBOL programs.

  2. Copy esjcl.jcl and *.cbl from Examples\Net Express IDE\demo\esjcl to the esjcl directory you created. (You can ignore testvsam.vse - it's used in a later tutorial.)

    The JCL file does not in fact have to be in the same directory as the executable files - you will specify its path when you run it - but it's convenient to put it there.

Running a JCL Job

To run the application:

  1. In the Net Express IDE, click Micro Focus Enterprise Server Administration at the bottom of the main part of the IDE. (If you have closed the IDE, re-open it and the project and the ES Admin window as before.)
  2. On the Home page of ES Admin, click Details in the Current Status column for JCLDEMO.
  3. Make sure the Server and Control tabs are selected, and click ES Monitor & Control.
  4. In the dropdown list under Resources on the ESMAC menu, select JES.

    If JES is not present, return to the Home page of ES Admin, click Edit by JCLDEMO, and check that you entered the configuration details correctly. In particular check that the paths exist, and that the spelling and case are correct. If you change anything, you must stop and restart JCLDEMO for the change to take effect.

  5. Click Control in the Resources part of the ESMAC menu (near the bottom of the menu - not the one near the top).

    The JCL Control page that appears is for submitting jobs, and for starting additional printers and initiators.

  6. In the field next to the Submit button, use the Browse button to enter the path and name of the JCL file you want to run, that is: C:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA \JCLDEMO\esjcl\esjcl.jcl. The relevant part of the Web page is shown in Figure 10-2.

    Submitting a JCL Batch Job

    Figure 10-2: Submitting a JCL Batch Job

  7. Click Submit.

    The Job Control page displays messages showing the job starting, as shown in Figure 10-3. The Console Daemon window displays messages showing the job running. If you defined a batch printer SEP, the output from the job is printed out.

    Running a JCL Batch Job

    Figure 10-3: Running a JCL Batch Job

Viewing the Spool Queues

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. To see the spool queues:

  1. In the Resources part of the ESMAC menu, with JES selected from the dropdown list, click Spool.

    The page that appears shows one of the spooler queues. There is a set of radio buttons to select which queue is displayed.

  2. Click Output. This displays the Output Queue. It contains the output from the job you have just run, as shown in Figure 10-4.

    The Output Queue

    Figure 10-4: The Output Queue

  3. Check the check box to the left of the JCLTEST entry, and click Display.

    This shows details of the job, as shown in Figure 10-5.

    Job Output

    Figure 10-5: Job Output

  4. You can view details of a particular step. Click Details on the line for the READ step (the bottom line in Figure 10-5.

    The page shown in Figure 10-6 appears.

    Details of the READ Step

    Figure 10-6: Details of the READ Step

  5. To view the output from the READ step, click Display (near the bottom in Figure 10-6).

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

    You can get back to the ESMAC pages by right-clicking in the window and clicking Back.

Viewing the Catalog

To see the catalog:

  1. In the Resources part of the ESMAC menu, with JES selected from the dropdown list, click Catalog.

    The page that appears shows the catalog, as shown in Figure 10-7. The file MFIJCL.OUTFILE.DATA that was created by the example job is there.

    The Catalog

    Figure 10-7: The Catalog

  2. Click Details on the line for MFIJCL.OUTFILE.DATA.

    The page shown in Figure 10-8 appears.

    Catalog Entry

    Figure 10-8: Catalog Entry

  3. To view the file, click Display (on the bottom line in Figure 10-8).

    Because you are within the IDE, the IDE recognizes from the .dat extension of the physical filename that this is a data file, and opens the Data File Editor to display it. If you were using a separate Web browser, the file contents would simply be displayed as a page in the browser.

  4. The Data File Editor asks you for the details fo the file's format so it can display the file. You can see from the Catalog Entry that the DS Org is PS, the RECFM is FB, and the LRECL is 80, so select Sequential - fixed length as the File Organization, and enter "80" as the Maximum Length. Click OK. Click No on the question whether to save these details as a profile.

    Initially the data appears invalid. As we said earlier, the project contains a DIALECT(ENTCOBOL) directive. One effect of this mainframe-dialect directive is to cause the application that we ran to output its data file in EBCDIC.

  5. At the top left of the Data File Editor window, select EBCDIC.

    You can now see the data correctly.

    If you were using a separate Web browser, you would use the Codeset field at the bottom right in Figure 10-8 to select EBCDIC before you clicked Display.

  6. Close the Data File Editor.

Using a Printer Exit Module

You can write a printer exit module to integrate MSS’s batch printing capability with existing print subsystems. For more information about what printer exit modules do, see the section Printer Exit Modules in the chapter JCL Support.

A sample printer exit is provided in install-dir\Examples\Net Express IDE\sampprnx\sampprnx.cbl. This printer exit simply takes each line of the data file created and calls the COBOL run-time system's print routines to print it. You can try it out by following these instructions, which assume that you have already worked through the preceding sections in this chapter:

  1. Compile the printer exit module:
    1. Close the esjcl.app project you were using, and open install-dir\Examples\Net Express IDE\sampprnx\sampprnx.app.

      A separate project has been supplied for the printer exit, because a printer exit module cannot be built with a mainframe dialect, and so this program could not be compiled with the DIALECT(ENTCOBOL) directive included in esjcl.app.

    2. Build the project.
    3. Deploy the printer exit module:
      1. Copy the .int and .idy files from Examples\Net Express IDE\sampprnx\debug to a location on the COBPATH.
      2. Copy *.cbl and *.cpy from Examples\Net Express IDE\sampprnx to your c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo\esjcl directory.
  2. Close sampprnx.app and re-open esjcl.app, so that you can use ES Admin from within the IDE.
  3. Click Tools > Enterprise Server > Administration.
  4. Update the printer that you defined before:
    1. Click Edit next to JCLDEMO.
    2. Make sure the Server and Properties tabs are selected, and click MSS > JES.
    3. Click Printer > Edit.
    4. Specify the name of your printer exit module, sampprnx, in Printer Exit Name.

      Do not include the extension.

    5. Click OK
  5. Submit the JCL job:
    1. In the dropdown list under Resources on the ESMAC menu, select JES.
    2. Click Control in the Resources part of the ESMAC menu).
    3. In the field next to Submit, type the path and name of the JCL file you want to run, that is: c:\Documents and Settings\user-ID\My Documents\Micro Focus\Net Express ver\WORKAREA\jcldemo\esjcl\esjcl.jcl
    4. Click Submit.

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