LongEx Mainframe Quarterly - September 2026
z/OS System symbols are z/OS system level variables that are set by the z/OS systems programmer, or z/OS itself. Common symbols include &SYSNAME (the z/OS system name), &SYSPLEX (the sysplex name), and &YYMMDD (current date). You can find out more in our partner article. This is great, but how do you use these symbols? System Symbols and PARMLIBEvery z/OS systems administrator will use symbols with PARMLIB. For example, the following IEASYSxx parameter can set the z/OS logrec dataset name to include the z/OS system name: LOGREC=SYS1.&SYSNAME..LOGREC An interesting static symbol is &SYSCLONE. This is a 2-character 'shorthand' string for the z/OS system name. By default, it is the last two characters of the SYSNAME symbol, but can be modified in IEASYMxx. Systems administrators can set PARMLIB members with a suffix of &SYSCLONE: so that different PARMLIB members are used with different z/OS systems. For example, we could code the IEASYSxx PARMLIB parameter CLOCK=&SYSCLONE. On system 'MVS1', the PARMLIB CLOCKS1 (S1 is the sysclone) would be used; MVS2 would use CLOCKS2. This is a brilliant feature to allow systems programmers to share one PARMLIB amongst multiple z/OS systems. However, not all PARMLIB members support symbols. Some that don't include CEAPRMxx, DEVSUPxx, GTFPARM and IGGCATxx. You can see which members do and do not support symbols in the z/OS Initialization and Tuning Reference. A useful tool is included by IBM in SYS1.PARMLIB(SPPINST): the z/OS Symbolic Parmlib Parser. This is an ISPF application that can analyse PARMLIB members, substituting in symbols so you can see the 'final' parameter. It's not just z/OS PARMLIB. Symbols can be used in other z/OS related configuration datasets, from TCP/IP PROFILE and VTAM VTAMLST to DFSMShsm ARCCMD. Other IBM products like CICS and Netview provide some system symbol support, as do products from other vendors including Broadcom, BMC and Rocket Software. Check the relevant documentation to see if symbols can or cannot be used. System Symbols In Commands and JCLSymbols are not just for systems administrators. z/OS automatically relaces symbols (strings beginning with '&') with the appropriate value stored in each symbol. It also does this for z/OS console commands. The following shows a user in SDSF displaying their jobname: D A,&JOBNAME
CNZ4106I 05.10.41 DISPLAY ACTIVITY 660
JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS
00034 00052 00002 00048 00046 00002/00100 00069
DSTEPHE IN A=009E PER=NO SMC=000 PGN=N/A DMN=N/A AFF=NONE
CT=220.588S ET=06.11.20
WUID=TSU08023
WKL=TSOPRD SCL=TSO01 P=1
RGP=N/A SRVR=NO QSC=NO
ADDR SPACE ASTE=7EEE6780
Symbols can be used by anyone using JCL. For example, the following IEBGENER set uses the &SYSNAME variable to substitute the z/OS system name into a dataset name: //RUN EXEC PGM=IEBGENER //SYSUT1 DD DISP=SHR,DSN=DSTEPHE.&SYSNAME..OUTA //SYSUT2 DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY Note the two dots at the end of &SYSNAME: same rules as for JCL variables. Remember that system symbols can only be used in JCL if the JES CLASS parameter SYSSYM=ALLOW is set. Note also that system symbols aren't the normal JCL symbols, but can be used like them. If you have data, this can include system symbols. z/OS provides a batch utility to replace system symbols in data: EZACFSM1. The following JCL shows how this works: //RUN EXEC PGM=EZACFSM1
//SYSIN DD *
SYSPLEX: &SYSPLEX
SYSTEM: &SYSNAME
JOB: &JOBNAME
OSLEVEL: &OSLEVEL
DATE: &LWDAY &LDAY-&LMON-&LYR4
TIME: &HHMMSS
//SYSOUT DD SYSOUT=*
Interestingly, this utility is provided in the TCP/IP component of z/OS. Symbols and Datasetsz/OS replaces system symbols with the relevant value for all dynamic allocations. So, we can use system symbols when using features like ISPF. For example, the following shows a user listing all datasets beginning with their jobname (ie. TSO userid): Enter one or both of the parameters below: Dsname Level . . . &JOBNAME..C* Volume serial . . Again, two dots at the end of the symbol name: one to indicate the end of the symbol, the other is a dot in a datasetname. ISPF 3.4 outputs: DSLIST - Data Sets Matching DSTEPHE.C* Row 1 of 4
Command ===> Scroll ===> CSR
Command - Enter "/" to select action Message Volume
-------------------------------------------------------------------------------
DSTEPHE.CNTL VOL001
DSTEPHE.CRIT.CNTL VOL004
DSTEPHE.CRIT.LOAD VOL002
DSTEPHE.CRIT.SOURCE VOL001
***************************** End of Data Set list ****************************
Indirect cataloguing is a technique using a system symbol rather than a volume serial number when cataloguing a dataset. The following IDCAMS commands show how this could be done: DELETE MY.DSET NOSCRATCH CATALOG(CAT.MCAT) DEFINE NVSAM(NAME(MY.DSET) VOL(&SYSR2) DEVT(3390)) CATALOG(CAT.MCAT) z/OS will substitute the value of the symbol &SYSR2 whenever the catalog entry for MY.DSET is requested. On one system, &SYSR2 could point to the volume VOL001, and on another, VOL002. Using such indirect cataloging can allow two systems to share a master catalog. Suppose we have a SYSRES volume SYSRESA. z/OS will set the symbol &SYSR1 to SYSRES. Many sites may have a 'secondary' SYSRES, perhaps SYSRE2. We could specify in IEASYMxx: SYMDEF(&SYSR2='&SYSR1(1:5).2') Now, SYSR2 will be set to SYSREB. If SYSRES changes to IPLRES, SYSR1 will automatically be IPLRE2. System symbols are also supported with CICS online (RDO) File and Library definitions. When defining a datasetname, you can include system symbols. Indirect cataloging has some limitations: only non-SMS managed non-VSAM datasets. Cannot use indirect cataloging for PARMLIB or any dataset specified in the LOADxx IPLPARM member. REXX and UNIXAny REXX exec can access system symbols using the sysvar function. For example, the following REXX outputs the z/OS version: Say 'OS Level=' mvsvar('SYMDEF','SYSOSLVL')
This will output: OS Level= Z1020500 Or in other words, this is z/OS (Z1) version 2.5 (0205). Many automation products allow REXX execs to access z/OS system symbols. For example, CA Ops/MVS provides the OPSYSSYM function, and Netview provides both the SUBSYM function and the SUBSYM pipe stage. The z/OS UNIX shell can also access symbols using the sysvar command: handy for shell scripts. The following shows a z/OS UNIX user displaying the sysplex name: $ sysvar SYSPLEX PRDPLX1 $ Remember, as explained in our partner article, z/OS system variables are different from UNIX environment variables. Symbols For Programming Languagesz/OS provides many other APIs to access z/OS system symbols. For example, z/OSMF provides a RESTful API to view system symbols in JSON format. The RESTful request https://mvs1.interskill.com:10443/zosmf/variables/rest/1.0/systems/local will return JSON formatted data with all defined symbols. Assembler programmers can use the ASASYMBM service to substitute a symbol in a string with a system symbol. The z/OS Assembler Service Guide has example code, as does SYS1.SAMPLIB(IEASYMCK). The following assembler snippet shows how it works: * --- Get Sysplex Name -----------------------
XC SYMBP(SYMBP_LEN),SYMBP Zero ASASYMBM Parmlist
LA R1,#WTOVAL R1 -> Input string
ST R1,SYMBPPATTERN@
LA R1,10 R1 = Input string length
ST R1,SYMBPPATTERNLENGTH
LA R1,OUTVAL R1 -> Output area
ST R1,SYMBPTARGET@
MVC OUTVALL,=AL4(L'OUTVAL) OUTVALL = Output area len
LA R1,OUTVALL R1 -> OUTVALL
ST R1,SYMBPTARGETLENGTH@
LA R1,ASARC R1 -> Return code area
ST R1,SYMBPRETURNCODE@ store in parm list
LINK EP=ASASYMBM,MF=(E,SYMBP) Call ASASYMBM
CLI ASARCL,X'00' If error
BNE SUBERR Process Error
XR R0,R0
(rest of code – Sysplex name is in OUTVAL)
* --- Areas for ASASYMB -----------------
OUTVAL DC CL10' ' Area to get Sysplex Name
OUTVALL DS F Length output area
ASARC DS 0F Area for return code
DS XL3
ASARCL DS X Bottom byte holds retcode
ASASYMBP DSECT=NO Parms for ASASYMBM
#WTOVAL DC CL10'&&SYSPLEX' Input String (two '&')
As this LINKs to an external program, it is not exactly high performance. In fact, the IBM manuals state that “This service is not appropriate for use in a performance-sensitive area.” If you're not an assembler programmer, the bad news is that there's no API for COBOL, C or PL/I programs. The good news is that the same ASASYMBM program can be called from these programs. Java programmers can feel smug, as the IBM Semeru Java SDK provides JZOS classes including the substituteSystemSymbols method. Here's an example: import com.ibm.jzos.ZUtil;
import com.ibm.jzos.RcException;
public class dzsSymb {
public static void main(String[] args) {
String sysplexName="None";
try {
// Get Sysplex Name from &SYSPLEX symbol
sysplexName =
ZUtil.substituteSystemSymbols("&SYSPLEX",true);
System.out.println("Sysplex: " + sysplexName);
} catch (RcException e) {
// Error calling ZUtil function
System.out.println("Unable to get Sysplex name from symbol:" +
e.getMessage());
}
}
}
ConclusionMost sites will use symbols in PARMLIB settings. However, there are many other places that can benefit from a z/OS system wide variable that is only set by z/OS systems administrators, or z/OS itself. |
