Defining the WLM environment and JCL startup procedure for the Java language XML schema repository stored procedure

The XML schema validation stored procedure, XSR_COMPLETE, which is written in Java, can share a WLM environment with other Java routines. You need a JCL procedure that is tailored for starting that WLM environment.

About this task

One of the tasks that installation job DSNTIJRW performs is to call a program that installs a WLM environment with the default name of DSNWLM_JAVA. The installation process configures DSNWLM_JAVA so that you can use it to run the XML schema repository stored procedure XSR_COMPLETE. One of the tasks that installation job DSNTIJMV performs is to install a WLM startup procedure named ssnmWLMJ for that WLM environment.

You only need to follow this process if the predefined settings do not work for you, and you need to make changes to the WLM environment or startup procedure.

Procedure

To set up the WLM environment and JCL startup procedure for XSR_COMPLETE, follow these steps:

  1. In a TSO session, start the IWMARIN0 utility.

    For example, in the ISPF Command Shell, type:

    EXEC 'SYS1.SBLSCLI0(IWMARIN0)'
  2. In the WLM ISPF Choose Service Definition menu, choose option 1 or option 2, depending on your current WLM service definition setup. See the WLM documentation on service definitions for details.
  3. In the Application Environment Selection List panel, type 3 (Modify) next to DSNWLM_JAVA.
  4. In the WLM ISPF Definition Menu panel, choose option 9: Application Environments.
  5. In the Modify an Application Environment panel, you see values like these. 
       Application-Environment  Notes  Options  Help                      
 -------------------------------------------------------------------------- 
                     Modify an Application Environment                      
 Command ===> ____________________________________________________________  
                                                                            
 Application Environment Name . : DSNWLM_JAVA                               
 Description  . . . . . . . . . . Environment for Java procedures           
 Subsystem Type . . . . . . . . . DB2                                       
 Procedure Name . . . . . . . . . DSNWLMJ                                   
 Start Parameters . . . . . . . . DB2SSN=&IWMSSNM,APPLENV='DSNWLM_JAVA'     
                                  ________________________________________  
                                                                           
 Starting of server address spaces for a subsystem instance:                
 1   1.  Managed by WLM                                                     
     2.  Limited to a single address space per system                       
     3.  Limited to a single address space per sysplex
    Subsystem Type
    Specify DB2.
    Procedure Name
    Specify a name that matches the name of the JCL startup procedure for the stored procedure address spaces that are associated with this application environment.
    Start Parameters
    If the DB2® subsystem in which the stored procedure runs is not in a Sysplex, specify a DB2SSN value that matches the name of that DB2 subsystem. If the same JCL is used for multiple DB2 subsystems, specify DB2SSN=&IWMSSNM. Specify an APPLENV value that matches the value that you specify in the Application Environment Name field.
    Starting of server address spaces for a subsystem instance
    Specify 1 (Managed by WLM) or 2 (Limited to a single address space per system).
  6. Modify the pre-defined JCL startup procedure for the stored procedure address spaces that are associated with the WLM application environment.

    The installation process creates a JCL startup procedure similar to this one.

    //DSNWLMJ PROC APPLENV=DSNWLM_JAVA,                        1 
