From SOE to WAPL

If your first exposure to either Scheduling Operational Environment (SOE) or Workload Automation
Programming Language for z/OS (WAPL) was with IBM Workload Scheduler for z/OS 9.3, then this
document will probably be of little interest to you.

If you’re still reading, then I will start with a little history to put things in context. SOE was first
developed as a strategic tool in 2007, with limited availability, only made available to customers with
specific needs and used in some projects to migrate customers to Workload Scheduler from other
ISV products. In 2009 SOE 2.4 was made publicly available as an unsupported tool, provided ASIS, to
aid with automating various Workload Automation processes. Under the covers it exploited the
published Program Interface (PIF), but was more consumable.

Though unsupported, the tool was updated with new features, support for new releases and fixes
for any issues discovered. A new version was released roughly every 12 months, with fix packs in
between as needed. Because of the unsupported nature of the tool, fixes were only ever applied to
the latest level of code, but in some cases customers could be advised how to make those fixes
themselves as early versions of the code were provided uncompiled, and some fixes were only in the
data map which was always delivered in the clear. From version 3.3 the tool was delivered as
compiled REXX, to allow customers with the REXX compiler to run it at a higher speed, and in
preparation for what was to come.

In 2014 it was announced that SOE would be officially delivered as part of the product from version
9.3, making SOE 3.3 Fix Pack A, delivered in August 2014, the final issue of SOE. A few months later
it was officially taken into the full product source and became known as WAPL. Since some of the
later changes included the IF/THEN and loop capability, the new name reflected both the
programming capability and helped distinguish the unsupported tool from the supported one. All
subsequent fixes to SOE have been applied to WAPL.

As the final version of SOE gets older, now almost 3 years old, it is extremely important to move to a
supported version of WAPL. When SOE 3.3 FP A was released the highest version of Workload
Scheduler available at that time was TWSz 9.2, and the highest operating system available was z/OS
2.1. It was not designed with changes in any higher releases in mind. This is vitally important for
anyone moving to z/OS 2.2, as this includes changes the way virtual addresses were resolved, which
was not compatible with the way SOE processed virtual addressing at start-up, making SOE unable to
work correctly on initiators above the line under z/OS 2.2.

Fortunately, WAPL has been available for 2 years now and is fully supported. WAPL becomes
compatible once this PTF is applied http://www-
01.ibm.com/support/docview.wss?crawler=1&uid=swg1PI69440. So ensure you have upgraded to
WAPL and applied this fix before moving to z/OS 2.2.

If you are an existing SOE user there are effectively two scenarios to upgrade to WAPL –

1. Stay at your existing level of Workload Scheduler and upgrade your SOE environment to the
latest version of WAPL.
2. Upgrade to IWS for z/OS 9.3, making allowances for element naming differences
What had to change for SOE to be supported (The Blue Wash)
To be included in the product officially, the SOE architecture had to be adapted to fit in with libraries
and naming conventions of IBM Workload Scheduler for z/OS. Largely it already did, with the main
touch points of the JCL procedure (EQQYXJCL) and the main entry point (EQQYXTOP) already having
EQQ prefixed names.

The libraries containing SOE elements were mapped either to mostly pre-existing product libraries,
or customisation libraries

SOE library Purpose WAPL equivalent

SETUP.ISPSLIB SOE installer skeleton library No equivalent as WAPL is installed by SMPE
SETUP.ISPPLIB SOE installer panel library No equivalent as WAPL is installed by SMPE
SETUP SOE installer package library No equivalent as WAPL is installed by SMPE
PARM SOE data and configuration Product SEQQWAPL library (new)
REXX SOE compiled REXX code Product SEQQMISC library
SOESAMP SOE samples Product SEQQSAMP library
SEAGALT REXX alternate library Already included in z/OS
SOEEXEC SOE compiled REXX code Product SEQQMISC library
IBMTOOLS Special tools for migrations Only delivered with IBM services projects
JCL SOE JCL procedures Generated into EQQJOBS output library
USRPARM Allows users to store User would create their own library for this if
customised parameters needed.
USRREXX Allows users to store their own User would create their own library for this if
SOE REXX modules needed.

