IBM Support


Technote (FAQ)


A basic guide to upgrading TIVOLI WORKLOAD SCHEDULER for z/OS to a new RELEASE, with emphasis on best practices for a successful migration and elimination of excessive detail provided in product documentation.


In an attempt to cover every possible situation, the creators of the TWS-z/OS INSTALLATION manual 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 - MIGRATION STEPS FOR A SYSTEM IN A HEAVY WORKLOAD ENVIRONMENT), and to check with product support for additional guidance.


The very first thing to remember when approaching a migration of TWSz 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. But the OLD exits may not function correctly with newer releases.
  • Verifying that release-suffixed loadmodules are in a linklisted library (EQQINITx, EQQSSCMx, EQQMINOx).
  • For detailed instructions on INSTALLING, testing, and verifying the new release, consult the TWSz 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 1672977 "Preparation for TWSz migration" at:

For TWS z/OS 9.2 only see technote 1672929 "Migration and Fallback issues for TWSz 9.2 (TWSZOS920 )" at:

For special considerations when migrating from an older release of TWSz see technote
1672997 "TWSz migration issues when skipping release levels" at:

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 workfiles 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. 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.
      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. If you do not want these EQQIC66I messages, code TRACE(N) in the CONVERT command that includes the EQQADDS.

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

      //SYSIN DD *

      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 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.

    • 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.

Related information

Preparation for TWSz migration
Migration and Fallback issues for TWSz 9.2

Document information

More support for: IBM Workload Scheduler for z/OS

Software version: All Versions, Version Independent

Operating system(s): z/OS

Reference #: 1608030

Modified date: 09 July 2015

Translate this page: