Submitting a JCL job in a Language step

In this tutorial, you set up and run a simple JCL job through the zBuilder job step. The job step type is used to submit JCL jobs within the zBuilder language task. Unlike other step types, job steps can execute APF-authorized programs.

Prerequisites

Estimated time

This tutorial takes about 15 minutes to complete.

Steps

  1. Within your language task, define a job step to store the configuration for your JCL job:
---
version: 1.0.0
tasks:
  # zBuilder configuration goes here...

  - language: JobTest
    # Language Configuration goes here...

    steps:

      # JCL Configuration goes here
      - step: JCLTutorial
        type: job
        maxRC: 4
  1. Source the JCL. For this tutorial a simple "Hello World" example, hello.jcl, is used:
//HELLO  JOB ,
//       MSGCLASS=H,MSGLEVEL=(1,1),TIME=(,4),REGION=0M
//*
//* PRINT \"HELLO, WORLD\" ON JOB OUTPUT
//*
//STEP0001 EXEC PGM=IEBGENER
//SYSIN    DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD *
HELLO, WORLD
/*
//SYSUT2   DD SYSOUT=*
//

Add the source file to the step configuration:

- step: JCLTutorial
  type: job
  maxRC: 4
  source: ${APP_DIR}/jcl/hello.jcl
Sourcing JCL

JCL can be submitted from three different sources: datasets, files, and strings.

Dataset: Provide a fully qualified dataset.

# Source from a dataset
source: //${HLQ}.JCL(HELLO)

File: Provide the full path to the file that contains the JCL source.

# Source from a file
source: ${APP_DIR}/jcl/hello.jcl

String: Provide a string from inline text. This can be most effective when dealing with JCL that might require inline variable replacement. Note the use of a pipe symbol (|) to indicate that the following text should maintain newline characters.

# Source from a string
text: |
  //HELLO  JOB ,
  //       MSGCLASS=H,MSGLEVEL=(1,1),TIME=(,4),REGION=0M
  //*
  //* PRINT \"HELLO, WORLD\" ON JOB OUTPUT
  //*
  //STEP0001 EXEC PGM=IEBGENER
  //SYSIN    DD DUMMY
  //SYSPRINT DD SYSOUT=*
  //SYSUT1   DD *
  HELLO, WORLD
  /*
  //SYSUT2   DD SYSOUT=*
  //

Encoding: You can optionally provide the source encoding of the JCL. If encoding is not provided, DBB will infer the code page based on system defaults and file tagging.

# Provide source encoding (e.g. IBM-1047, UTF-8)
sourceEncoding: IBM-1047
  1. Define a log file to store the JCL output:
- step: JCLTutorial
  type: job
  maxRC: 4
  source: ${APP_DIR}/jcl/hello.jcl
  logs:
    - log: ${LOGS}/jcl/${FILE}.log
      ddname: "*"
Logging

You can define any number of log files to save job output. Ensure that the specified log file is unique, as each log will overwrite existing logs. In this example, the ${FILE} variable is used for this purpose. You must specify the ddname to save in the form DD:STEP:PROC. To store all job output, use "*". By default, zBuilder will store output in the default encoding used by the system, but you can optionally specify logEncoding to target another code page (and optionally define sourceEncoding if zBuilder fails to correctly resolve the system code page).

Note: Because job steps interact directly with the JESx spool, job output has to remain on the spool long enough to gather status and output. Therefore, a job class that does not immediately archive or delete the output must be used.

logs:

  # Store all output
  - log: ${LOGS}/jcl/${FILE}.log
    ddname: "*"

  # Store all output in UTF-8
  - log: ${LOGS}/jcl/${FILE}_UTF8.log
    ddname: "*"
    logEncoding: UTF-8

  # Only store SYSPRINT logs
  - log: ${LOGS}/jcl/${FILE}_SYSPRINT.log
    ddname: SYSPRINT

Summary

You should now have all the building blocks to write and implement your own JCL within a Language Task job step.

---
version: 1.0.0
tasks:
  # zBuilder configuration goes here...

  - language: JobTest
    # Language Configuration goes here...

    steps:

      # Configure JCL
      - step: JCLTutorial
        type: job
        maxRC: 4
        source: ${APP_DIR}/jcl/hello.jcl
        logs:
          - log: ${LOGS}/jcl/${FILE}.log
            ddname: "*"

Next steps

  • Read more about job steps in the Job Step Reference.
  • Follow the tutorials for other language task step types.