Though the main programs and JCL in SOE already had an EQQ prefix, some members in the PARM
and SOEEXEC libraries did not originally have EQQ prefixed members. A WAPL sample job,
EQQWPLCO has been provided to create SOE versions of the PARM members.

Since the most popular SOEEXECs have been largely replaced with native WAPL commands, a similar
action was not taken with SOEEXEC members, to encourage evaluation of any SOEEXEC use and
either migrate to use the native WAPL command, or the new name.

SOEEXEC WAPLEXEC Alternate command

ADDAPPL EQQWXADD Replaced by WAPL ADD command
BLEXT EQQWXBLX
CPSRUPD EQQWXCSR
CSVBUILD EQQWXCSV
DEPCOUNT EQQWXDPC
DEPEXT EQQWXDPX
HTMLCAL EQQWXHTM
IAXREF EQQWXIAX
JCLCATDD EQQWXCAT
JOBFIND EQQWXJBF Replaced by WAPL JOBFIND command
JOBUPD EQQWXJBU
LTPDEPS1 EQQWXLT1
LTPDEPS2 EQQWXLT2
LTPDEPS3 EQQWXLT3
LTPTRLEX EQQWXTRL
 SOEEXEC WAPLEXEC Alternate command
MOPDOP EQQWXMOD Replaced by WAPL Current Plan Operation commands (Chapter 6)
NOESCAPE EQQWXNOE
PERIODWK EQQWXPER
SUBLINK EQQWXLNK Replaced by WAPL ADD command with LINK(YES)
TWSDCON EQQWXDCN

No SOEEXECs were amended as part of the porting to WAPL (other than their name), so it is possible
to include the SOE 3.3 SOEEXEC library as the last library in the SYSPROC concatenation to run all
SOEEXECs exactly as they were under SOE, and then gradually migrate to the new names or
commands.

Other than those unavoidable naming differences WAPL is largely just the latest version of SOE.

Upgrading from SOE to WAPL

First, don’t get hung up on the name change, as mentioned earlier the new name reflects the
addition of programming features to the old SOE engine, and also differentiates the unsupported
code (all versions of SOE) from the supported code (all versions of WAPL). WAPL is essentially SOE
3.4 and uses the same main entry point, EQQYXTOP, and the same JCL procedure, EQQYXJCL and the
bulk of the same underlying engine. The upgrade process simply involves ensuring your EQQYXJCL is
pointing at 9.3 WAPL elements and customised to accommodate old SOE names.

If you are not upgrading your current subsystems to IWSz 9.3, then to obtain the WAPL code you
need to first install an instance of IWSz 9.3 under SMPE on a Sandbox system. You only need to get
as far the loading of the SEQQ libraries to get WAPL installed. Strictly speaking you do not need to
get as far as a working controller, but it is recommended to do that in the long term, so that in the
event of problems you can attempt to reproduce any problems in the 9.3 system, to determine
whether it is a core WAPL issue, or a cross version issue. This will aid problem resolution.

The core code needed to support WAPL is as follows –

 From EQQJOBS output library member EQQYXJCL – core JCL procedure

 From SEQQMISC all members beginning EQQWX and EQQYX
 From SEQQWAPL all member (this is a new library for 9.3)
 From SEQQLMD0 member EQQSWARQ – This is a new member that does not exist in earlier
releases of IWSz and is crucial for WAPL support of z/OS 2.2.

If you are not upgrading your subsystems to IWSz 9.3, then this is the code that needs porting to all
your subsystems. How you do this is entirely up to you, but if your current naming convention
includes version in the dataset name, then you might want to consider porting these datasets using
the names they would have when you eventually roll out version 9.3. For purposes of illustration
that is the convention I will be using in this document. Any maintenance applied to your IWSz 9.3
datasets should be rolled out to your other systems using whatever method works for you.

