Migrating a z/OS federated node

After the deployment manager is migrated and restarted, you can perform the actual migration of its federated application server nodes by running the Job Control Language (JCL) jobs that you generated. When you generated your custom migration jobs, you also created customized instructions for preparing and running the migration jobs in the BBOMMINS members of the CNTL dataset that was used to generate your jobs. Follow these customized instructions to complete the process of migrating your federated nodes to Version 9.0.

1. Ensure that the application servers and the node agent are stopped for the federated node being migrated.

   You must stop the federated node before you proceed.

2. Ensure that the newly migrated deployment manager is running.

   For the application server node to be properly migrated, the deployment manager must be running. For this migration to work, the deployment manager must be up and listening on its SOAP port.

   Table 1. Deployment manager is running . Check when complete

   Check Off	Item
   	Access the administrative console of the WebSphere Application Server Version 9.0 deployment manager. This validates that the deployment manager is running.

   Table 2. Application server is running . Check when complete

   Check Off	Item
   	Ensure that the WebSphere Application Server Version 9.0 copy of the code is running. The version is listed on the Welcome pane of the administrative console.

3. Create and mount a new Version 9.0 configuration file system.

   Before you perform the migration, Version 9.0 requires that a configuration file system be present for your new configuration. You can run BBOMMHFS or BBOMMZFS to create and mount a new configuration file system, or you can mount one manually. Either way, you must have a file system for your Version 9.0 configuration created and mounted before you proceed. This configuration file system is the target of the migration; your Version 7.0 or later configuration file system is the source.

   BBOMMHFS or BBOMMZFS creates a mount-point directory, allocates the configuration's file system, and mounts the file system at whatever value you specified for the mount point when you generated your migration jobs.

   Before you proceed, ensure that you have allocated, created, and mounted your configuration file system datasets either manually or using BBOMMHFS or BBOMMZFS. The mount point should be owned by the WebSphere Administrator user ID and have permissions of at least 755. The new configuration file system structures should be included in BPXPARM so that they will be mounted at the next IPL.

4. Submit BBOWMG1F and BBOWMG2F.
   Note: If you are not using XA connectors, submitting BBOWMG1F and BBOWMG2F is optional. However, you should submit both jobs to ensure that your transaction logs are clear.

   BBOWMG1F enables all servers on the federated application server node being migrated to start in Peer Restart and Recovery (PRR) mode. PRR processing mode resolves any outstanding transactions, clears the transaction logs, and stops the server. BBOWMG2F disables PRR mode and returns all servers to normal operating state.

   Follow these steps to clear the XA transaction logs:

   1. Stop the application server.
   2. Submit the job BBOWMG1F, and verify a return code of 0.
   3. Restart the federated application server, and wait for it to perform PRR processing and stop automatically.
      Tip: After the transactions are resolved and the server stops, a nonzero return code is normal and expected. The following is an example of an acceptable result code from the server process:

      BBOO0035W TERMINATING THE CURRENT PROCESS, REASON=C9C218D5

   4. Submit the job BBOWMG2F, and verify a return code of 0.
5. Copy your generated JCL procedures.

   The migration utility BBOMMCP copies the generated JCL procedures to start the servers to the specified procedure library. Your Version 9.0 configuration must use different JCL procedures from those used by your Version 7.0 or later configuration. This utility will update the new Version 9.0 configuration, substituting your new JCL names in place of the names that existed in your original Version 7.0 or later configuration.

   Caution: This utility copies the generated JCL to your procedure library. If you specified the same names as you used in your Version 7.0 or later configuration when you generated your migration jobs, this utility will overlay the existing procedures. If you are using the same names, make sure that you back up the existing Version 7.0 or later procedures before running this utility in case you need to roll back later.

   Submit BBOMMCP, and verify a return code of 0.

6. If you specified new procedure names, update your RACF® STARTED profiles for the controller and daemon.
   The STARTED profile used by controller regions is based on the procedure name and JOBNAME. You must ensure that a STARTED profile will apply so that the proper identity will be assigned to the started task. If your Version 7.0 or later controller JCL procedure name is AZACR and you specified AZ1ACR for Version 9.0, for example, then you would need to create a STARTED profile for that new procedure name:

                 new controller      same identity used in
                    JCL name         V7.0 or later configuration
                       |                    |
    RDEFINE STARTED AZ1ACR.* STDATA(USER(AZACRU) GROUP(AZCFG) TRACE(YES))

   Note:

   • Do not use a different user ID to start. There are other things tied to the user ID, and other changes would also be required if you change the user ID.
   • If your original STARTED profile was generic, STARTED AZ*.* ... for example, you would not need to create a new STARTED profile.
   • Servant region STARTED profiles are based on JOBNAME, not procedure name. So there is no issue with the servant when you use a different procedure name.
   • Daemons and node agents are controllers; so, using different procedure names for these implies a new STARTED profile.
