BEGIN and END directives

Purpose

These directives, used in pairs, denote the following, depending on the value of the ACTION keyword:
  • The start and end of HCL Workload Automation for Z variable substitution.
  • The start and end of the lines to be included in the tailored job.
  • The start and end of the lines to be excluded from the tailored job.

Syntax


1  //*%OPC BEGIN
1+ .,
1  ACTION=
2.1 EXCLUDE
2.1 INCLUDE
2.1 NOSCAN
1?  PHASE=
2.1! SUBMIT
2.1 SETUP
1?  COMP= ( + ., ( comparison expression ) )

1  //*%OPC END  ACTION=
2.1 EXCLUDE
2.1 INCLUDE
2.1 NOSCAN

Parameters

ACTION=(EXCLUDE|INCLUDE|NOSCAN)
Specifies which BEGIN/END action is required.
EXCLUDE
This specifies that the lines following this BEGIN directive up to the next END ACTION=EXCLUDE directive should be excluded from the job that is submitted for this operation.
INCLUDE
This specifies that the lines following this BEGIN directive up to the next END ACTION=INCLUDE directive should be included as part of the job that is submitted for this operation.
NOSCAN
This specifies that any variables following this BEGIN directive up to the next END ACTION=NOSCAN directive should not be substituted. When you specify NOSCAN, you do not specify a PHASE parameter, because NOSCAN is valid at both submit and at setup.
PHASE=SETUP|SUBMIT
Specifies whether the BEGIN/END pair should take effect during the setup or submit phase of the operation. This parameter is required only if ACTION=EXCLUDE or INCLUDE.
COMP=((comparison expression), (comparison expression),...)
Specifies comparison expressions that are used to decide whether the BEGIN directive should be acted on. If the comparison expression is true, the BEGIN directive is honored. For details on defining comparison expressions, see The COMP keyword on BEGIN and FETCH directives.

Usage Notes

In a job, every BEGIN directive must have a matching END directive specifying the same ACTION. For example, the directive:

//*%OPC BEGIN ACTION=EXCLUDE,PHASE=SUBMIT

requires the following matching END directive:

//*%OPC END ACTION=EXCLUDE

If HCL Workload Automation for Z detects an unpaired BEGIN or END, the processing ends in error. Even a BEGIN statement that is not honored because its comparison expression is not true requires a matching END statement.

Only the following directives can lie within the domain of a BEGIN ACTION=NOSCAN directive and an END ACTION=NOSCAN directive:
  • SEARCH
  • SETFORM
  • SETVAR
  • TABLE
When these directives are in the range of a NOSCAN directive, they are always acted upon even if there is a comparison condition that is false.
Note: When the SETVAR directive is within the NOSCAN range, all the variables in the same NOSCAN range that follow SETVAR are in any case substituted.

BEGIN and END directives that specify ACTION=INCLUDE or ACTION=EXCLUDE cannot be nested and cannot overlap. They can, however, completely contain a nested NOSCAN domain.

Consider the following examples:

Example 1
//*%OPC SCAN
//*%OPC BEGIN PHASE=SETUP,ACTION=INCLUDE          1
//DDNAME1 DD DSN=&HIONE..&DATASET1,DISP=SHR       2
//DDNAME2 DD DSN=&HIONE..&DATASET2,DISP=SHR       3
//*%OPC END ACTION=INCLUDE                        4

Example 1 is valid. Lines 2 and 3 will be included in the job for the operation.

Example 2
//*%OPC SCAN                                       1
//*%OPC BEGIN PHASE=SUBMIT,ACTION=EXCLUDE          2
//EXEC PGM=MYPROG                                  3
//*%OPC BEGIN PHASE=SETUP ACTION=INCLUDE           4
//DDNAME1 DD DSN=&HIONE..&DATASET1,DISP=SHR        5
//SYSOUT  DD SYSOUT=A                              6
//*%OPC END ACTION=EXCLUDE                         7
//DDNAME2 DD DSN=&HIONE..&DATASET2,DISP=SHR        8
//*%OPC END ACTION=INCLUDE                         9

Example 2 is invalid. An EXCLUDE action (lines 2 and 7) overlaps an INCLUDE action (lines 4 and 9). Error message EQQJ533 will be issued.

Example 3
//*%OPC SCAN                                       1
//*%OPC BEGIN PHASE=SUBMIT,ACTION=INCLUDE          2
//EXEC PGM=MYPROG                                  3
//*%OPC BEGIN ACTION=NOSCAN                        4
//DDNAME1 DD DSN=&HIONE..&DATASET1,DISP=SHR        5
//SYSOUT  DD SYSOUT=A                              6
//*%OPC END ACTION=NOSCAN                          7
//DDNAME2 DD DSN=&HIONE..&DATASET2,DISP=SHR        8
//*%OPC END ACTION=INCLUDE                         9

Example 3 is valid. The NOSCAN domain defined by lines 4 and 7 is completely contained within the BEGIN and END ACTION=INCLUDE (lines 2 and 9).

Note also that the variable HIONE on line 8 will be substituted, but the variable HIONE on line 5 will not be substituted because it is within a NOSCAN domain.

BEGIN and END directives that specify ACTION=INCLUDE or ACTION=EXCLUDE can modify the structure of JCL from one run to another. For this reason, to apply again the same directives in a Restart and Cleanup path, ensure that they do not alter the structure of the JCL. For details, see JCL changes considerations.