Instream Procedures

Purpose

Instream procedures are procedures that are defined within the JCL input stream of a job, rather than being stored in a procedure library. They allow you to define a sequence of JCL statements once within a job and execute it multiple times with different parameters, without the need to create and maintain a separate cataloged procedure.

Structure

Basic Format

1
2
3
4
5
6
7
8
//jobname  JOB parameters...
//procname PROC [parameters...]
//stepname EXEC PGM=program
//DDname   DD   parameters...
//         ...
//         PEND
//         
//execstep EXEC procname[,parameter overrides...]

Components

Usage Examples

Simple Instream Procedure

1
2
3
4
5
6
7
8
9
//MYJOB    JOB (ACCT#),'JOHN DOE',CLASS=A
//*
//MYPROC   PROC
//STEP1    EXEC PGM=IEFBR14
//DD1      DD   DSN=MY.DATASET,DISP=(NEW,CATLG),
//             SPACE=(TRK,(10,5)),UNIT=SYSDA
//         PEND
//*
//RUN1     EXEC MYPROC

This example defines a simple procedure that creates a new dataset and then executes it once.

Instream Procedure with Parameters

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//COPYJOB  JOB (ACCT#),'JANE SMITH',CLASS=A
//*
//COPYPROC PROC DSN1='MY.INPUT.DATASET',
//             DSN2='MY.OUTPUT.DATASET'
//COPY     EXEC PGM=IEBGENER
//SYSUT1   DD   DSN=&DSN1,DISP=SHR
//SYSUT2   DD   DSN=&DSN2,DISP=(NEW,CATLG),
//             SPACE=(TRK,(10,5)),UNIT=SYSDA
//SYSIN    DD   DUMMY
//SYSPRINT DD   SYSOUT=*
//         PEND
//*
//RUN1     EXEC COPYPROC
//*
//RUN2     EXEC COPYPROC,DSN1='PROD.DATA',DSN2='PROD.COPY'

This example defines a procedure with parameters for copying a dataset, then executes it twice: once with default parameter values and once with overridden values.

Multiple Instream Procedures

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//MULTIJOB JOB (ACCT#),'ADMIN',CLASS=A
//*
//CLEAN    PROC
//STEP1    EXEC PGM=IEFBR14
//DD1      DD   DSN=TEMP.DATASET,DISP=(MOD,DELETE)
//         PEND
//*
//CREATE   PROC TYPE='DATA',NAME='DEFAULT'
//STEP1    EXEC PGM=IEFBR14
//DD1      DD   DSN=&NAME..&TYPE,DISP=(NEW,CATLG),
//             SPACE=(TRK,(10,5)),UNIT=SYSDA
//         PEND
//*
//RUN1     EXEC CLEAN
//RUN2     EXEC CREATE,TYPE=MASTER,NAME=PROD

This example defines two different instream procedures and executes them in the same job.

Conditional Processing in Instream Procedures

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//CONDJOB  JOB (ACCT#),'ADMIN',CLASS=A
//*
//CONDPROC PROC ENV='PROD',DEBUG=N
//STEP1    EXEC PGM=MYPROG
//INPUT    DD   DSN=&ENV..DATA,DISP=SHR
//OUTPUT   DD   DSN=&ENV..OUTPUT,DISP=(NEW,CATLG),
//             SPACE=(TRK,(10,5)),UNIT=SYSDA
//DEBUG    DD   DUMMY
//         IF &DEBUG=Y THEN
//DEBUG    DD   SYSOUT=*
//TRACE    DD   SYSOUT=*
//         ENDIF
//         PEND
//*
//TEST     EXEC CONDPROC,ENV=TEST,DEBUG=Y
//PROD     EXEC CONDPROC

This example defines a procedure with conditional processing based on parameter values, then executes it with different parameter combinations.

Key Features and Limitations

Features

• Self-contained - All JCL components are in one place, making it easier to understand the complete job
• Immediate availability - No need to update procedure libraries before using modified procedures
• Multiple executions - Can be executed multiple times in the same job with different parameters
• Support for symbolic parameters - Can use parameters with default values that can be overridden during execution
• Conditional processing - Can include IF/THEN/ELSE statements for dynamic behavior

Limitations

• Limited to current job - Cannot be called from other jobs
• Not shareable - Must be redefined in each job that needs them
• Maintenance overhead - Changes must be made in every job that contains the procedure
• Procedure name scope - Must be unique within the job
• Position in JCL - Must be defined before they are referenced

Rules and Considerations

Naming Rules

• Procedure names must be 1-8 characters long
• Valid characters include letters A-Z, numbers 0-9, and special characters @, #, and $
• The first character must be a letter or special character (@, #, $)
• Procedure names must be unique within a job
• Procedure names should not conflict with step names in the same job

Order of Statements

1. An instream procedure must be defined before it is referenced by an EXEC statement
2. Multiple instream procedures can be defined in succession
3. Instream procedures can appear at any point in a job before they are referenced
4. The PEND statement must follow the last statement of the procedure
5. JCLLIB statements, if used, should precede instream procedures

Symbolic Parameter Rules

• Parameters are defined on the PROC statement
• Default values can be specified for parameters
• Parameters can be overridden on the EXEC statement that calls the procedure
• Parameter names must follow JCL naming conventions
• Parameter values can include special characters when enclosed in apostrophes

Common Use Cases

Testing and Development

• Testing modifications to a procedure before updating a cataloged procedure
• Developing new procedures without having to create entries in a procedure library
• Creating temporary variations of standard procedures for special situations

One-time or Rarely Used Processes

• Special data conversion or cleanup operations
• Emergency recovery processes
• Procedures specific to a single job or application

Repeating Patterns Within a Job

• Processing multiple datasets with the same steps but different parameters
• Running the same process for different environments (dev/test/prod)
• Performing initialization and cleanup operations multiple times

Best Practices

1. Use clear naming conventions for procedures and parameters
2. Include comments to document the purpose and usage of the procedure
3. Group related instream procedures together for better organization
4. Provide default values for all parameters when possible
5. Consider converting frequently used instream procedures to cataloged procedures
6. Use conditional processing to make procedures more flexible
7. Validate parameter values within the procedure when possible
8. Keep procedures focused on a single logical function for better reusability

Troubleshooting

Common Issues

Debugging Tips

• Use MSGLEVEL=(1,1) on the JOB statement to see expanded procedures in the job log
• Add JCLDUMP DD SYSOUT=* to see JCL after parameter substitution
• Add comments (//*) to document the procedure and its parameters
• Test complex procedures with simplified steps before implementing fully
• Use TYPRUN=SCAN on the JOB statement to check for JCL errors without executing the job

JES2 vs. JES3 Considerations

Instream procedures are supported in both JES2 and JES3 environments with some differences:

• Both JES2 and JES3 support basic instream procedure functionality
• JES3 provides additional features for instream procedures in //*PROCESS statements
• JES3 supports procedure libraries defined with //*MAIN PROC= statements
• In both environments, instream procedures are processed by the converter before job execution
• Specific system implementations may have additional restrictions or extensions

Comparison: Instream vs. Cataloged Procedures

Related Concepts

• Cataloged Procedures - Procedures stored in procedure libraries for system-wide use
• PROC Statement - Defines the beginning of a procedure and its parameters
• PEND Statement - Marks the end of a procedure definition
• Symbolic Parameters - Variables used to customize procedures
• JCLLIB Statement - Specifies procedure libraries for a job