7. Delete and redefine the log stream if necessary.
   Perform this step only if you previously configured the transaction XA partner log or compensation log on the Version 7.0 or later server to use a log stream.

   1. Make sure that the node is stopped.
   2. Delete and redefine the log stream.

      You can use the BBOLOGSD and BBOLOGSA jobs that were created during Version 7.0 or later customization if you configured the server initially to use the log stream.

      The following sample shows an example of such a job:

      //RLSP1A  JOB 'xxxx,yyy,?','USERID',MSGCLASS=H,
      //         CLASS=J,MSGLEVEL=(1,1),REGION=4M,NOTIFY=&SYSUID
      //STEP1    EXEC PGM=IXCMIAPU
      //STEPLIB  DD   DSN=SYS1.MIGLIB,DISP=SHR
      //SYSPRINT DD SYSOUT=*
      //SYSIN    DD *
      
      DATA TYPE(LOGR) REPORT(YES) /* Default to show output of job */
       DELETE LOGSTREAM NAME(P1ACEL6A.W51ASA2.D)
       DEFINE LOGSTREAM NAME(P1ACEL6A.W51ASA2.D)
              LOWOFFLOAD(20)
              HIGHOFFLOAD(79)
              STG_DUPLEX(YES)
              DUPLEXMODE(UNCOND)
              STG_DATACLAS(OPERLOG)
              STG_SIZE(5000)
              HLQ(Q10RRS)
              LS_SIZE(5000)
              LS_DATACLAS(OPERLOG)
              STRUCTNAME(WAS_LOGRLS)
      /*
      

   If you are migrating nodes in a sysplex, follow this procedure for each federated node that you migrate.

8. Perform one of the following actions:
   1. Submit the BBOWMG3F job.
      Attention: When running in an z/OS environment and configured with multiple TCP/IP stacks, you may need to add the environment variable _BPXK_SETIBMOPT_TRANSPORT to direct the migration job to the proper TCP/IP stack that should be used. If you use the incorrect stack, the result leads to a java.net.UnknownHostException that causes the subsequent wsadmin login to fail.

      An export _BPXK_SETIBMOPT_TRANSPORT=<stack.name> statement is required in the JCL to identify the appropriate stack. Your JCL might look something like this:

      //***************************************************************         
      //*                                                                       
      //* UPGRADE: Perform the migration to the new Profile                     
      //*                                                                       
      //***************************************************************         
      //*                                                                       
      //*                                                                       
      //UPGRADE EXEC PGM=IKJEFT01,REGION=0M,COND=(4,LE)                         
      //SYSTSPRT DD SYSOUT=*                                                    
      //STDENV DD * // _CEE_RUNOPTS=TRAP(ON,NOSPIE) //*                         
      //SYSTSIN  DD *                                                           
        BPXBATCH SH +                                                           
        export _BPXK_SETIBMOPT_TRANSPORT=TCP; +                                 
        /tmp/migrate/bbomigrt2.sh WASPostUpgrade +                              
            /tmp/migrate/28133744/_      +                                      
        1>> /tmp/migrate/28133744/BBOWMG3F.out +                                
        2>> /tmp/migrate/28133744/BBOWMG3F.err;                                 
      /*                         

      BBOWMG3F is the job that performs the physical migration of the Version Version 7.0 or later node to Version 9.0 based on the information that you supplied when you generated your migration jobs. Submit BBOWMG3F, verify that you are getting return codes of 0, and review the log files in the temporary migration directory on the configuration file system. The migration temporary directory is temporary_directory_location/nnnnn, where temporary_directory_location is the directory specified for the temporary directory location (/tmp/migrate by default) and nnnnn is the numeric value generated for the migration identifier when you generated your migration jobs.

   2. Submit the following three jobs:
      1. Submit the BBOWMPRO job.

         BBOWMPRO creates the Websphere Application Server home and default profile.

      2. Submit the BBOWMPRE job.

         BBOWMPRE runs the migration pre-upgrade process.

      3. Submit the BBOWMPOS job.

         BBOWMPOS runs the migration post-upgrade and finish-up (change file permission) processes.

9. Ensure that the old daemon is stopped.

   Ensure that all federated nodes in the same cell on this LPAR are stopped.

10. Update the daemon JCL procedure if necessary.

    WebSphere Application Server for z/OS® Version 9.0 requires that the daemon process be at the highest level of code of any of the servers that it manages on the same LPAR. It will be at the Version 9.0 level when this federated node is started.

    After you migrate all nodes to Version 9.0 and before you remove the previous version's libraries from the system, you must update the daemon JCL procedure. Failure to do so will result in a failure of the daemon to start.

    Note:

    • If you are migrating from Version 6.1 to Version 9.0, the daemon needs to have a STEPLIB that includes the Version 6.1 SBBOLD2 and SBBOLPA datasets.
    • If a Version 9.0 cell has a Version 9.0 server that is communicating with a Version 6.1 server in a Version 6.1 cell that is on the same system as the Version 9.0 cell, you also need to add the version 6.1 SBBOLD2 and SBBOLPA datasets to the STEPLIB of the Version 9.0 daemon.
11. Start the new federated application server node.
    1. Start the node agent.
       The following message is displayed on the console and in the job log of BBON001:

       BBOO0019I INITIALIZATION COMPLETE FOR WEBSPHERE FOR z/OS CONTROL PROCESS BBON001

    2. Start the federated application server.

       Use the existing command that you would use to start a Version 7.0 or later application server, but replace the RACF STARTED procedure name with the value that you entered in the federated node panel for the controller procedure name when you generated your migration jobs. This command starts the Version 9.0 federated application server. Wait until the server is finished initializing before proceeding.

       The following message is displayed on the console and in the job log of BBOS001:

       BBOO0019I INITIALIZATION COMPLETE FOR WEBSPHERE FOR z/OS CONTROL PROCESS BBOS001

12. Verify that your configuration and applications were migrated correctly.

    For Compute Grid or Feature Pack for Modern Batch, also verify that the job scheduler was migrated correctly and that you can dispatch jobs to the servers that host your batch applications.

    To verify the job scheduler migration, after the deployment manager restarts, access the job management console through a web browser.

    To verify that the servers that host your batch applications work correctly:

    1. Verify that the batch applications on the migrated server are started. Examine the server logs for any errors.
    2. Verify that you can dispatch batch jobs to the migrated server by submitting a job from the migrated job scheduler server. You can submit the job by using the Job Management Console, the WSGrid utility, the EJB interface, or the web services interface.