Installing and configuring the Zowe cross memory server

Published in

Zowe

9 min readApr 27, 2021

{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 up ZWESVSTC.
The second z/OS component is the cross memory server,(aka ZIS), that is launched with the ZWESISTC started task which runs the load module ZWESIS01. 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 and ZWESIS01 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 ZWESIP00which 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 either IEASY00, 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.g USER.PARMLIB(IEASY**) . This shows us that IEASY01 is in USER.PARMLIB !

Now that we know IEASYS01 is the member used at IPL time, we need to look inside it for the SCH= 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.