There are as many different possible z/OS configurations as there are z/OS customers. As a result, it is impossible to provide a document that comprehensively describes the considerations for migrating from one ADCD release to another for every customer.

However, there are some “good housekeeping” practices that you can adhere to that make it easier whenever you are ready to move to a new ADCD release or a new release of the 2016 Sysplex Extensions in the future. This chapter describes those practices.

Although an ADCD system is not for use in production environments, there is still value in configuring it in a manner that minimizes the time and effort to migrate it to a newer release in the future.

In an ideal world, you download the volumes that are associated with a new ADCD release, initial program load (IPL) the new sysres, and everything works with no extra customization or effort. The other extreme is that you must start from scratch when you install a new release and perform the same customization process when you move to a new release.

Although it is unlikely that you can achieve the ideal scenario, there are things that you can do to bring you closer to that extreme than the other. This chapter provides advice to help you achieve this goal.

When users move to a new ADCD release, they often want to carry over as much of their existing customization as possible, but without having to manually reapply all of the changes to the new ADCD-supplied data sets. A good way to come close to this outcome is to do your utmost to avoid changing ADCD-provided volumes. It helps with this process if you can think of data sets as falling into one of the following categories:

Roughly corresponding to these categories, you ideally have the following types of DASD volumes:

In practice, some of the ADCD volumes are a mix of system volumes and system work volumes. ADCD volumes are structured in this way to reduce the number of volumes that are required for the complete ADCD environment. For example, the F1C521 volume contains CICS SMP-maintained libraries and CICS runtime data sets. Nevertheless, the concept of trying to segregate volumes that are replaced by a future ADCD release from volumes that you carry forward from one release to the next is still a valuable one.

The sysres is a good example of a system volume. Virtually all of the data sets on that volume should not be changed by you. Taking the May 2015 ADCD release sysres as an example, there are the following exceptions to the recommendation about treating that volume as if it was read-only:

Although SYS1.PARMLIB and SYS1.PROCLIB can be changed manually, you should try to place any parmlib or proclib changes in the USER.PARMLIB and USER.PROCLIB data sets. Those data sets are placed ahead of the SYS1 equivalents in their respective concatenations. For example, if there is a PROGBO in SYS1.PARMLIB and in USER.PARMLIB, the member from USER.PARMLIB is used.

If you can adhere to this guidance, the only data set on your sysres that is changed is the backup RACF database data set. When you migrate to a new release, you can start with a new ADCD-provided RACF database, or you can use a RACF utility to copy the RACF database from your old release over to the new release.

The product volumes (F1PRD1, F1PRD2, and F1PRD3) are more examples of system volumes in that the data sets they contain should be updated only by SMP/E.

The subsystem volumes (those volumes that are used by DB2, CICS, and so on) as provided by ADCD are something of a hybrid. They contain SMP-maintained data sets and data sets that are used by your subsystems.

The system work volumes are provided by ADCD, but they contain data that is specific to your environment; for example, F1SYS1, F1PAGA/B/C, F1USS1/2, and F1CFG1. Unfortunately, there is no simple one-size-fits-all migration process for these volumes.

Some of these volumes contain data that you might be willing to discard when you move to a new release; for example, your JES2 spool, SMF data sets, page data sets, Logrec, and DAE data sets.

Other volumes contain data that you likely want to merge with the version of that data set that is provided by the new release; for example, your master catalog¹, RACF database, and SMS SCDS.

You should review the contents of these volumes and identify how you can handle each data set when the time comes to migrate to a new ADCD release.

The 2016 Sysplex Extensions provides DB2 and CICS subsystems that are tailored to run in a Parallel Sysplex environment. They use the ADCD-provided CICS and DB2 software libraries. All of the other data sets that you need to run the subsystems that are provided by the 2016 Sysplex Extensions are contained on a pair of SMS-managed volumes (one pair for CICS and one pair for DB2). Packaging the subsystems in this way makes it easier for you to add or remove those subsystems. It minimizes the number of steps that are required to add those subsystems and makes it easier for you to migrate these subsystems from one ADCD release to another. If you plan to add your own subsystems, you can use this model to build the subsystems in a way that eases the migration effort when you move to a new ADCD release.

We expect future releases of the 2016 Sysplex Extensions to follow this model (the volumes that contain the subsystem work data sets will be delivered with each new release). This configuration gives you the option of replacing your volumes with the new volumes (and cold starting your subsystems), or carrying your volumes forward. However, in the latter case, you must follow the migration process that is provided by the new release of CICS or DB2.

Perhaps the most important thing is to do your utmost to avoid adding new data sets to the ADCD-provided volumes. If you have data sets that you know you want to carry forward from one ADCD release to another (such as those containing your application programs, your own data, load libraries, and JCL), you should place those data sets on volumes (we call them user volumes) that are not replaced by the new ADCD volumes. Also, ensure that they are cataloged in user catalogs that are also on user volumes.

In as far as reasonable, any new data sets that you create should be placed on a user volume. These user volumes should not contain any system data sets. The objective is to maintain a clear delineation between ADCD-delivered volumes and data sets, and your own volumes and data sets. The fewer changes that you must make to anything on an ADCD-provided volume, the easier it is to migrate to a new ADCD release.

You should expect that every new ADCD release contains new data sets in support of new software products or new releases of existing products. These data sets often are cataloged in the master catalog that is provided with the new ADCD.