Also if not upgrading your subsystems, base WAPL requires a new load module, EQQSWARQ which is
not contained within any previous releases of IWSz. This module must reside within an authorised
library, I would recommend using your eventual intended name for IWSz 9.3 SEQQLMD0 and adding
that into your APF lists, but equally the member could be ported into an existing authorised library if
that suits your needs better. The library containing EQQSWARQ should be concatenated after the
version of IWSz you are communicating with.
In the IWSz Planning and Installation guide it recommends you run sample EQQWPLCO. This job
copies the EQQ prefixed members in SEQQWAPL to member names with their original SOE names.
Whether you run this in place on the SMPE controlled library, or copy the contents and run in a non-
SMPE controlled library depends upon your policy surrounding SMPE controlled libraries. Whichever
method you use ensure the end result contains both old and new member names, and this is the
library you use in the EQQYXJCL procedure. This allows you to gradually move over from old to new
names. Any updates to the SEQQWAPL library should be followed by running EQQWPLCO. It is
recommended that when you have completed the migration to EQQ names that you remove the
non-EQQ members and no longer run the EQQWPLCO job.

Customising EQQYXJCL to be more SOE friendly

The EQQYXJCL procedure is produced as output from the EQQJOBS process, and if you have never
used SOE, so WAPL is your first exposure to the tool, then the customisation performed by EQQJOBS
is enough to use WAPL successfully.

However, if you have existing SOE workload out there, want to set your own site defaults, or will be
wanting to run WAPL across versions of IWSz, then there are a few more customisations you will
need to apply.

Setting defaults
At the top of the procedure you will see the following defaults, and you might notice they use the
old SOE names. This is because the change to EQQ names only came towards the end of the
integration into the product. As all testing had been completed using these old defaults, it was
released this way so as not to invalidate the testing.
//EQQYXJCL PROC @=,
// ARGS='',
// CMD=EQQYXTOP,
// FILESPEC=FILENONE,
// LANG=EN,
// MOD='',
// OPTFILE='TWS.V930.SEQQWAPL',
// OPTS=OPTDEFLT,
// REF=REFERNCE,
// REG=4M,
// SUBSYS=WSMC,
// VER=V930,
// #=

EQQYXJCL using old defaults

At some point a future release of WAPL will correct these names to the modern EQQ prefixes. To
pre-empt this, and avoid copies of the old name escaping into the wild needing to be tidied up, it is
recommended you pre-empt that as follows.
 //EQQYXJCL PROC @=,
// ARGS='',
// CMD=EQQYXTOP,
// FILESPEC=EQQFLNON,
// LANG=EN,
// MOD='',
// OPTFILE='TWS.V930.SEQQWAPL',
// OPTS=EQQOPDEF,
// REF=EQQREF,
// REG=4M,
// SUBSYS=WSMC,
// VER=V930,
// #=

EQQYXJCL using new defaults

If you want to set your own WAPL default options, you can create your own OPTIONS statement in a
member in a non-product library, and point to it by amending the OPTFILE and OPTS symbolic
parameters as appropriate. This member will be executed in WAPL before anything else, and is not
restricted to just OPTIONS statements, any statement is allowed e.g. VARSET MYVAR = “HELLO”.

Consider carefully what you put in this member as it will be executed by every WAPL job, so will
increase processing for every job, and consider the risk of changing it (in particular getting it wrong).
The EQQOPTS DD statement was an early SOE mechanism for allowing standard code to be executed
across multiple jobs. A later release of SOE introduced the INCLUDE statement which allows pre-
built members to be executed only when needed by the job, so is a much more efficient and safe
approach.

The EQQLANG DD statement can also be pre-empted to point at the new name, changing –
//EQQLANG DD DISP=SHR,DSN=TWS.V930.SEQQWAPL(LANG&LANG.)

