IBM Support

ZWSTECHNOTE : MIGRATION TO NEW RELEASE - BEST PRACTICES ( zWS z Workload Scheduler )

Question & Answer


Question

A basic guide to upgrading z Workload Scheduler to a new RELEASE, with emphasis on best practices for a successful migration and elimination of excessive detail provided in product documentation. Also covers upgrade to a newer z/OS release.   

Any changes made April 4, 2023 are marked with a vertical bar  ("|") on the left margin,

Cause

In an attempt to cover every possible situation, the creators of the zWS Planning and Installation Guide have made the migration instructions overly complex and confusing. This document attempts to provide clear and concise directions for a successful migration.

For special situations such as a high availability environment where it is likely that a significant number of ETT or DATASET TRIGGERS may occur while the migration is in progress, users are advised to consult the applicable sections of the manual (Topic - "Migrating the production environment" ), and to check with product support for additional guidance.

For situations where the migration is being done in a staggered or "one LPAR at a time" approach see also technote

https://www.ibm.com/support/pages/node/6342825
(Migration to a new release of zWS in a phased approach (example - one LPAR at a time))

| If migration is being done from a very old release (prior to 9.3) see also technote

https://www.ibm.com/support/pages/node/6342823
(Migration from an unsupported release of TWSZ to a supported release using a two-step migration job (EQQICNVS member in SEQQSAMP))

 

Answer

| For migration to zWS 9.5  or 10.1 from 9.3 or 9.2 releases please see:

 https://www.ibm.com/support/pages/node/1127883 

(What PTFs must be applied to TWSz 9.2 or IWSZ 9.3 or zWS 9.5 before migration to IZWS (z Workload Scheduler) 9.5?)

| In general before attempting a migration from an older release always check the EQQICNVS member of SEQQSAMP for the new release | | as it will list all necessary maintenance.  Also it is always best to apply all the HIPER PTFs for the new release.

| To see which release to release migrations are possible please see:

| https://www.ibm.com/support/pages/node/6113614

| (Migration to a supported release of z Workload Scheduler  ( IBM Workload Scheduler for z/OS ))
| For z/OS release upgrades please see:
| https://www.ibm.com/support/pages/node/6113626

| (Upgrading the z/OS operating system level while staying on the same release of z Workload Scheduler ( zWS IWSz TWSZ ))  

|**** Please note:  If migrating to IWSz release 9.3 and PTF UI55005 has been applied    please pay CAREFUL attention to the FLASH about UI55005 implementation:

        https://www.ibm.com/support/pages/node/729727

        If you are not completely sure about this please open a case  with zWS support ( COMPID 5697WSZ01) before doing the

       migration ****

The very first thing to remember when approaching a migration of zWS from one release to another is that the new release must be INSTALLED, CONFIGURED AND TESTED using dummy or sample data before the migration can be attempted.

