Comment Lines (//*) in JCL

Purpose

Comment lines in JCL are used to document job streams, provide information about job purpose, history, or processing logic, and improve readability without affecting job execution. JCL comments are denoted by the //* prefix and are ignored by the JES processor during job execution.

Key Benefit:

Effective use of comment lines is essential for maintaining, troubleshooting, and understanding complex JCL procedures, particularly in enterprise environments where multiple developers work with the same JCL.

Basic Syntax

jcl
1
//* Any text following this prefix is treated as a comment and is ignored during execution

Comment Format Rules

  • Must begin with //* in columns 1-3
  • No spaces are allowed between the slashes and the asterisk
  • Comments can contain any text after the //* prefix
  • Comments can appear anywhere in a JCL stream
  • A comment line cannot be continued to the next line
  • Maximum length is 80 characters (including the //* prefix)

Usage Examples

Basic Comments

jcl
1
2
3
4
5
6
//PAYROLL JOB (ACCT),'JOHN DOE',CLASS=A
//* This job processes the bi-weekly payroll run
//* Created: 2023-10-15
//* Author: Jane Smith
//* Modified: 2024-03-20 - Added deduction processing
//STEP01 EXEC PGM=PAYPROC

This example shows basic documentation comments at the beginning of a job, including creation date, author, and modification history.

Section Dividers

jcl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//YEAREND JOB (ACCT),'FINANCE',CLASS=A
//*
//*=================================================================
//* YEAR-END PROCESSING - FINANCIAL REPORTING SEQUENCE
//*=================================================================
//*
//STEP01 EXEC PGM=GLCLOSE
//INPUT1 DD DSN=FINANCE.GL.MASTER,DISP=SHR
//OUTPUT1 DD DSN=FINANCE.GL.YEAREND,DISP=(NEW,CATLG,DELETE),
//           SPACE=(CYL,(50,20))
//*
//*=================================================================
//* GENERATE TAX REPORTS
//*=================================================================
//*
//STEP02 EXEC PGM=TAXREPT

This example demonstrates how to use comment lines as section dividers to visually separate logical parts of a complex job.

Documenting Technical Details

jcl
1
2
3
4
5
6
7
8
9
10
11
//EXTRACT JOB (ACCT),'DATA TEAM',CLASS=A
//STEP01 EXEC PGM=DBEXTRACT
//SYSIN DD *
  SELECT * FROM CUSTOMER WHERE REGION='WEST'
/*
//* Note: This DD statement uses a DCB override to match the
//* characteristics of the source database export format.
//* LRECL=4092 is required to prevent truncation of long records.
//OUTPUT DD DSN=CUSTOMER.EXTRACT,DISP=(NEW,CATLG,DELETE),
//          SPACE=(CYL,(100,50)),
//          DCB=(RECFM=VB,LRECL=4092,BLKSIZE=0)

This example shows comments used to explain technical parameters and configuration decisions that might not be obvious to other developers.

Comment Types and Best Practices

Comment TypePurposeBest Practice
Header CommentsDocument job purpose, author, creation datePlace at the beginning of the job, use consistent format
Section DividersSeparate logical sections of complex jobsUse distinctive visual patterns like series of characters
Technical NotesExplain complex parameters or technical decisionsPlace immediately before the relevant JCL statement
Change LogTrack modifications, dates, and reasonsInclude date, author, and concise description of changes
Dependency NotesDocument dependencies on other jobs or resourcesList dependent jobs, datasets, or timing requirements

Commenting Strategies

Standard Header Template

jcl
1
2
3
4
5
6
7
8
9
//*=====================================================
//* JOB NAME: jobname 
//* PURPOSE: Brief description of job purpose
//* AUTHOR: Creator name
//* CREATED: YYYY-MM-DD
//* MODIFIED: YYYY-MM-DD by Name - Reason
//* DEPENDENCIES: List any dependencies
//* NOTES: Any special instructions or information
//*=====================================================

Using a consistent header template makes it easier to locate important information about a job at a glance.

Visual Separation Techniques

jcl
1
2
3
4
5
6
7
8
9
10
11
//*-----------------------------------------------------
//* SECTION TITLE
//*-----------------------------------------------------
 
//*+++++++++++++++++++++++++++++++++++++++++++++++++++
//* IMPORTANT SECTION - REQUIRES CAREFUL MONITORING
//*+++++++++++++++++++++++++++++++++++++++++++++++++++
 
//*#####################################################
//* CRITICAL ERROR HANDLING SECTION
//*#####################################################

Different visual patterns can be used to distinguish different types of sections or importance levels.

Commenting vs. Disabled JCL

It's important to distinguish between true comment lines that begin with //* and disabled JCL statements where the // is replaced with //* to temporarily disable them:

jcl
1
2
3
4
5
6
7
8
//PAYROLL JOB (ACCT),'JOHN DOE',CLASS=A
//STEP01 EXEC PGM=PAYPROC
//INPUT DD DSN=PAYROLL.INPUT,DISP=SHR
//* This is a genuine comment line
//* The following line is disabled JCL, not a true comment
//*OUTPUT DD DSN=PAYROLL.OUTPUT,DISP=(NEW,CATLG,DELETE),
//*          SPACE=(CYL,(10,5))
// This line would cause a JCL error since it begins with // followed by a space

Note that using //* to disable JCL statements is a common practice, but these are technically different from true comment lines meant solely for documentation.

Common Use Cases

  • Documentation: Explaining job purpose, processing logic, and special instructions
  • Change Management: Tracking modifications, dates, and reasons for changes
  • Troubleshooting Aids: Providing hints about common issues or debugging information
  • Visual Organization: Breaking large jobs into visually distinct sections
  • Technical Notes: Explaining unusual parameters or configuration choices
  • Temporary Disabling: Commenting out JCL statements temporarily during testing
  • Reference Information: Including contact information, related documentation, or system notes

Best Practices

  • Use comments consistently throughout your JCL procedures
  • Create standardized comment templates for headers and section dividers
  • Keep comments updated when modifying JCL
  • Include a change log to track modifications
  • Document dependencies, especially timing or dataset requirements
  • Place comments strategically - immediately before relevant code sections
  • Be concise but informative - overly verbose comments can reduce readability
  • Consider using different visual styles to indicate different types of sections
  • Document any unusual or complex JCL syntax or parameters
  • Include contact information for the responsible team or developer

JES2 vs JES3 Considerations

Comment lines work the same way in both JES2 and JES3 environments. There are no syntax differences for basic comments.

Note:

While the basic //* comment syntax is identical between JES2 and JES3, be aware that JES3 has some special comment formats for specific control functions that aren't standard comments. These special formats are covered in JES3 documentation separately.

Related Concepts