Migrating WML for z/OS base to version 2.2.0

If you currently run WML for z/OS v2.1.0.3, v2.1.0.2, or v2.1.0.1, you have the option to migrate to the latest v2.2.0.

1. Back up your <current-version> code library in case that you need to fall back.
2. Locate the v2.2.0 SMP/E image and Program Directory on your z/OS system.
3. Follow the instructions in the Program Directory to run the SMP/E program and install v2.2.0 WMLz base.

   The SMP/E program installs WMLz base in the default /usr/lpp/IBM/aln/v2r1m0 directory, which is referred as $IML_INSTALL_DIR. The directory structure should look similar to the following example:

   
4. Install the latest product updates (APARs and PTFs) for v2.2.0. See Prerequisites and maintenance for IBM Machine Learning for z/OS for instructions.
5. Stop all <current-version> services and processes that are running on WMLz base, including those of Jupyter Kernel Gateway, scoring service, UI service, core services, and Spark-integration service. See Stopping and starting services running on WML for z/OS base for instructions.

   If you've configured the <current-version> scoring service in a CICS® region, you must also stop the ALNSCSER server and discard the scoring service bundle by issuing the following CICS command:

   
   CEMT SET BUNDLE(ALNSCBDL) DISABLED
   CEMT SET JVMSERVER(ALNSCSER) DISABLED
   CEMT DISCARD BUNDLE(ALNSCBDL)
   CEMT DISCARD JVMSERVER(ALNSCSER)

6. Execute the aln-migrate.sh script in the $IML_INSTALL_DIR/alnsamp directory as shown in the following example:

   aln-migrate.sh <current-version_$IML_HOME_dir> <v2.2.0_$IML_HOME_dir> 

   Make sure that the ID you use to run the script has READ access to the <current-version>_$IML_HOME directory, subdirectories, and files. See Configuring user ID for setting up WML for z/OS base for details about required permissions, environments, and system resources for the user ID.

   When prompted, respond or provide any required information that the script requests. The script will perform the following major tasks:

   • Copy the content from the <current-version> $IML_HOME directory into the new v2.2.0 $IML_HOME directory.
   • Update the configuration files of Jupyter Kernel Gateway, scoring service, Spark-integration service, and other services.
   • Reuse and reassign <current-version> network ports for v2.2.0.

   For the scoring service in a CICS region, the script will also update the ALNSCSER.jvmprofile file in your v2.2.0 $IML_HOME/cics-scoring/configuration/generated/<cics_region_name> directory. Copy the file to <JVMPROFILEDIR> used by the CICS region.

7. Update the bash profile by setting export IML_HOME to the new v2.2.0 $IML_HOME directory and export SPARK_CONF_DIR to the new $SPARK_CONF_DIR directory and then issue the source .profile command to activate the change.
8. Update the metadata table by running the gen-alnwmeta.sh script in the $IML_INSTALL_DIR/alnsamp directory and specifying the -u option as shown in the following example:

   ./gen-alnwmeta.sh -u <current-version>

   The script generates sample JCL files ALNWMETA and ALNWMETA.037. The content of the files is the same but as their names indicate, their encoding is different, with the former in ASCII and the latter in IBM-037. Both files are stored in the $IML_HOME/alnsamp directory.

   Customize and run the JCL job to update the metadata table and other database objects. See Creating metadata tables for WML for z/OS repository service for instructions.

9. Start v2.2.0 services and processes, including those of Jupyter Kernel Gateway, scoring service, UI service, core services, and Spark-integration service. See Stopping and starting services running on WML for z/OS base for instructions.

   If you run the scoring service in a CICS region, complete the following steps:

   1. Verify that your CICS region user ID (<cics_region_userid>) can read and write to the $IML_HOME/tmp and $IML_HOME/cics-scoring/configuration directories.
   2. Verify that the same user ID has Read access to the v2.2.0 $IML_INSTALL_DIR/cics-scoring/bundle directory.
   3. Modify the CICS scoring service bundle to point to your v2.2.0 $IML_INSTALL_DIR directory by issuing the following command:

      
      CEDA ALTER BUNDLE(ALNSCBDL) GROUP(ALNSCGRP)
      BUNDLEDIR(v2.2.0 $IML_INSTALL_DIR/cics-scoring/bundle)

   4. Start the ALNSCSER JVM server and the scoring service bundle as described in Steps 10 - 11 in Configuring WML for z/OS scoring services in a CICS region.
10. Sign into the WML for z/OS administration dashboard as an admin user and from the sidebar, navigate to the System Management - Function Level page.
11. Activate new WML for z/OS function level.

    When you open the Function Level page, an administration dashboard service will check and display the WML for z/OS function and metadata levels that are currently running and available on your z/OS system.

    The current function level should be '<current-version>'. If the metadata level is 'v2.2.0' and the new available function level is 'v2.2.0', you have the option to activate new function level, do nothing, or fall back to <current-version>.

    Important: You cannot fall back to <current-version> once you activate the new v2.2.0 function level.

    • Activate v2.2.0 function level. Click Activate to update your function level to v2.2.0. After the process completes successfully, your WML for z/OS base will be running at v2.2.0. You can perform normal machine learning activities, including creating, training, deploying, and scoring models.
    • Do nothing. Your WML for z/OS base will be running in read-only mode. You can continue running the existing scoring workload for testing purpose, but you cannot create, train, or deploy models.
    • Fall back to <current-version>. In this case, complete the following steps to revert your WMLz base installation and environment back to <current-version>:
      1. Stop all v2.2.0 services and processes that are currently running on z/OS, including those of Jupyter Kernel Gateway, scoring service, and Spark-integration service. See Stopping and starting services running on WML for z/OS base for instructions.
      2. Change the export IML_HOME statement in the bash profile to point to the <current-version> $IML_HOME directory and issue a source .profile command to update the environment.
      3. Start all <current-version> services and processes.

         You do not need to revert metadata level from v2.2.0 to <current-version>. The <current-version> code is forward compatible with v2.2.0 metadata objects.