// DB2SSN=DSN,RGN=0K,NUMTCB=5                              2 
//IEFPROC EXEC PGM=DSNX9WLM,REGION=&RGN,TIME=NOLIMIT,  
//   PARM='&DB2SSN,&NUMTCB,&APPLENV'
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN                      3 
// DD DISP=SHR,DSN=DSNA10.SDSNEXIT  
// DD DISP=SHR,DSN=DSNA10.SDSNLOAD  
// DD DISP=SHR,DSN=DSNA10.SDSNLOD2  
//JAVAENV DD DISP=SHR,                                     4  
//   DSN=DSNA10.DSNWLMJ.JAVAENV
//JSPDEBUG DD SYSOUT=*                                     5  
//JAVAOUT  DD PATH='/tmp/javaout.txt',                     6 
//   PATHOPTS=(ORDWR,OCREAT,OAPPEND),                         
//   PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP,SIROTH,SIWOTH)     
//JAVAERR  DD PATH='/tmp/javaerr.txt',                        
//   PATHOPTS=(ORDWR,OCREAT,OAPPEND),                         
//   PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP,SIROTH,SIWOTH)

    Notes:

     1  In this line, the procedure name must be the same as the Procedure Name value in the Create an Application Environment or Modify an Application Environment panel. The APPLENV value must be the same as the Application Environment Name value in the Create an Application Environment or Modify an Application Environment panel. If the Start Parameters field in the Create an Application Environment or Modify an Application Environment panel contains an APPLENV parameter, the APPLENV parameter value in the Start Parameters field value overrides the value in the JCL startup procedure.
     2  In this line, the DB2SSN value must be the same as your DB2 for z/OS® subsystem name. The maximum value of NUMTCB should be 5.
     3  STEPLIB specifies the DB2 and Language Environment® data sets that are necessary for running the stored procedures. At a minimum, you need the Language Environment run time data set, SCEERUN, and the SDSNLOAD data set, which contains the DSNX9WLM program. SDSNLOD2 contains the JDBC and SQLJ dynamic link libraries (DLLs).
     4  JAVAENV specifies a data set that contains Language Environment run time options for Java stored procedures. The presence of this DD statement indicates to DB2 that the WLM environment is for Java routines. This data set must contain the environment variable JAVA_HOME. This environment variable indicates to DB2 that the WLM environment is for Java routines. JAVA_HOME also specifies the highest-level directory in the set of directories that containing the SDK for Java.
     5  Specifies the destination to which DB2 puts information that you can use to debug your stored procedure. The information that DB2 collects is for assistance in debugging setup problems, and should be used only under the direction of IBM® Software Support. You should comment out this DD statement during production.
     6  Specifies HFS files into which the Java run time environment puts information that you can use to debug your stored procedure. This information is for assistance in debugging setup problems. You should comment out these DD statements during production.
  7. Modify the Language Environment run time options data set (JAVAENV data set), _CEE_ENVFILE file, and JVMPROPS file that the installation process created. If you are migrating from Version 9, the installation process does not create the _CEE_ENVFILE file and the reference to it in the ENVAR options list during conversion mode from Version 9.1. You need to add those items after you enter Version 10 new-function mode.

    The default names for those data sets are:

    Data set type Default name
    JAVAENV DSNA10.DSNWLMJ.JAVAENV
    _CEE_ENVFILE /usr/lpp/db2a10/base/classes/dsnenvfile.txt
    JVMPROPS /usr/lpp/java/properties/dsnjvmsp

    The name of the Language Environment run time options data set must be the same as the data set name in the JAVAENV DD statement in the JCL startup procedure for the stored procedure address spaces that are associated with the WLM application environment.

    The installation process uses JCL similar to this to allocate and populate the Language Environment run time options data set.

    Do not include sequence numbers in any of the input data sets. There should be no text after column 72.

    //DSNTIJJ EXEC PGM=IEBGENER
//SYSIN    DD  DUMMY                    
//SYSPRINT DD  SYSOUT=*                 
//SYSUT2   DD  DSN=DSNA10.DSNWLMJ.JAVAENV,                             1 
//             DISP=(,CATLG,DELETE),      
//             UNIT=SYSDA,SPACE=(TRK,1),  
//             DCB=(RECFM=VB,LRECL=255)
//SYSUT1   DD  *
ENVAR("_CEE_ENVFILE=/usr/lpp/db2a10/base/classes/dsnenvfile.txt",  2 
      "DB2_BASE=/usr/lpp/db2a10/base",                             3 
      "JCC_HOME=/usr/lpp/db2a10/jdbc",                                 4 
      "JAVA_HOME=/usr/lpp/java150/J5.0",                               5 
      "JVMPROPS=/usr/lpp/java/properties/dsnjvmsp"),                   6 