When you IPL the new ADCD release with your master catalog, you cannot access those data sets unless you specify the volume serial. Therefore, part of the migration to a new ADCD release includes creating a master catalog that contains all the data sets on the new ADCD system and all your own data sets that you were using on the previous release.

When you are deciding how to create this superset master catalog, you have the following choices:

In either case, the task is greatly simplified if you maintained a “clean” master catalog; that is, a catalog that has a minimum number of changes to the master catalog that was delivered with your current ADCD release. One of the best ways of achieving that is to catalog all your user data sets in user catalogs and place those catalogs on your user volumes².

There are a few restrictions that are related to the use of user catalogs. If a data set that is specified in any of the following parmlib members is cataloged in a user catalog, the volser that the data set is on must be specified in the corresponding parmlib member:

Although this list is long, most of the affected data sets are system data sets. Therefore, they normally are cataloged in the master catalog.

A good way to ensure that you do not forget to create an ALIAS that points at a user catalog when you create a high-level qualifier is to severely restrict the number of users that have RACF update access to the master catalog. This restriction helps highlight situations where a data set might be cataloged in the master catalog because no corresponding ALIAS was defined.

Another useful tip is to use a consistent naming convention for your user catalogs; for example, UCAT.PROJECTA. This naming convention makes it easy to differentiate between aliases that are delivered with ADCD (the ADCD-provided user catalogs all have a high-level qualifier of USERCAT) and aliases that were created by you (and therefore point at a user catalog that is called UCAT.xxxxx).

Most (but not all) parmlib members support the ability to concatenate multiple members. For example, assume that the IGGCAT00 member contains a parameter that you want to override.

One way to achieve this override is to update the IGGCAT00 member in the ADCD.Z21F.PARMLIB member. Although this method works, the next ADCD release ships a new ADCD.anna.PARMLIB data set, which means that the change you made to the IGGCAT00 member in ADCD.Z21F.PARMLIB is lost.

Another option is to copy the entire IGGCAT00 member to your USER.PARMLIB member. Because USER.PARMLIB is ahead of ADCD.Z21F.PARMLIB in the parmlib concatenation, the USER.PARMLIB version is used and the copy in ADCD.Z21F.PARMLIB is not used.

This method is effective from the perspective that you can easily copy your USER.PARMLIB data set contents to the corresponding data set in the new ADCD release. However, it has the drawback that if IBM updates the 00 member, your system does not pick up that change (the system reads only the first member if there are multiple identically-named members).

For components that support multiple concatenated members, we believe that the ideal solution is to create a member with a meaningful suffix (something other than 00), and to populate that member with only the parameters that you are overriding. You then specify something such as, CATALOG=(00,PS) in your IEASYSxx member. This specification results in the 00 and the PS members being read during the IPL. If IBM makes changes to the 00 member, those changes are picked up during the IPL.

Unfortunately, not every component supports the use of concatenated parmlib members. Nevertheless, this methodology is a valuable for those components that do support this use.

For more information about effectively managing your parmlib members, see the section titled, “Description and use of the parmlib concatenation” in z/OS MVS Initialization and Tuning Reference, SA23-1380.

Our last tip is that you try to keep your system structure as simple as possible. Simplicity makes the administration of your system easier and less prone to human error. It also significantly reduces the problem determination effort if something is not working as planned.

A good example of this guideline is to minimize the number of parmlib members through the intelligent use of system symbols. Example 2-1 shows an excerpt from the IEASYSB1 parmlib member. In the highlighted text, you can see that the page data set names contain the system name as the second qualifier.

Example 2-2 shows an excerpt from the IEASYSB2 parmlib member. In this example, you can see that the two members are identical, except for the page data set names.

An alternative is to maintain a single IEASYSxx member, which is similar to the one that is shown in Example 2-3. In this case, the system name in the page data set name is replaced with the system symbol &SYSNAME. When that member is read by system S0W1, the &SYSNAME in the page data sets is replaced with S0W1. When it is read by S0W2, it is replaced by S0W2.

System symbols are a powerful tool for simplifying the task of managing your systems. Symbols are defined in the IEASYMxx member. In that member, you can specify values for symbols that are used on every system in the sysplex. You also can filter based on the LPAR name or virtual machine name (or zPDT host name) so that the same symbol resolves to different values, depending by which system they are referenced.

In addition to parmlib members, system symbols can be used in procedures, TSO logon procs, and system commands. Starting with z/OS 2.1, system symbols also (optionally) can be used in normal job JCL (including in SYSIN statements) and even in jobs that are submitted via the internal reader. A future update to this document will contain some real-world examples of how this capability might be used.

Also, starting with z/OS 2.1 is the ability to dynamically change system symbols by using a system command (SETLOAD IEASYM,xx). In z/OS 2.2, the maximum length of a system symbol was increased to 44 characters so that a system symbol can contain a value, such as a data set name or an IP address.

If you refer to the IEASYMPS member in the SYSPLEX.PARMLIB data set after you download the 2016 Sysplex Extensions volumes, you see some examples of how we used system symbols to simplify the members that are used for the sysplex.

This first release of the 2016 Sysplex Extensions is a significant change from the previously available ADCD sysplex support, so we do not want to make too many changes at one time.

However, future releases will expand on the examples and advice that is provided in this chapter. If you have any suggestions that you believe might benefit other zPDT users, send an email to: [email protected].