Installing and configuring the Zowe cross memory server
{Core}
The Open Mainframe Project’s Zowe z/OS components contain two important pieces.
- The first component is the Zowe started task
ZWESVSTC
. This launches a USS shell within which it runs the API Mediation Layer, Zowe Desktop, and their dependent services. In a previous blog Installing Zowe on z/OS I described how to install and configure a z/OS environment and bring upZWESVSTC
. - The second z/OS component is the cross memory server,(aka
ZIS
), that is launched with theZWESISTC
started task which runs the load moduleZWESIS01
. This is used by the Zowe desktop for tasks that require elevated levels of z/OS privilege such as authenticating user IDs. Whereas all of the I/O between the other Zowe components occur over secure sockets, the Zowe desktop andZWESIS01
communicate via a cross memory connection, hence its eponymous name The Zowe Cross Memory server.
This blog describes how to install, configure, launch and troubleshoot the cross memory server. Wherever possible I’ve tried to use the Zowe Explorer (VS Code extension) and the Zowe CLI to perform the configuration steps (which can operate without any Zowe z/OS components being present as they rely on z/OSMF REST APIs, before you start to puzzle how I can use Zowe to install Zowe and whether the chicken came before the egg).
Installation of Zowe z/OS components
The Zowe z/OS components can be obtained either in a .pax file (known as a convenience build) or as an SMP/E installable. Both methods will result in the creation of two data sets SZWEAUTH
and SZWESAMP
. These contain the members for the cross memory server. For this blog I have installed them into the high level qualifier WINCHJ.ZWE120
ZWESISTC Proclib
The first installation step is to copy the memberZWESISTC
from the installation data setSZWESAMP
to procedure library that exists on the JES PROCLIB concatenation. This will allow it to be executed as a started task. When you execute the JES command /S STCNAME
a lookup occurs to find a PDS member of the same name by searching PROCLIB concatenation in order. The first matching member for STCNAME
found is run.
To see which data sets are on the path issue the SDSF command PROC
or issue the JES2 command $D PROCLIB
. The screen shot shot below on my system shows seven data set names that behave as a hierarchy where 1 is searched first, then 2, and so forth down to the system supplied SYS1.PROCLIB
.
Generally the first few proclib data sets will be the ones for vendor software, which is whatUSER.PROCLIB
has been created for. On your system the list may be different.
Copy the memberWINCHJ.ZWE120.SZWESAMP(ZWESISTC)
created by the Zowe installation to a PDS on the path, for my installation I’m going to use USER.PROCLIB(ZWESISTC)
.
STEPLIB DSNAME=
On line 49 of the ZWESISTC
proclib JCL member the STEPLIB DD DSNAME=
should be updated to point to the location of the ZWESIS01
load library. For my installation this was installed into WINCHJ.ZWE120.SZWEAUTH
and I’m going to leave it there, so the line becomes
//STEPLIB DD DSNAME=WINCHJ.ZWE120.SZWEAUTH,DISP=SHR
One of the reasons I prefer to leave the load module where it was installed (rather than copy it to another PDS member) is because if I had used SMP/E to lay down a PTF release then having the load library remain in the same PDS means thatRESTORE
can be used to undo/rollback the PTF. If I had copied the load library elsewhere this would be an additional step.
Note If you are installing Zowe into a zD&T or zPDT based image there will already be a ZWESISTC
member in ADCD.Z23B.PROCLIB
that was pre-loaded with Zowe 1.16 as part of the Application Developers Controlled Distribution (ADCD) image. You should update this proclib with your newer ZWESISTC
member.
PARMLIB DSNAME=
On line 50 of ZWESISTC
there is a PARMLIB
statement. This should point to the location of the member ZWESIP00
which contains the default configuration values for the cross memory server. This member is included in the SZWESAMP
PDS member created at installation time, in my case WINCHJ.ZWE120.SZWESAMP(ZWESIP00)
.
I’ve updated line 50 for PARMLIB DD DSNAME=
to point to my installation data set. In some configurations you might prefer to copy ZWESIP00
to a data set on the PARMLIB
concatenation which can be determined with the SDSF command PARM
or the MVS command D PARMLIB
.
APF Authorization
Now that we have the proclib let’s try to start the cross memory server. Since ZIS
uses a system LX the address space will not be reusable after termination which can result in leaking ASID resources, which left unchecked will eventually require an IPL. To prevent this from occurring it needs to be started with /S ZWESISTC,REUSASID=YES
. More info on this can be found in the z/OS documentation cross memory services avoid loss asids from reuse.
It’s important to add the REUSASID=YES
when starting ZIS
which is true for similar z/OS software such as ICSF. While leaving it off won’t stop ZIS
from starting the leaked ASIDs will have a detrimental impact to z/OS.
Because we haven’t yet APF authorized the load library containing the ZIS
server program, the job will terminate with the JES message ZWES0117E Not APF-authorized (4)
.
The load module ZWESIS01
makes calls to z/OS services that are restricted functions, for which it needs to be explicitly authorized. APF authorization occurs at the level of the data set (load library) that the program (load module) is within. We’re using WINCHJ.ZWE120.SZWEAUTH(ZWESIS01)
so we need to APF auth the data set WINCHJ.ZWE120.SZWEAUTH
.
To work with APF authorization we’ll need to issue some MVS commands. These are long commands so may not fit into the COMMAND INPUT ===>
area so a good trick is to type /
to bring up the System Command Extension view.
The System Command Extension allows you to enter the command D PROG,APF,DSNAME=
with the data set containing the cross memory server load module.
The result of the command is shown in the SDSF viewer, and the response CSV4521
below shows that the data set isn’t yet APF authorized.
To APF authorize the data set the command SETPROG APF
needs to be run.
SETPROG APF,ADD,DSNAME=WINCHJ.ZWE120.SZWEAUTH,SMS
If the command runs successfully you will see the confirmation message CSV410I
indicating that the PDS is now added to the APF list.
You can check this by re-running the command D PROG,APF,DSNAME=WINCHJ.ZWE120.SZWEAUTH
which will now show a message CSV450I
together with its two members that are now APF authorized.
I uses SDSF to enter the commands for APF, however I could just as easily used the Zowe CLI console group, as shown below. This is super handy if you’re doing automation where you could write some bash scripts to run the commands and do programmatic install and config steps (and it also gives me a chance to show off the Zowe CLI and create an animated gif— yay !).
Key 4 non swappable
The final step required to configure the cross memory server is to make it run as key(4) non swappable. If you haven’t done this step when you launch the started task /S ZWESISTC,REUSASID=YES
you’ll get the error
ZWES0118E Core server started in wrong key 8
To allow the load module to run in key(4) you’ll need to edit a member called SCHEDxx
where xx varies depending on how your z/OS system has been configured. To work out what the value of xx should be involves a number of steps that might seem obtuse, and if anyone reading this knows of a better way please let me know and I’ll buy them a beer/wine/coffee/pastry.
- Retrieve the PARMLIB data sets using the command
D PARMLIB
.
Joes-MBP-3:~ Joe$ zowe console issue command "d parmlib"
IEE251I 13.37.00 PARMLIB DISPLAY 554
PARMLIB DATA SETS SPECIFIED
AT IPL
ENTRY FLAGS VOLUME DATA SET
1 S T50031 USER.PARMLIB
2 S COMN01 COMMON.PARMLIB
3 S G2301E SYS1.PARMLIB
4 S G2301E SYS1.PARMLIB.INSTALL
- Work out the location of the IEASYS data set by retrieving the IPL information with the command
D IPLINFO,SCH
. You can issue this within SDSF by typing/
in the COMMAND INPUT ===> area, however I’m going to use the Zowe CLI for this instead. The result below shows 01 and 00 which are the xx values that z/OS is currently using.
Joes-MBP-3:~ Joe$ zowe console issue command "d iplinfo,sch"
IEE255I SYSTEM PARAMETER 'SCH': (01,00)
Joes-MBP-3:~ Joe$
- Locate the
IEASYxx
members in the PARMLIBs. These will be eitherIEASY00, IEASY01
. There are a number of ways to do this including ISPF, however given that this is a Zowe blog it’s a good time to showcase the recently added member filter of the Zowe Explorer that allows a search criteria to include member filter critera, e.gUSER.PARMLIB(IEASY**)
. This shows us thatIEASY01
is inUSER.PARMLIB
!
- Now that we know
IEASYS01
is the member used at IPL time, we need to look inside it for theSCH=
statement.
This points to 01
and 00
. In the parmlib data sets again look for the member SCHED01
. You can create another filter in the Zowe Explorer to do this and rattle through the PARMLIB concatenation, and on my system I found USER.PARMLIB(SCHED01)
.
In the member add the two lines:
PPT PGMNAME(ZWESIS01)
KEY(4)
NOSWAP
PPT PGMNAME(ZWESAUX)
KEY(4)
NOSWAP
as shown below.
Having done this you’ll need to do a refresh which is done issuing the system command /SET SCH=xx
Are we there yet ?
If all the steps have worked successfully, then when you issue the command /S ZWESISTC
you should see the address space go active and the log message ZWES109I Core server ready
Is Zowe connected ?
The main Zowe started task is ZWESVSTC
. This should be started after the cross memory server is running, and on successful attach the message ZWES1014I
is issued.
ZWES1014I ZIS status - 'Ok' (name='ZWESIS_STD ', cmsRC='0', description='Ok', clientVersion='2')
If there is a failure to attach the cmsRC
will be non zero. The Zowe documentation chapter ZSS server unable to communicate with X-MEM contains details of how to troubleshoot the most common problems that can occur. The one that I see most frequently at customer sites is
ZWES1014I ZIS status - Failure (name='ZWESIS_STD ', cmsRC=33, description='Permission denied'
which occurs if the user ZWESVUSR
running the started task ZWESVSTC
does not have read authority to the FACILITY class ZWES.IS
. Because the cross memory server runs APF authorized code this class is used to guard access to its services.
Can I rename ZIS and have more than one active ?
The default name of of the ZIS
server program isZWESIS01
and specified in line 47 of the ZWESISTC
PROCLIB
//ZWESIS01 EXEC PGM=ZWESIS01,REGION=&RGN,
If you change the value of the PGM=
to be something different (perhaps ZWESIS_02
in order to have >1 ZIS
server active on the same LPAR), then be sure to update the instance.env
used to start the ZWESVSTC
started tasks to match with the ZOWE_ZSS_XMEM_SERVER_NAME=
, see Cross Memory Server.
ZOWE_ZSS_XMEM_SERVER_NAME=ZWESIS_02
My huge thanks to Irek Fakhrutdinov from Rocket software, and Nayer Najafi from IBM (and fellow Zoweians) for their input and help writing and editing this blogpost.
Finding out more
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.