to
//EQQLANG DD DISP=SHR,DSN=TWS.V930.SEQQWAPL(EQQLNG&LANG.)

Communicating with other versions

If you are using WAPL for more than just version 9.3, then the STEPLIB potentially needs to point to 2
separate libraries.

1. The SEQQLMD0 that belongs to the version that the controller is using
2. The authorised library that you put EQQSWARQ in.

The EQQMLIB library should also point to the version belonging to the controller
//STEPLIB DD DISP=SHR,DSN=TWS.&VER..SEQQLMD0
// DD DISP=SHR,DSN=TWS.V930.SEQQLMD0

//EQQMLIB DD DISP=SHR,DSN=TWS.&VER..SEQQMSG0

Allowing WAPL to work with multiple versions

Note that using this method precludes using VER=* to get WAPL to “detect” the version, as it will
cause a JCL error in the STEPLIB and EQQMLIB. The VER=* option, though technically still available,
was always a bit of a pointless feature, as you always have had to pre-empt which version you were
communicating with by presenting the correct STEPLIB and EQQMLIB in the JCL. So you always had
to know the version before submitting a job.

Setting the VER= keyword to the actual version, e.g. VER=V910, will both tell WAPL what version is
running and set the correct STEPLIB and EQQMLIB. WAPL can accept many different formats of
version to suit your dataset naming convention, e.g. VER=V910, VER=910, VER=V9R1M0 etc.

From version 9.3 onwards the EQQSWARQ load module will be in every SEQQLMD0, so once you
have no controller lower than 9.3, you can remove the second DD statement from the STEPLIB.

All other DD statements referencing IWSz libraries should point explicitly to the version of WAPL that
you are running, not the controller. Only the load library and message library need to be pointed to
the version of the controller.

Bringing SOE into the picture

If you have been using SOE, then you may already have your own SOEEXECs or have exploited the
deprecated Filter Exit. Equally if you have used the supplied SOEEXECs and don’t want to change all
the calling JCL to the new names upfront, then you can integrate some SOE and WAPL libraries
together in the SYSPROC.
//SYSPROC DD DISP=SHR,DSN=TWS.SOE330.USRREXX
// DD DISP=SHR,DSN=TWS.V930.SEQQMISC
// DD DISP=SHR,DSN=TWS.SOE330.SOEEXEC

Integrating legacy WAPL libraries

Ensure that no members in the USRREXX library begin with EQQ, unless you are exploiting the filter
exit, in which case your EQQYXU00 member is OK in this library. If you are not using the filter exit,
then there is no reason for any USRREXX members to override members in SEQQMISC, so you may
want to consider placing the SEQQMISC library first in the concatenation, to avoid accidental
overrides which may cause issues and complicate support of WAPL.

You may want to consider testing your “upgraded SOE” with only a few jobs to start with. If that is
the case do not place your new version of EQQYXJCL in the place you currently access the SOE
version from, instead placing it in a library that you can explicitly refer to it from a select number of
jobs using the JCLLIB statement.

//ZUSRDH1W JOB NOTIFY=&SYSUID,MSGCLASS=X,CLASS=B

//*
// JCLLIB ORDER='ZUSRDH1.TEST.JCL'
//RUNWAPL EXEC EQQYXJCL
//OUTDATA DD SYSOUT=*
//SYSIN DD *
LIST ADCOM ADID(DAILYPLANNING)

Running “upgraded SOE” for only selected jobs

The REXX alternate library
WAPL runs as compiled REXX, which can be interpreted by the REXX alternate library, which is now
available as part of z/OS. Alternatively if you have the REXX compiler itself, it will run much faster
using the compiler library.

Your systems programmer should know which mechanism you have in place, and hopefully it is link
listed. If not you will need to add either the compiler or alternate library to the bottom of the
STEPLIB.

If you don’t know where your REXX library is, SOE came with a copy of the alternate library,
SEAGALT, which you can use to get things working.