Configuring WML for z/OS scoring services in a CICS region

After you install WML for z/OS base, you have the option to configure and run the scoring service in a CICS region. The scoring service will be embedded in a Liberty Profile (JVM) server and used as a CICS resource bundle. You can use the CICS LINK command to run online scoring of SparkML, MLeap, and PMML models.

Before you begin

Procedure

  1. Verify that the $IML_INSTALL_DIR/cics-scoring directory exists, where $IML_INSTALL_DIR refers to the default /usr/lpp/IBM/aln/v2r1m0 directory.

    If the subdirectory is not there, rerun the SMP/E program and reinstall the WMLz base.

  2. Issue the export IML_HOME=<mlz_config_dir> command to set the $IML_HOME global variable in the bash profile to a directory where you want to store all the generated files, including system configurations and logs. You must set the variable; otherwise, the installation will encounter an error.
  3. Copy the mlpubkey.pub and keystore.jks files in binary mode to the $IML_HOME/cics-scoring/configuration directory.
  4. Create a new Liberty Profile server named ALNSCSER in a CICS region.

    The $IML_INSTALL_DIR/cics-scoring/bin directory contains the server.sh script. Use the script to create, configure, and if needed, remove a scoring service server in a specific CICS region.

    You can create and start one scoring service server per CICS region. If you run multiple CICS regions on the same LPAR, you can create a server for each region. Regardless the region, the server must be named ALNSCSER.

    Issue the following command from the $IML_INSTALL_DIR directory to create a new ALNSCSER scoring server in a CICS region:

    cics-scoring/bin/server.sh create <cics_region_name>

    Running the create command generates a scoring.cfg.<cics_region_name> server configuration file in the $IML_HOME/cics-scoring/configuration directory.

  5. Customize the scoring.cfg.<cics_region_name> file.

    In addition to the configuration parameters that you already set during Step 3 of Configuring WML for z/OS scoring services, specify appropriate values for the following parameters:

    -Dcom.ibm.ws.logging.console.log.level
    Specifies the error condition level at which the Liberty Profile server writes a message to the JVM server stdout stream. The default level is INFO.
    JAVA_HOME
    Specifies the location of the Java directory on your z/OS system.
    WLP_INSTALL_DIR
    Specifies the directory of the Liberty Profile installation in your CICS environment. For example, in the IBM CICS Transaction Server for z/OS 5.4.0 installation, the default Liberty Profile directory is /usr/lpp/cicsts/cicsts54/wlp.
  6. If necessary, configure the level of the scoring server log by customizing the log4j2.xml.template file.

    By default, the WML for z/OS scoring service sets the log level to INFO. At this level, the log records all informational messages for all requests that are issued to the scoring server, including those for model deployment. Depending on the volume of requests your scoring service receives, the size of the log file can grow really large and fast. If the volume is consistently high, consider reducing the size of the log file by setting the log level to WARN or ERROR.

    1. Make a copy of the log4j2.xml.template file in the $IML_INSTALL_DIR/cics-scoring/configuration/defaults directory and save it as log4j2.xml.ALNSCSER into the $IML_HOME/cics-scoring/configuration directory.
    2. Open the log4j2.xml.ALNSCSER file and find the lines for logger com.ibm.ml.scoring.online.
    3. Set the log level to WARN or ERROR as shown in the following example:
      
      <logger name="com.ibm.ml.scoring.online" level="WARN" additivity="false">
              <appender-ref ref="Console"/>
      </logger>
    4. Save the log4j2.xml.ALNSCSER file.
  7. Configure the ALNSCSER scoring server for CICS region <cics_region_name> by issuing the following command:
    cics-scoring/bin/server.sh config <cics_region_name>

    The config command reads the parameters in the scoring.cfg.<cics_region_name> configuration file and generates the ALNSCSER.jvmprofile and server.xml files for the ALNSCSER server.

    You can find the ALNSCSER.jvmprofile file in $IML_HOME/cics-scoring/configuration/generated/<cics_region_name> and the server.xml file in $IML_HOME/cics-scoring/usr/<cics_region_name>/servers/ALNSCSER.

  8. Copy the ALNSCSER.jvmprofile file from $IML_HOME/cics-scoring/configuration/generated/<cics_region_name> to <JVMPROFILEDIR> used by your CICS region.
  9. Verify that your CICS region user ID (<cics_region_userid>) can read and write to the following directories and files:
    • $IML_HOME/cics-scoring/configuration
    • $IML_HOME/cics-scoring/usr/<cics_region_name>
    • $IML_HOME/cics-scoring/workdir
    • <JVMPROFILEDIR>/ALNSCSER.jvmprofile
    • $IML_HOME/tmp

    Also, make sure that the ID can read the following directories and files:

    • $IML_INSTALL_DIR/cics-scoring/bundle
  10. Define the ALNSCSER JVM server to CICS by issuing a CEDA command as shown in the following example:
    CEDA DEFINE JVMSERVER(ALNSCSER) GROUP(ALNSCGRP)
    DESCRIPTION(JVM SERVER FOR MLZ SCORING SERVER)
    JVMPROFILE(ALNSCSER) 
    STATUS(ENABLED)

    You can also run the sample JCL ALNSCDEF job in the $IML_INSTALL_DIR/cics-scoring/extra/jcllib directory to define the JVM server to your CICS region.

  11. Define the scoring service bundle to CICS by issuing a CEDA command as shown in the following example:
    CEDA DEFINE BUNDLE(ALNSCBDL) GROUP(ALNSCGRP)
    DESCRIPTION(CICS BUNDLE FOR MLZ SCORING SERVER)
    BUNDLEDIR(/$IML_INSTALL_DIR/cics-scoring/bundle)
    STATUS(ENABLED)

    You can also run the sample JCL ALNSCDEF job in the $IML_INSTALL_DIR/cics-scoring/extra/jcllib directory to define the scoring service bundle to your CICS region.

  12. Start the ALNSCSER JVM server by issuing a CEDA command as shown in the following example:
    CEDA INSTALL JVMSERVER(ALNSCSER) GROUP(ALNSCGRP)
  13. Start the scoring service bundle by issuing a CEDA command as shown in the following example:
    CEDA INSTALL BUNDLE(ALNSCBDL) GROUP(ALNSCGRP)
  14. Verify that the ALNSCSER JVM server and the scoring service bundle are successfully started.

    It can take up to 60 seconds for the scoring service to start. Check scoring-all.log for server status in the $IML_HOME/cics-scoring/workdir/<cics_region_name>/ALNSCSER directory. The server is successfully started if you will see a message similar to the following example:

    |com.ibm.ml.scoring.online.service.ServiceManager| Scoring server started...

    Alternatively, you can issue the CICS CEMT INQUIRE commands to query the status of the JVM server, the scoring service bundle, and the scoring service program:

    CEMT INQUIRE JVMSERVER(ALNSCSER)
    Jvm(ALNSCSER) Ena Prf(ALNSCSER) Ler(DFHAXRO)       
       Threadc(011) Threadl(015) Cur(964350144)           
    
    CEMT INQUIRE BUNDLE(ALNSCBDL)
    Bun(ALNSCBDL) Ena  Par(00001) Tar(00001)         
       Enabledc(00001) Bundlei(scoring-service)
    CEMT INQUIRE PROGRAM(ALNSCORE)      
    Prog(ALNSCORE) Pro Ena   Ced                  
       Resc(0000) Use(0000000000) Any Cex Dpl Ore Ope Jvm 
  15. Add the new ALNSCSER scoring service as a native CICS scoring service to the Scoring Services page of the WML for z/OS administration dashboard. You can then select and use the new scoring service when creating the deployment of a model. See Adding a WML for z/OS scoring service for instructions.
  16. If needed, stop the scoring service and the ALNSCSER server by issuing the following CICS command:
    CEMT SET JVMSERVER(ALNSCSER) DISABLED
    CEMT SET BUNDLE(ALNSCBDL) DISABLED
  17. Restart the ALNSCSER server and the scoring service by issuing the following CICS command:
    CEMT SET JVMSERVER(ALNSCSER) ENABLED
    CEMT SET BUNDLE(ALNSCBDL) ENABLED
  18. If needed, remove the ALNSCSER server installation and configuration from a CICS region by issuing the following command:
    $IML_INSTALL_DIR/cics-scoring/bin/server.sh remove <cics_region_name>