In-stream Job Comments

Purpose

In-stream JCL comments provide a way to document job streams directly within the JCL code itself. These comments explain the purpose, requirements, and functionality of JCL jobs, making maintenance, troubleshooting, and knowledge transfer easier for operations teams and developers.

Key Benefit:

In-stream comments embed documentation directly alongside the code it describes, ensuring that explanations, requirements, and contextual information remain with the JCL as it moves through development, testing, and production environments.

Types of JCL Comments

Comment Type	Syntax	Usage
Comment Statement	`//* comment text`	Full line dedicated to a comment
JES2 Comment	`/* comment text`	JES2-specific comment style
JES3 Comment	`//*comment text`	JES3-specific comment style (no space after asterisk)
Inline Comment	Any text after valid JCL parameters	Comments at the end of JCL statements
Comment Block	Multiple consecutive comment lines	Detailed explanations or section headers
Comment Cards	`//COMMENT DD *`	Using DD statements solely for documentation

Comment Statement Syntax

Standard Comment Statement

jcl

1
2
3
//* This is a standard JCL comment statement.
//* It begins with //*, followed by a space, then the comment text.
//* Multiple comment lines can be used in sequence.

The comment statement consists of //* followed by a space and then the comment text. The entire line is treated as a comment and is not processed as an executable JCL statement.

JES2 Comment

jcl

