Using symbols in JES2 in-stream data

For programming flexibility and efficiency, symbolic substitution is supported for data that is contained within JES2 in-stream data sets. Unlike symbolic substitution in the JCL stream of a job, which is performed by the JCL converter during processing of JCL statements, in-stream symbolic substitution is performed by JES2 when an in-stream data set is read.

The three types of symbols that can be used for JES2 in-stream substitution are JCL Symbols, JES Symbols and System Symbols:

JCL symbols

By default, JCL Symbols are only available to the job at the converter phase and are lost by the time the job runs. However, by using the EXPORT and SET JCL statements, JCL symbols can be made available to the job execution phase.

Any JCL symbols that are inherited from a submitting job through the internal reader SYMLIST facility are implicitly exported. Exported JCL Symbols can be accessed during the job execution phase using the JCL Symbol Service (IEFSJSYM) or the JES Symbol Service (IAZSYMBL).

The JCL Symbol Service (IEFSJSYM) is documented in z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG.

JES symbols

JES Symbols are dynamic symbols that can be managed and manipulated using the JES Symbol Service (IAZSYMBL). The JES Symbol Service is documented in z/OS JES Application Programming.

System symbols

System Symbols are specific to the MVS system. Refer to Using system symbols and JCL symbols and the ASASYMBM service in z/OS MVS Programming: Assembler Services Reference ABE-HSP). System symbols are defined in the IEASYMxx member of SYS1.PARMLIB, and are described in z/OS MVS Initialization and Tuning Reference.

The type of symbol substitution used for the in-stream data is controlled by the SYMBOLS keyword coded on the DD statement that defines the in-stream data set. Without the SYMBOLS keyword, JES does not perform symbol substitution for the in-stream data set and the application interprets the data exactly as it is entered in the data set.

The SYMBOLS keyword can be defined as follows:

SYMBOLS=JCLONLY: Names of JCL symbols and JES symbols found in the in-stream data set are replaced with their values.
SYMBOLS=EXECSYS: Substitution follows the SYMBOLS=JCLONLY rule. In addition, system symbols defined on the system during job execution can be used in the in-stream data.
SYMBOLS=CNVTSYS: Substitution follows the SYMBOLS=EXECSYS rule, with the exception that system symbols used for substitution are taken not from the system where the job is executing, but from the system where the job has undergone JCL conversion.
The symbols will have values that they had at the time of JCL conversion.

The syntax rules for using symbols in in-stream data include those described previously for using symbols in JCL. One important difference is the handling of blanks in the input data. When symbols are substituted in JCL statements, there is no special treatment of blanks—as symbols are substituted, the resulting string expands or contracts depending on whether the symbol value is longer or shorter than the symbol expression (symbol name with a leading ampersand character and optional period at the end of the symbol name). When symbols are substituted in in-stream data, the system attempts to maintain the position of non-blank characters. This is achieved by adding or removing blanks between non-blank character sequences. At least one blank is always preserved to maintain syntactical validity of the data. The resulting string never contracts and only expands if there are not enough blanks to remove to maintain data positioning. Refer to Defining and nullifying JCL symbols for additional information.