Using symbols in JES in-stream data
For programming flexibility and efficiency, symbolic substitution is supported for data that is contained within JES 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 JES when an in-stream data set is read.
- 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).
SYSUID is a special type of JCL symbol, which is set and maintained by JES. Unlike other JCL symbols, the value for the SYSUID symbol is substituted in the in-stream data even if it was not explicitly EXPORTed in the JCL stream of the job. The value that is used for substitution in the in-stream data is the same as the one used during conversion, except when the SYSUID symbol was modified by the SET JCL statement but not EXPORTed. In this case, the conversion uses the modified value of the symbol, whereas the original value is used for the in-stream data. If this is not the result you want, use the EXPORT JCL statement to ensure that the value used for the in-stream data is the same as that used by conversion.
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. See 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.
- 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 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.
Another difference is the treatment of multiple adjacent ampersand characters. When two adjacent ampersand characters are encountered in the in-stream data, two-to-one ampersand compression does not occur. This simplifies using symbol substitution in the in-stream data that is intended for applications that routinely depend on double ampersand characters, such as IBM High Level Assembler (HLASM).
See Defining and nullifying JCL symbols for additional information.