1
2
/* This is a JES2-specific comment.
/* These comments have a single slash, followed by an asterisk.

JES2 comments begin with /* and are specific to JES2 environments. They are ignored by the JCL interpreter.

JES3 Comment

jcl

1
2
//*This is a JES3-specific comment with no space after the asterisk.
//*These comments can control JES3 processing.

JES3 comments begin with //* (no space after the asterisk). Some JES3 comments can have special meanings when they begin with specific keywords like //*MAIN, //*FORMAT, etc.

Inline Comments

jcl

1
2
//STEP1 EXEC PGM=PAYROLL,REGION=4M   Runs the payroll program
//INFILE DD DSN=ACCT.MASTER,DISP=SHR   Master account file

Text appearing after valid JCL parameters is treated as a comment. However, this practice requires careful consideration of parameter formats to ensure the JCL is correctly parsed.

Warning:

With inline comments, be careful not to place them where the JCL processor might interpret them as continuation indicators or parameters, which could cause syntax errors.

Comment Organization Patterns

Job Header Block

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//*-----------------------------------------------------------------
//* JOB NAME: PAYROLL
//* AUTHOR:   John Smith
//* DATE:     2023-06-15
//* PURPOSE:  Monthly payroll processing and report generation
//* 
//* DEPENDENCIES:
//*   - Requires ACCT.MASTER to be updated by ACCTUPDT job
//*   - Requires PAYROLL.RATES file to have current rates
//*
//* RETURN CODES:
//*   0  - Successful execution
//*   4  - Minor issues, review reports
//*   8+ - Processing failure, contact support
//*-----------------------------------------------------------------

A header block at the beginning of a job provides essential documentation about the job's purpose, dependencies, and expected behaviors.

Step Documentation

jcl

1
2
3
4
5
6
7
//*-----------------------------------------------------------------
//* STEP1: DATA VALIDATION
//* Validates input data and produces error report if needed.
//* Expected duration: 5-10 minutes (normal volume)
//*-----------------------------------------------------------------
//STEP1   EXEC PGM=VALIDATE
//SYSOUT  DD SYSOUT=*

Comments preceding each step explain what the step does, what to expect, and any special considerations.

Change History

jcl

1
2
3
4
5
6
//*-----------------------------------------------------------------
//* CHANGE HISTORY:
//* 2023-06-15 - J.Smith  - Initial implementation
//* 2023-07-22 - A.Johnson - Added tax calculation step
//* 2023-09-03 - B.Williams - Updated for new payroll rates file
//*-----------------------------------------------------------------

A change history section tracks modifications to the JCL over time, providing an audit trail of updates.

Usage Examples

Comprehensive Job Documentation

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
//*=================================================================
//* JOB:     MTHLY_ACCT
//* PURPOSE: MONTHLY ACCOUNT PROCESSING AND REPORTING
//* AUTHOR:  JANE DOE (EXT. 5555)
//* DATE:    2023-10-01
//*=================================================================
//* PRE-REQUISITES:
//*   - DAILY_CLOSE JOB MUST COMPLETE SUCCESSFULLY
//*   - ACCT.MASTER MUST BE BACKED UP (BKUP_ACCT JOB)
//*=================================================================
//* FREQUENCY: MONTHLY (LAST BUSINESS DAY)
//* RUNTIME:   APPROX. 45 MINUTES
//* RESTART:   AT STEP THAT FAILED, AFTER RESOLVING ISSUE
//*=================================================================
 
//MTHLY_ACCT JOB (ACCT),'MONTHLY PROCESSING',
//          CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
 
//*-----------------------------------------------------------------
//* STEP1: VALIDATE INPUT DATA
//* Validates that all required input files are available and correct
//*-----------------------------------------------------------------
//STEP1   EXEC PGM=VALIDATE
//SYSOUT  DD SYSOUT=*
//MASTER  DD DSN=ACCT.MASTER,DISP=SHR
 
//*-----------------------------------------------------------------
//* STEP2: GENERATE MONTHLY REPORTS
//* Creates standard monthly reports for distribution
//*-----------------------------------------------------------------
//STEP2   EXEC PGM=REPORTER,COND=(0,LT,STEP1)
//SYSOUT  DD SYSOUT=*
//INPUT   DD DSN=ACCT.MASTER,DISP=SHR
//REPORT  DD DSN=ACCT.MONTHLY.REPORT,
//           DISP=(NEW,CATLG,DELETE),
//           SPACE=(CYL,(5,2)),
//           DCB=(RECFM=FBA,LRECL=133,BLKSIZE=27930)

This example shows a fully documented job with header information, prerequisites, step documentation, and other details that make the JCL self-documenting.

Technical Documentation in Comments

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
//*=================================================================
//* COMPLEX SORT PROCESSING
//*=================================================================
//* THIS JOB PERFORMS A MULTI-PHASE SORT WITH THE FOLLOWING LOGIC:
//*
//* 1. PRE-PROCESS: Filter invalid records from input
//* 2. PRIMARY SORT: Sort by account number (ascending)
//* 3. SECONDARY SORT: Within each account, sort by date (descending)
//* 4. POST-PROCESS: Summarize transactions and generate totals
//*
//* SORT KEYS:
//*   PRIMARY:   POS 1-10  (CHAR) - ACCOUNT NUMBER
//*   SECONDARY: POS 11-18 (CHAR) - TRANSACTION DATE (YYYYMMDD)
//*=================================================================
 
//MYSORT   JOB (ACCT),'COMPLEX SORT',CLASS=A
//STEP1    EXEC PGM=SORT
//SORTIN   DD DSN=ACCT.TRANS.DATA,DISP=SHR
//SORTOUT  DD DSN=ACCT.SORTED.DATA,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(10,5)),
//            DCB=(RECFM=FB,LRECL=100,BLKSIZE=32700)
//SYSIN    DD *
  SORT FIELDS=(1,10,CH,A,11,8,CH,D)
  INCLUDE COND=(25,1,CH,EQ,C'V')
/*

This example includes detailed technical documentation about a complex sort operation, explaining the multi-phase process and defining the sort keys clearly.

Comment Sections for Standard Jobs

Effective JCL documentation typically includes these standard sections:

Job Identification: Job name, purpose, author, creation date
Dependencies: Prerequisites, required input files, job scheduling requirements
Execution Information: Expected runtime, resource requirements, restart procedures
Step Documentation: Purpose of each step, expected outputs, error handling
Return Codes: Meaning of various return codes the job might produce
Special Handling: Any manual interventions that might be required
Change History: Log of modifications to the JCL
Contact Information: Who to contact for issues or questions

Best Practices

Be consistent with comment formatting to make JCL easier to read and maintain
Use visual separators like //*------------------ to organize comment blocks
Document all non-obvious JCL statements, especially complex conditions or unusual parameters
Include contact information in job headers for support purposes
Explain any special conditions or requirements needed for successful job execution
Document expected return codes and what they mean
Update comments when changing JCL to maintain documentation accuracy
Include a change history to track modifications over time
Avoid overly verbose comments that may make the JCL harder to read
Use consistent language for similar concepts throughout all JCL documentation

Automation and Standards Considerations

Many organizations implement standards and automation for JCL comments:

Automated Headers: Scripts or tools that generate standard JCL headers with job information
Comment Templates: Standardized templates for different types of jobs
Documentation Extraction: Tools that extract comments to generate job documentation
JCL Standards Enforcement: Automated validation of proper documentation during code review

Example Comment Template

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//*=================================================================
//* JOB:     <>
//* PURPOSE: <>
//* AUTHOR:  <> (<>)
//* DATE:    <>
//*=================================================================
//* PRE-REQUISITES:
//*   - <>
//*=================================================================
//* FREQUENCY: <>
//* RUNTIME:   <>
//* RESTART:   <>
//*=================================================================
 
//<> JOB <>,'<>',
//          CLASS=<>,MSGCLASS=<>,NOTIFY=<>

Many organizations use standard templates like this, which developers complete before submitting new jobs.

Common Issues and Troubleshooting

Issue	Possible Causes	Solutions
Comment accidentally interpreted as JCL	Incorrect comment format or missing asterisk	Ensure comment lines begin with //* with the correct format Check for typos in comment indicators
JCL interpreted as comment	JCL statement inadvertently formatted as a comment	Review JCL lines to ensure actual commands don't begin with comment indicators Use distinct visual separators between comments and code
Inline comment causing JCL error	Inline comment placed where a continuation might be expected	Use only standard comment lines (//*) for documentation Be cautious with inline comments, especially near continued lines
Outdated comments	Comments not updated when JCL was modified	Implement a policy to update comments with code changes Include comment review in code review process

JES2 vs JES3 Considerations

Comment handling has some differences between JES2 and JES3:

Feature	JES2	JES3
Comment format	Supports both //* and /* formats	Uses //* format, often without space after *
Special processing	/$ and /# have special meanings in some contexts	//MAIN, //FORMAT, etc. are JES3 control statements
Comment message display	Most comments not displayed in job output	Some comment formats may appear in job output

Note:

With z/OS 2.5, JES3 is being phased out in favor of JES2, making JES2-specific behaviors the standard moving forward.

Related Concepts

Comment Lines - Basic JCL comment syntax
JCL Variables - Variables that can be documented in comments
JCL Operator Messages - Messages sent to operators
Symbolic Parameters - Parameters that should be documented in comments
JOB Statement - Main job statement that often has header comments