APAR status
Closed as documentation error.
Error description
When properly coding a SET statement for a symbol that is to be used in a proc, the symbol is not substituted correctly. It is applied to the last step of the proc only. If the symbol was used prior to the step invoking the proc, the old value is used for steps other then the last. See the local fix for a cirumvention. Additional Symptoms: As shown below, the JCL output was as expected for each mainline JCL substitution. However, the SYSIN substitution might not work as expected, and then the question becomes "Why don't we see EXAMPLE1 in the SYSIN Output for the 1st SYSIN substitution, and why is the outcome identical for both the 2nd & 3rd SYSIN substitutions?" Explanation: By including the Set Statement after the Job Step's EXEC Statement and before the next Job Step's EXEC Statement, the Exported symbol will resolve to its last known SET inside of the job step, or if not SET within the current job step, the symbol will resolve to its last known SET outside of the job step. Hence, why we see EXAMPLE2 in the output for the 1st SYSIN sub and EXAMPLE3 for the 2nd and 3rd SYSIN Sub. For Example: // EXPORT SYMLIST=(*) // SET EX1=EXAMPLE1 // SET EX2=EXAMPLE2 // SET EX3=EXAMPLE3 //****************************** // SET IBM=&EX1 <-- 1st Mainline JCL Sub. //JOBSTEP1 EXEC PGM=XYZ //SYSIN DD *,SYMBOLS=JCLONLY THE OUTPUT &IBM <<<-- 1st SYSIN Sub. //****************************** // SET IBM=&EX2 <-- 2nd Mainline JCL Sub. //JOBSTEP2 EXEC PGM=XYZ //SYSIN DD *,SYMBOLS=JCLONLY THE OUTPUT &IBM <<<-- 2nd SYSIN Sub. //****************************** // SET IBM=&EX3 <-- 3rd Mainline JCL Sub. //JOBSTEP3 EXEC PGM=XYZ //SYSIN DD *,SYMBOLS=JCLONLY THE OUTPUT &IBM <<<-- 3rd SYSIN Sub. //****************************** ===================================================== Output: The JCL Mainline OUTPUT: 1st JCL Sub = IEFC653I SUBSTITUTION JCL IBM=EXAMPLE1 2nd JCL Sub = IEFC653I SUBSTITUTION JCL IBM=EXAMPLE2 3rd JCL Sub = IEFC653I SUBSTITUTION JCL IBM=EXAMPLE3 ---------------------------- The SYSIN OUTPUT: 1st SYSIN Sub. = THE OUTPUT EXAMPLE2 2nd SYSIN Sub. = THE OUTPUT EXAMPLE3 3rd SYSIN Sub. = THE OUTPUT EXAMPLE3
Local fix
The easiest way to handle this, and make instream sysmbols act the same as JCL symbols, is to code a Dummy IEFBR14 step prior to the step in which you want to use the symbol. Code the SET statement after the EXEC statement.
Problem summary
**************************************************************** * USERS AFFECTED: Installations running HBB7790 or above * **************************************************************** * PROBLEM DESCRIPTION: Documentation enhancements are * * required to clarify how exported JCL * * symbols are resolved * **************************************************************** * RECOMMENDATION: * **************************************************************** JCL symbols which are exported via the EXPORT SYMLIST parameter are resolved differently than non exported symbols. This APAR provides enhancements to the JCL Reference manual to clarify how to code JCL so that exported symbols are resolved as expected. See the submitter text of this APAR for additional details.
Problem conclusion
The following documentation updates are made with this APAR: Book Title: MVS JCL Reference Book Number: SA23-1385 Chapter: EXPORT Statement - Add the text below, as flagged with "|": EXPORT statement Purpose: | Use the EXPORT statement to make specific JCL symbols | available to the job step program. Exported JCL symbols can | be accessed during the job execution phase using the JCL | Symbol Service (IEFSJSYM) or the JES Symbol Service | (IAZSYMBL). Symbols must be set to a value subsequent to the | EXPORT statement for the symbol value to be exported. | | JCL symbol values used by a job step program are not | resolved until the job step execution phase. JCL symbol | values used in JCL statements are resolved during the | job conversion phase. Consider which phase(s) that | symbol resolution will be performed when coding JCL. In | this chapter, symbols that are used by the job step | program are referred to as 'exported symbol values'. | See the SYMLIST parameter section for more details. Book Title: MVS JCL Reference Book Number: SA23-1385 Chapter: EXPORT Statement Section: SYMLIST parameter - Modify the text below, as flagged with "|": Parameter type: Keyword on EXPORT statement, required | Purpose: | Use the SYMLIST parameter to list the JCL symbolic | parameters to be exported, and therefore, made available | to the job step program. Exported symbol values can | also be passed in to in-stream (sysin) data; see Using | symbols in JES in-stream data for details. | | JCL symbol values used by a job step program are not | resolved until the job step execution phase. In this | section, JCL symbol values that are made available to | the job step program are referred to as exported symbol | values. | | Exported symbol values can be set in the JCL with the | SET statement or through PROC symbolic parameter | processing. Exported symbol values must be set at a | point in time in the job stream after the EXPORT SYMLIST | statement, and prior to or within the same job step as | the program where they are to be used. | | Exported symbol values are resolved to the last value | set prior to or within the job step that executes the | program that uses them. Exported symbol values persist | across job steps, so once an exported symbol value is | set, subsequent job step programs will receive the same | exported symbol value until the symbol is set to a new | value. See the examples section for additional | information on how exported symbol values are resolved. | | JCL Converter processing generates EXPORT EXPSET | statements to manage how exported symbol values are | resolved. These statements appear in the job log. | Reviewing the placement of EXPORT EXPSET statements in | the job log can be helpful in understanding exported | symbol value resolution for a given job. | | Using Exported symbol values in procedures: | Exported symbol values can be set in the JCL with the | SET statement or through PROC symbolic parameter | processing. SET statements that are placed immediately | following an EXEC PROC statement apply to the | exported symbol values that are used in the final step | in the procedure. : : Examples - Renumber existing example 3 to example 4, and place this example ahead of existing example 3: |3 Examples 3a and 3b both execute a procedure that contains | the following JCL: | //PROC1 PROC | //PSTEP1 EXEC PGM=IEBGENER | //SYSUT1 DD *,SYMBOLS=(JCLONLY) | PSTEP1 SYM1 VALUE = &SYM1 | //SYSUT2 DD SYSOUT=* | //SYSPRINT DD SYSOUT=* | //SYSIN DD DUMMY | //PSTEP2 EXEC PGM=IEBGENER | //SYSUT1 DD *,SYMBOLS=(JCLONLY) | PSTEP2 SYM1 VALUE = &SYM1 | //SYSUT2 DD SYSOUT=* | //SYSPRINT DD SYSOUT=* | //SYSIN DD DUMMY | //PSTEP3 EXEC PGM=IEBGENER | //SYSUT1 DD *,SYMBOLS=(JCLONLY) | PSTEP3 SYM1 VALUE = &SYM1 | //SYSUT2 DD SYSOUT=* | //SYSPRINT DD SYSOUT=* | //SYSIN DD DUMMY | //PROC1 PEND | | 3a. This example illustrates how an exported symbol | value is resolved when the SET statement resides | immediately following EXEC PROC statements. | //JOB ... | // EXPORT SYMLIST=* | // SET SYM1=ONE | //JSTEP1 EXEC PROC1 | // SET SYM1=TWO | //JSTEP2 EXEC PROC1 | //JSTEP3 EXEC PROC1 | // SET SYM1=THREE | Considering the expanded JCL shown in the job log, | the | //SYM1 EXPORT EXPSET=TWO | statement resides in the job step scope of | JSTEP1.PSTEP3. Therefore, the exported symbol value | of SYM1 is TWO beginning at step JSTEP1.PSTEP3. | //SYM1 EXPORT EXPSET=THREE | is seen in the job log in the job step scope of | JSTEP3.PSTEP3. Therefore, the exported symbol value | of SYM1 changes to THREE at step JSTEP3.PSTEP3. | SYM1 resolves to the following values: | Job Step Proc Step SYSUT1 results in | -------- ---- ----------------- | JSTEP1 PSTEP1 PSTEP1 SYM1 VALUE = ONE | JSTEP1 PSTEP2 PSTEP2 SYM1 VALUE = ONE | JSTEP1 PSTEP3 PSTEP3 SYM1 VALUE = TWO | JSTEP2 PSTEP1 PSTEP1 SYM1 VALUE = TWO | JSTEP2 PSTEP2 PSTEP2 SYM1 VALUE = TWO | JSTEP2 PSTEP3 PSTEP3 SYM1 VALUE = TWO | JSTEP3 PSTEP1 PSTEP3 SYM1 VALUE = TWO | JSTEP3 PSTEP2 PSTEP3 SYM1 VALUE = TWO | JSTEP3 PSTEP3 PSTEP3 SYM1 VALUE = THREE | 3b. This example illustrates how a job step following | an EXEC PROCV statement will affect how | exported symbol values are resolved. | //JOB ... | // EXPORT SYMLIST=* | // SET SYM1=ONE | //JSTEP1 EXEC PROC1 | //NULLSTP1 EXEC PGM=IEFBR14 | // SET SYM1=TWO | //JSTEP2 EXEC PROC1 | //NULLSTP2 EXEC PGM=IEFBR14 | // SET SYM1=THREE | //JSTEP3 EXEC PROC1 | Considering the expanded JCL shown in the job log, | the | //SYM1 EXPORT EXPSET=TWO | statement resides in the job step scope of NULLSTP1. | Therefore, the exported symbol value of SYM1 is TWO | beginning at NULLSTP1. | //SYM1 EXPORT EXPSET=THREE | is seen in the job log in the job step scope of | NULLSTP2. Therefore, the exported symbol value of | SYM1 changes to THREE beginning at step NULLSTP2. | The exported symbol value of SYM1 resolves to the | following values: | Job Step Proc Step SYSUT2 results in | -------- ---- ------------------ | JSTEP1 PSTEP1 PSTEP1 SYM1 VALUE = ONE | JSTEP1 PSTEP2 PSTEP2 SYM1 VALUE = ONE | JSTEP1 PSTEP3 PSTEP3 SYM1 VALUE = ONE | JSTEP2 PSTEP1 PSTEP1 SYM1 VALUE = TWO | JSTEP2 PSTEP2 PSTEP2 SYM1 VALUE = TWO | JSTEP2 PSTEP3 PSTEP3 SYM1 VALUE = TWO | JSTEP3 PSTEP1 PSTEP1 SYM1 VALUE = THREE | JSTEP3 PSTEP2 PSTEP2 SYM1 VALUE = THREE | JSTEP3 PSTEP3 PSTEP3 SYM1 VALUE = THREE | - Change existing example 3 to example 4 and add the following explanation test, as flagged with "|: ... | 4. Exported | symbol values passed in on PROC statements are | resolved in the scope of the job step in which they | are used. Symbols passed to nested procedures are | resolved at the procedure level that is current to | where the exported symbol value is used. The job log | of the following example will | contain | //WHO EXPORT EXPSET=xxx and | //WHAT EXPORT EXPSET=yyy | statements. Their placement in the JCL will show the | scope at which the exported symbol values are set and | received by the executing program for each step in | the job. // EXPORT SYMLIST=* //PROC2 PROC WHAT=SPOCK // SET WHO=LEONARD //P2STEP1 EXEC PGM=IEBGENER //SYSIN DD DUMMY //SYSPRINT DD SYSOUT=* //SYSUT2 DD SYSOUT=* //SYSUT1 DD *,SYMBOLS=(JCLONLY) WHO = &WHO WHAT = &WHAT //PROC2 PEND //PROC1 PROC //P1STEP1 EXEC PGM=IEBGENER //SYSIN DD DUMMY //SYSPRINT DD SYSOUT=* //SYSUT2 DD SYSOUT=* //SYSUT1 DD *,SYMBOLS=(JCLONLY) WHO = &WHO //P1STEP2 EXEC PROC2,WHAT=ROCK // SET WHAT=SCISSORS // SET WHO=SHELDON //PROC1 PEND // SET WHO=HOWARD //JSTEP1 EXEC PROC1 // SET WHO=PENNY // SET WHAT=PAPER //JSTEP2 EXEC PROC1 //JSTEP3 EXEC PROC1 // SET WHO=AMY //JSTEP4 EXEC PROC2,WHAT=LIZARD //JSTEP5 EXEC PROC2 Exported symbol values in this job will resolve for each step as follows: Step Name Proc Step WHO WHAT --------- --------- --- ---- JSTEP1 P1STEP1 HOWARD P1STEP2 P2STEP1 PENNY PAPER JSTEP2 P1STEP1 PENNY P1STEP2 P2STEP1 SHELDON SCISSORS JSTEP3 P1STEP1 PENNY P1STEP2 P2STEP1 AMY SCISSORS JSTEP4 P2STEP1 LEONARD LIZARD JSTEP5 P2STEP1 LEONARD SPOCK
Temporary fix
Comments
APAR Information
APAR number
OA52860
Reported component name
CONVERTER/INTER
Reported component ID
5752SC1B9
Reported release
790
Status
CLOSED DOC
PE
NoPE
HIPER
NoHIPER
Special Attention
NoSpecatt / Xsystem
Submitted date
2017-05-12
Closed date
2017-09-25
Last modified date
2017-09-25
APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:
| SA23138500 |
Fix information
Applicable component levels
[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19M","label":"APARs - z\/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"790","Edition":"","Line of Business":{"code":"","label":""}},{"Business Unit":{"code":null,"label":null},"Product":{"code":"SG19O","label":"APARs - MVS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"790","Edition":"","Line of Business":{"code":"","label":""}}]
Document Information
Modified date:
25 September 2017