Starting with release 5.0 PU5, it is now possible to export symbols in Enterprise Server and use them in in-stream data. It is also possible to pass symbols on jobs submitted with the help of the Internal Reader. The following examples show how SYMBOLS may be used.
The following examples are based on the JCL - Symbols sample installed with this product. See JCL - Symbols Mainframe Samples browser.
MFJUXIT=[full path and name of the MFJUXIT compiled module]
To compile the programs, use the following commands:
cbllink -d CALLMFJZ.cbl -oCALLMFJZ.dll cbllink -d MFJUXIT.cbl -oLOADLIB\MFJUXIT.dll
You can define system-wide symbols in the dataset SYS1.PARMLIB(IEASYM00). This dataset will be read when the system starts up and the values defined may then be used in JCL jobs.
The example job, INITSYS.JCL, shows how to create this dataset and populate it with symbols and values. It also shows how to use substrings defining values.
Because this dataset is read at system startup, values that are added later will not be available. You can force a re-read of this dataset at each job submission by setting the environment variable MFJ_RELOAD_IEASYM00=Y.
The example job, SYMBOL6.JCL, demonstrates how to use and replace symbols in in-stream data. It shows the use of the static system symbol, SYSNAME defined in IEASYM00, and the dynamic symbols SYSJOBNM, SYSJOBID and SYS_CORR_CURRJOB, together with other JCL symbols being defined and exported in the job.
The symbols are used in the in-stream data for SYSUT1 in the IEBGENER step and appear with the values replaced in the SYSUT2 dataset for that step.
Note that &SYS_JOB_NOTIFY has not been assigned a value and so appears unchanged in the output. SYSUT1 has the parameter SYMBOLS=(JCLONLY,MYLOG) and the MYLOG dataset will contain messages showing the replacement of the values on each line of the in-stream data.
The second step in the SYMBOL6 job, LISTSYMB, calls the CALLMFJZ module which makes a call to 'IEFSJSYM' to list all the JCL symbols defined at that point of the job. It will then write the values to the SYSOUT dataset for the step.
CALLMFJZ.cbl shows how to interpret the memory structure returned by IEFSJSYM. When the information has been processed, it is important to call IEFSJSYM with the 88-func-freemem function to free the block of memory assigned. Failure to do so will lead to a memory leak which might, eventually, cause the whole system to fail.
It is possible to pass the exported symbols be passed to a job submitted using the Internal Reader. SYMBOL8.JCL demonstrates how symbols defined in one job can be passed and used in the job it submits using INTRDR. SYMBOL8 submits the job SYMBOL8B which uses the symbol values defined and passed in the parent job.
The job correlator (unique job reference id) is generated by the system and can be used as a symbol value (as in SYS VALUE = &SYS_CORR_CURRJOB in SYMBOL6.JCL). It can also be picked up in the MJFUXIT user exit. The user exit can also set SYS_CORR_USERDATA.
The MFJUXIT sample user exit included in this demonstration will set the SYS_CORR_USERDATA for the SYMBOL6 job to 'MY JOB USER DATA' at the event-job-stmt-info.
When the job is run, the user exit will report the user data value at the event-job-started. You can see the set statement echoed to the console log in the messages:
JCLXM0000I J000**** SYMBOL6 Job Correlator = J0001029TST.....JES6DFEE255....: JCLXM0000I J000**** SYMBOL6 User Exit set correlator user data to MY JOB USER DATA
If you view the JESYSMSG for the job after it has run, notice some messages which report that these values were read by the user exit:
JCLXM0000I Job Correlator = J0001029TST.....JES6DFEE255....: JCLXM0000I User Data is: MY JOB USER DATA
However, as mentioned in Limitations below, the JES symbols service IAZSYMBL is not currently implemented so these values can not be asked for or set by a user program other than the user exit.