This includes:

  • | Updating the JES and SMF exits. These exits are always DOWNWARD compatible. That is, the exits from the NEWEST release can always be used with older releases of TWSz. (EXCEPT for APAR PI24927 -- see https://www.ibm.com/support/pages/node/531133 )
  • But the OLD exits may not function correctly with newer releases.
  • Verifying that release-suffixed load modules are in a linklisted library (EQQINITx, EQQSSCMx, EQQMINOx).
  • For detailed instructions on INSTALLING, testing, and verifying the new release, consult the zWS Planning and Installation manual for the product release to which you are moving. *ONLY* after the new release has been installed and verified, can you proceed with the migration following this document.

| See also technote 509839 "Preparation for TWSz migration" at:
https://www.ibm.com/support/pages/node/509839

For special considerations when migrating from an older release of TWSz see technote
 "TWSz migration issues when skipping release levels" at:
https://www.ibm.com/support/pages/node/509859


Now the migration guidelines:

1. This document concentrates on the TWSz CONTROLLER and E2E SERVER started tasks, and any required changes to the E2E USS file system.

  • TWSz DIALOG/PIF/GUI servers have no "migration" requirements. However, as part of INSTALLING the new release, the started task procedures for the servers (as well as all other TWSz JCL and procedures) should be regenerated using the EQQJOBS installation aid supplied with the TWSz release to which you are upgrading. New DD statements are sometimes added in a new release, and the DCB characteristics of dynamically allocated work files sometimes change.
    • NOTE: TWSz CONTROLLER and all SERVER started tasks must always be at the same release.

    DATASTORES have no "migration" requirements. You can simply restart the started task using all the same datasets, but pointing at the SEQQLMD0 and SEQQMSG0 for the new release. Since there is no database migration, the DATASTORE and CONTROLLER can be at different releases.
    • NOTE: An exception occurs when moving to TWSz V8R6 from earlier releases. 8.6 introduces a new AUTOMATIC RETRIEVAL of JOBLOG and OPERINFO data for operations ending in error. For this function to work, both CONTROLLER and DATASTORE must be at TWSz V8R6M0 or higher.

    TRACKERS require no migration of datasets, and are interoperable with CONTROLLERS of different releases. Therefore, the TRACKERs may be migrated before the CONTROLLER, after the CONTROLLER, or at the same time. If a TRACKER is migrated, its EQQEVDS dataset must be reallocated so that it can be formatted. To move a TRACKER to a new release of TWSz, there is no database migration, but all datasets including ALL MEMBERS of the EQQJCLIB must be carried forward, and the associated subsystem must be upgraded either by modifying the IEFSSNxx member of SYS1.PARMLIB and IPLing, or by using the BUILDSSX/SSCMNAME keywords of the OPCOPTS initialization statement. BUILDSSX/SSCMNAME can also be used to dynamically update the CONTROLLER subsystem without an IPL. Please refer to this document for details on correct usage of these OPCOPTS parameters:

2. Select a time for the migration when TWSz work is at a minimum. The CONTROLLER will be stopped for some time (one-to-two hours usually), and unless the HIGH AVAILABILITY technique is used to merge old and new TWSz CHECKPOINT datasets, TWSz jobtracking events created during the migration will be lost.

3. Review the INSTALLATION GUIDE chapter on MIGRATION, noting which datasets must be *EMPTY* (freshly allocated) when the TWSz Controller is started for the first time on the new release. Many customers incorporate the TWSz release (i.e. V8R6M0) in the DSNames of all datasets. If this is done, these datasets can be allocated ahead of time in preparation for the migration, thus reducing the actual down time.

4. At the selected time, note which JCL Repository dataset (EQQJS1DS or EQQJS2DS) is in use (ISPF dialog option 6.6, panel EQQSGCPP)

5. STOP (do not CANCEL) the CONTROLLER and review the EQQMLOG for message EQQN057I to make certain the shutdown processing completed normally.

  • NOTE: Running a REPLAN after stopping the CONTROLLER and before the database conversion is no longer recommended except in the following special situation.

    The main reason for the REPLAN was to move the contents of the JT datasets into the EQQTROUT so they would be available to the EQQAUDIT program. But changes to TWSz over the last several releases have made this pre-conversion REPLAN more trouble than it is usually worth.

    If retaining EQQAUDIT data is important, the simplest solution is to run an EQQAUDIT job (input JTX) after the CONTROLLER has been stopped and keep the output.

    But if that last increment of raw EQQAUDIT input data ABSOLUTELY MUST be retained in the EQQTROUT of the old release, then BEFORE stopping the CONTROLLER here is how it can be done:
      • > Submit a CP REPLAN JOB (dialog option 3.1) setting TYPRUN=HOLD on the jobcard.
        > STOP the controller. Check the EQQMLOG for messages EQQN057I and EQQN090I to be sure of a complete, clean shutdown.
        > RELEASE the CP REPLAN job and let it run to completion. Verify it ends with an acceptable return code. (IF E2E is used, the TPLGYPRM() keyword must be TEMPORARILY removed from the BATCHOPT init statement for this one job only).
        > On completion of the REPLAN, all job-tracking from the OLD release has been archived to that release's EQQTROUT dataset.
        > JOB TRACKING DATA and the EQQAUDIT program that formats that data are both RELEASE SENSITIVE. Therefore you must:
          • - NOT use the OLD EQQTROUT dataset with the CP BATCH JOBS of the NEW release (DO NOT mix record versions in the same dataset.
            - NOT use the EQQAUDIT program from the NEW release to generate reports from the EQQTROUT dataset from the OLD release -- or vice versa. Retain a copy of the OLD release's SEQQLMD0 and STEPLIB audit jobs to that library when generating reports from the data captured by the OLD release.

6. Whichever way the EQQTROUT issue is handled, at this point the old controller is stopped, and the JT info has been satisfactorily archived. So we can now proceed with the migration process.

7. Run the EQQICTOP dataset migration program (SEQQSAMP member EQQICNVS)

  • A. For EQQCPIN use the EQQCP1DS from the OLD release
      • (If a REPLAN was run AFTER stopping the OLD controller, EQQCPIN must then be the EQQNCPDS of the old release).
    B. For EQQCPOUT use the EQQNCPDS from the NEW release
    C. For EQQCXIN use the EQQCXDS from the OLD release
      • (If a REPLAN was run AFTER stopping the OLD controller, EQQCXIN must then be the EQQNCXDS of the old release).
    D. For EQQCXOUT use the EQQNCXDS from the NEW release
    E. For EQQXDIN use the EQQXD1DS from the OLD release
      • (If a REPLAN was run after stopping the OLD controller, EQQXDIN must then be the
        EQQNXDDS of the old release).
    F. For EQQXDOUT, use the EQQNXDDS from the NEW release.
    G. For EQQJSIN use whichever JSDS was noted in use on the OLD release
    H. For EQQJSOUT use the EQQJS1DS from the NEW release
    I. It is "normal" to get an RC04 with message EQQIC06W on the EQQWSDS because now AWSC records are found. Very few installations have defined any ALL WORKSTATION CLOSED intervals.
     J. For releases 9.3 and higher which include DD for EQQSTIN and EQQSTOUT it it normal to get
     message these message:
     EQQN032E UNABLE TO OPEN VSAM FILE EQQSTIN , VSAM RC = 0008, REASON = 0160
     EQQIC02E UNABLE TO CONVERT FILE ST
     if STEP AWARENESS was not configured and the ST file is empty
     There is no need to migrate an EMPTY file so in this case the line in the SYSIN:
     CONVERT FILE(ST) FROMREL(TWSV9R2M0) TOREL(TWSV9R3M0)
     may be commented out.

     This issue with migrating the ST file ( EQQSTDS/ EQQNSTDS ) has been addressed as part of
     APAR PI79321 (SPE 9.3.0.7):

     Moreover, this APAR improves EQQJOBS
     when creating the EQQICNVS JCL.
     The migration JCL is now customized
     by adding the Step List VSAM
     repository, provided that the STEP
     AWARENESS indicator is set to Yes.

     So applying the relevant PTFs from this list will eliminate the problem:

     UI48340
     UI48346
     UI48341 Korean
     UI48342 English
     UI48343 German
     UI48344 Kanji
     UI48345 Spanish
    • NOTE: Starting with TWSz V9R2 there is a new option, TRACE, to the CONVERT command for the EQQICTOP conversion program. This option defaults to Y, and causes a message EQQIC66I to be written to the mlog of the conversion job for each member of the EQQADDS dataset processed. 

      Here is the JCL assuming NO REPLAN is run after controller shutdown :

      //CONVERT EXEC PGM=EQQICTOP,REGION=2048K
      //STEPLIB DD DISP=SHR,DSN=TWSZ.V9R1M0.SEQQLMD0
      //EQQMLIB DD DISP=SHR,DSN=TWSZ.V9R1M0.SEQQMSG0
      //EQQMLOG DD SYSOUT=*
      //EQQADIN DD DISP=SHR,DSN=TWSZ.V8R6M0.AD
      //EQQADOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.AD
      //EQQWSIN DD DISP=SHR,DSN=TWSZ.V8R6M0.WS
      //EQQWSOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.WS
      //EQQCPIN DD DISP=SHR,DSN=TWSZ.V8R6M0.CP1
      //EQQCPOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.NCP
      //EQQCXIN DD DISP=SHR,DSN=TWSZ.V8R6M0.CX
      //EQQCXOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.NCX
      //EQQLTIN DD DISP=SHR,DSN=TWSZ.V8R6M0.LT
      //EQQLTOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.LT
      //EQQJSIN DD DISP=SHR,DSN=TWSZ.V8R6M0.JS1
      //EQQJSOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.JS1
      //EQQOIIN DD DISP=SHR,DSN=TWSZ.V8R6M0.OI
      //EQQOIOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.OI
      //EQQSIIN DD DISP=SHR,DSN=TWSZ.V8R6M0.SI
      //EQQSIOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.SI
      //EQQRDIN DD DISP=OLD,DSN=TWSZ.V8R6M0.RD
      //EQQRDOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.RD
      //EQQXDIN DD DISP=OLD,DSN=TWSZ.V8R6M0.XD1
      //EQQXDOUT DD DISP=OLD,DSN=TWSZ.V9R1M0.NXD
      //SYSIN DD *
      CONVERT FILE(AD) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(CP) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(CX) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(WS) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(LT) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(JS) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(OI) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(SI) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(RD) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)
      CONVERT FILE(XD) FROMREL(TWSV8R6M0) TOREL(TWSV9R1M0)

      The EQQICNVS member in SEQQSAMP has the JCL assuming a REPLAN was run AFTER the controller was shut down.


8. Make certain that all of the datasets listed in the INSTALLATION GUIDE as needing to be EMPTY (freshly allocated) are in the required state.

9. Set the PARMLIB member for the NEW controller to JTOPTS CURRPLAN(NEW) and JOBSUBMIT(NO). If E2E is used, also set FTWJSUB(NO).

10. If keeping the same CONTROLLER name and no IPL is being done as part of the migration, code OPCOPTS BUILDSSX(REBUILD) SCMNAME(EQQSSCMx,PERMANENT) -- where "x" is the value for your NEW release. This will rebuild the CONTROLLER SUBSYSTEM to the new release and keep it updated until the next IPL, prior to which time, the subsystem definition must be updated in IEFSSNxx.

  • NOTE: When the PERMANENT option of the SSCMNAME parameter is used, the TWSz started task procedure MUST include a STEPLIB to the TWSz SEQQLMD0 library.


11. Start the NEW controller. If running TWSz E2E, do not start the E2E SERVER STARTED TASK at this time. This may require temporarily changing the SERVERS() keyword of the OPCOPTS initialization statement, or bypassing any automation that controls the TWSz started tasks.

  • NOTE: If OPCOPTS OPCHOST(PLEX) is specified, the parameter must be changed to OPCHOST(YES) for the initial startup of the CONTROLLER. It is not possible to start a CONTROLLER with OPCHOST(PLEX) if the EQQCKPT dataset is empty (freshly allocated). After the initial startup, change the parameter back to OPCHOST(PLEX) before any further CONTROLLER restarts.


12. Verify in the EQQMLOG that all tasks including the five GS EXECUTORs start correctly.

13. Verify in the TWSz ISPF dialogs that the CP and LTP appear as expected.

14. Verify in the dialogs that mainframe workstations go to ACTIVE status. Verify by selecting each workstation on panel EQQMWSLL with row command S that the status is ACTIVE, and not ACTIVE WAITING FOR CONNECTION. The "waiting for connection" means there is a problem in the communication between the Controller and Tracker that must be resolved.

NOTE: Automation workstations may not be in the expected status after a migration- that is they
may be in STATUS=U and have to be manually varied to an ACTIVE STATUS.

15. If not using E2E, skip to step 17.

16. If using E2E, delete the E2E workdir and recreate it using the EQQPCS05 job from the NEW release. Then make certain that the E2E server is up and running on the new release (verify good startup in the SERVER EQQMLOG). If any files in the WRKDIR have been customized, such as TWSCCLOG.properties or LOCALOPTS, take care to retain these customized files.

17. ALL USERS, whether using E2E or not, run a CURRENT PLAN REPLAN to verify the batch processing (and if E2E is used, to create and distribute a new E2E SYMPHONY).

18. If all appears ok with the plans and the workstations are active, activate (HOST - mainframe)JOB submission via dialog option 9.2. If using E2E, monitor the FT workstations, and when they come online, activate FT job submission. To test TWSz job submission and job tracking without setting JOB SUBMIT ON. issue the EX command against a few READY operations. The operation will be submitted and tracked and its successors set to READY. (READY status includes R, A, and *).

19. At this point, the basic migration is complete. Reset all initialization parameters to their normal status.

20. IMPORTANT POST-MIGRATION "CLEANUP" INCLUDES:

    • JCL for CP and LTP batch jobs must be updated in the EQQJBLIB. That is, the JCL for older releases *MUST NOT* be used with newer releases. Instead, any JCL saved into a JOBLIB must be replaced with new copies captured from the ISPF dialog options 2 and 3 of the new release
    • All dialog users, whether accessing TWSz directly or through a PIF/DIALOG SERVER, *MUST* use the correct TWSz LOAD LIBRARY, PANEL LIBRARY, and MESSAGE LIBRARY for the new release. Also, all SERVERS must run the same level of code as the CONTROLLER.
    • Make certain that all PIF applications are recompiled (if statically linked) with the new release's version of EQQYCOM, and all BCIT, OCL, and SOE applications are updated to use the correct libraries for the new release. If PIF jobs dynamically invoke EQQYCOM or other TWSz loadmodules, they must have access to the SEQQLMD0 for the current release, either through link list, or a STEPLIB in their JCL.
    • If you have any STANDBY CONTROLLERs, be certain to update their started task procedures and parmlib members as needed.
    • The following items are actually part of the INITIAL INSTALLATION of the new release, but are listed here for emphasis
      • All message customization, panel customization, or other personalization of the TWSz environment must be reapplied to the IBM-supplied libraries of the new release.
      • All TWSz user exits must be updated if necessary, recompiled, and verified.

Documentation to collect if the migration is NOT successful

If the migration is not successful, that is, you need to revert back to the previous release, be sure to have the following set of documentation available for review (if you open a case to determine why the migration did not work):

(A) The complete JOBLOG and EQQMLOG of the controller task on the previous release

(B) If you ran a REPLAN after stopping the controller prior to running the EQQICNVS job, the output from this REPLAN

(C) The JCL and output from the EQQICNVS job  (PGM=EQQICTOP)   

(D) The complete  JOBLOG and EQQMLOG of the controller task on the new release 

(E) If you were using a step-by-step document (migration plan)  please include this also  

[{"Type":"MASTER","Line of Business":{"code":"LOB35","label":"Mainframe SW"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSWL3F","label":"IBM Z Workload Scheduler"},"ARM Category":[{"code":"a8m0z0000001fw9AAA","label":"ZOS-\u003EIZWS-\u003EMigration to a new release"}],"ARM Case Number":"TS000000000","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
30 November 2023

UID

swg21608030