MSGFILE(JSPDEBUG,,,,ENQ),                                              7 
XPLINK(ON)                                                             8 

    The installation process uses JCL similar to this to allocate and populate the _CEE_ENVFILE file.

    //DSNTIJR EXEC PGM=IEBGENER
//SYSIN    DD  DUMMY                                                    
//SYSPRINT DD  SYSOUT=*                                                 
//SYSUT2   DD  PATH='/usr/lpp/db2a10/base/classes/dsnenvfile.txt',  9 
//             FILEDATA=TEXT,                                           
//             PATHDISP=(KEEP,DELETE),                                  
//             PATHOPTS=(OWRONLY,OCREAT,OEXCL),                         
//             PATHMODE=(SIRWXU,SIRGRP)                                 
//SYSUT1   DD  *  

CLASSPATH=/usr/include/java_classes/gxljapi.jar                            10 
LIBPATH=/usr/lib/java_runtime                                           11 
STEPLIB=DSNA10.SDSNLOAD                                                    12 

    The installation process uses JCL similar to this to allocate and populate the JVMPROPS file.

    //DSNTIJS EXEC PGM=IEBGENER
//SYSIN    DD  DUMMY                                             
//SYSPRINT DD  SYSOUT=*                                          
//SYSUT2   DD  PATH='/usr/lpp/java/properties/dsnjvmsp',                13 
//             FILEDATA=TEXT,                                    
//             PATHDISP=(KEEP,DELETE),                           
//             PATHOPTS=(OWRONLY,OCREAT,OEXCL),                  
//             PATHMODE=(SIRWXU,SIRGRP)                          
//SYSUT1   DD  *                                                 
# Sets the initial size of middleware heap within non-system heap
#-Xms64M                                                         
# Sets the maximum size of nonsystem heap                        
#-Xmx128M

    Notes:

     1  This is the name of the Language Environment run time options data set.
     2  This line and the ones that follow it define the content of the Language Environment run time options data set. Change any data set names that differ from the ones in your environment.

    The content of the Language Environment run time options data set can have a length of no more than 245 bytes. If the length of the ENVAR options string makes the length of the content of the run time options data set greater than 245 bytes, you need to use a _CEE_ENVFILE file, whose name you specify in the ENVAR parameter. _CEE_ENVFILE identifies an additional file in which you can include more options. You can put all of your run time options in the _CEE_ENVFILE file, or put some options in the ENVAR parameter, and some in the _CEE_ENVFILE file.
     3  The value of DB2_BASE is the highest-level directory in the set of HFS directories that contain DB2 for z/OS code.
     4  The value of JCC_HOME is the highest-level directory in the set of directories that contain the JDBC driver.
     5  The value of JAVA_HOME is the highest-level directory in the set of directories that contain the SDK for Java. The SYSPROC.XSR_COMPLETE stored procedure requires SDK for z/OS, Java 2 Technology Edition, V5 or later.
     6  The value of JVMPROPS is the name of a z/OS UNIX System Services file that contains startup options for the JVM in which the stored procedure runs.
     7  MSGFILE specifies the DD name of a data set in which Language Environment puts run time diagnostics. All subparameters in the MSGFILE parameter are optional. The first subparameter is the DD name.
     8  XPLINK(ON) is required.
     9  The value of PATH must be the same as the value of _CEE_ENVFILE.
     10  CLASSPATH must include the path for the Java class that contains the JAR files for z/OS XML System Services XML schema registration (gxljapi.jar).
    Exception: Do not include the path for gxljapi.jar during conversion mode from Version 9.1.
     11  LIBPATH must include the path for the Java native libraries.
     12  STEPLIB must include the DB2 for z/OS run time library (SDSNLOAD).
     13  The value of PATH must be the same as the value of JVMPROPS.