JCL Exported Symbols

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.

Important: Release 5.0 PU5 introduces a change in the format of the job parsing files, MFELX*, created by the JES engine. As a result of this change, it is not possible to restart jobs run before installing 5.0 PU5.

The following examples are based on the JCL - Symbols sample installed with this product. See JCL - Symbols Mainframe Samples browser.

Compile user programs

Two user programs are included with this demonstration:
  • CALLMFJZ.cbl shows how to call the JCL Symbol Service IEFSJSYM
  • MFJUXIT.cbl is a sample JCL user exit that sets and reads the current job correlator, SYS_CORR_CURRJOB, and the associated user data, SYS_CORR_USRDATA.
These two programs must be compiled as shared objects and placed in a location where the JES engine will be able to load it (on the $CAS_BATCH_PATH). The Enterprise Server instance must include the MFJUXIT environment variable, where:
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

Defining system symbols

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.

Using symbols in in-stream data

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.

Listing exported symbols (IEFSJSYM)

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.

Using the Internal Reader to pass symbols

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.

Getting the job correlator and user data

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.

Limitations

  • SYS_JOB_NOTIFY can not be set prior to a job being submitted unless it is included in the static system symbols (IEASYM00).
  • There is no difference between SYMBOLS=EXECSYS and SYMBOLS=CNVTSYS.
  • SYMBOLS=JCLONLY will resolve JCL exported symbols and $SYS_* system symbols.
  • SYMBOLS=EXECSYS or SYMBOLS=CNVTSYS will replace JCL exported symbols with values resolved at job submission and static system symbols defined in the execution process.
  • All exported JCL symbol values are resolved when the job is submitted. Static system symbols that have not been exported as JCL symbols are resolved when the job is run. This is equivalent to SYMBOLS=EXECSYS.
  • The JES symbol service (IAZSYMBL) is not implemented. Calls to IAZSYMBL will return 12.
  • The IEFSJSYM function GETBYNAME is not implemented and will return 8 (unsupported function) and reason code x'00000818'.