Creating your first, minimal runtime environment

If you are a first-time user of IBM Z® Monitoring Configuration Manager, creating a minimal runtime environment is a good place to start. This example consists of a z/OS® agent, a monitoring server, and an enhanced 3270 user interface. You can logon to the enhanced 3270 user interface to view data from the z/OS agent.

Before you begin

Read the prerequisites for using Monitoring Configuration Manager.

The OMEGAMON® subsystem must be defined to z/OS.

About this task

Here is a diagram of the minimal runtime environment created by the following procedure:

Figure 1. Overview of a minimal runtime environment
Diagram of the topology of the minimal runtime environment.

To create this minimal runtime environment, you follow the same procedure you would follow to create any runtime environment. The difference is that a minimal runtime environment involves setting fewer parameters, and involves fewer tasks to complete the configuration after running Monitoring Configuration Manager.

Procedure

  1. Submit a job that performs the CREATE action of Monitoring Configuration Manager.

    The CREATE action creates a runtime environment definition library, rte_plib_hilev.RTEDEF, and populates it with an initial set of parameters.

    Example JCL:

    Figure 2. Example JCL to perform the CREATE action. 
    //UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=<lpar>
//S1       EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256
//STEPLIB  DD DISP=SHR,DSN=<tlib_hlq>.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=<tlib_hlq>.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
ACTION            CREATE
RTE_NAME          <rte_name>
RTE_PLIB_HILEV    <rte_plib_hilev>
/*

    Similar JCL is supplied in the KFJJMCM member of the TKANSAM target library.

    Note: Refer to this sample member, KFJJMCM, for any updates to the parameters. Any new or changed parameters will be listed in this member and can be customized according to the action that you want to run.

    Edit the example job statement to match your site's standards. For example, for job name, class, and message class. Consider changing the example job name prefix, UID, to your TSO user ID.

    Replace the placeholders in the example JCL with appropriate values:

    <lpar>
    Run Monitoring Configuration Manager actions on the LPAR where you will start the runtime environment.

    For example, if your site uses JES2, insert a SYSAFF job parameter after the JOB statement to ensure that the job runs on that LPAR.

    <tlib_hlq>
    The high-level qualifiers of the target libraries.
    <rte_name>
    Runtime environment name, 1 - 8 characters.

    Monitoring Configuration Manager uses this name for various purposes, including:

    • MVS™ member names
    • MVS data set name qualifiers
    • z/OS UNIX directory name, all uppercase
    <rte_plib_hilev>
    The high-level qualifiers of the runtime environment definition library:

    rte_plib_hilev.RTEDEF

    Monitoring Configuration Manager uses the values of RTE_NAME and RTE_PLIB_HILEV to set the default value of other parameters, such as RTE_HILEV and RTE_VSAM_HILEV, that are used for data set names. To avoid exceeding the 44-character limit for data set names, the combined length of RTE_NAME and RTE_PLIB_HILEV should not exceed 18 characters. For example, if RTE_NAME is 8 characters, then RTE_PLIB_HILEV should not exceed 10 characters.

    Tip: After running a Monitoring Configuration Manager job, check the KCIPRINT sysout data set.
  2. Edit the parameters in the rte_plib_hilev.RTEDEF library to configure a static hub monitoring server, a z/OS agent, and an enhanced 3270 user interface.

    In the RTEDEF(rte_name) member, set the following CONFIGURE_* parameters to Y:

    CONFIGURE_TEMS_KDS
    Configures a monitoring server (Tivoli® Enterprise Monitoring Server, or TEMS)
    CONFIGURE_ZOS_KM5
    Configures a z/OS monitoring agent
    CONFIGURE_E3270UI_KOB
    Configures an enhanced 3270 user interface address space

    Either delete all other CONFIGURE_* parameters or set them to N.

    The following diagram shows how these CONFIGURE_* parameters, and the default values of related parameters, configure the topology of the runtime environment:

    Figure 3. CONFIGURE_* parameters for a minimal runtime environment
    Diagram of the topology of the minimal runtime environment and the corresponding parameters.

    Also in the RTEDEF(rte_name) member, set the following parameters to match your site-specific standards:

    RTE_STC_PREFIX
    1- to 4-character prefix of the started task names for this runtime environment. The value in the initial set of parameters is OMEG.
    RTE_VTAM_APPLID_PREFIX
    Prefix of the VTAM® applids in this runtime environment. For this minimal runtime environment, there is only one VTAM application: the enhanced 3270 user interface.

    Each VTAM application in a runtime environment has a corresponding parameter for the VTAM applid. The default values of these parameters are the value of RTE_VTAM_APPLID_PREFIX followed by an application-specific suffix.

    In the initial set of parameters created by the CREATE action, the value of RTE_VTAM_APPLID_PREFIX is OMxx, where xx is the value of the z/OS static system symbol SYSCLONE. SYSCLONE is a 1- or 2-character shorthand notation for the system (LPAR) name. This value is one example of why you need to run Monitoring Configuration Manager actions on the LPAR where you will start the runtime environment.

    If you use these values, then the default VTAM applid for the enhanced 3270 user interface is OMxxOBAP. For example, if the system (LPAR) name is ZOS1, then the VTAM applid is OMS1OBAP.

    RTE_USS_RTEDIR
    The path of the z/OS UNIX directory where you want Monitoring Configuration Manager to write runtime files required by the started tasks.

    The TSO user ID that runs Monitoring Configuration Manager jobs must have permission to write to this directory, otherwise the GENERATE action will fail.

    RTE_TCP_PORT_NUM
    The TCP/IP port number on which the monitoring server will listen.
    Tip: Later steps in this procedure describe how to activate VTAM resources and APF-authorize libraries. If you insert the parameter RTE_X_STC_INAPF_INCLUDE_FLAG Y in the RTEDEF(rte_name) member, then the started tasks include a member that performs these steps for you.

    In the RTEDEF(GBL$PARM) member, set the following parameter:

    GBL_HFS_JAVA_DIR1
    The z/OS UNIX path of the Java™ home directory.

    The following diagram shows parameters that configure identifiers and values used by the runtime environment. Notice how the RTE parameters determine the default values of other parameters. For example, the default value of the KDS_TEMS_STC parameter is the value of RTE_STC_PREFIX followed by the suffix DS.

    Figure 4. Parameters that specify z/OS-related identifiers for a minimal runtime environment
    Diagram of the minimal runtime environment, its identifiers, and the corresponding parameters.
  3. Submit a job that performs the DISCOVER action.

    The DISCOVER action discovers CICS regions, Db2 subsystems, IMS control regions, MQ subsystems, and TCP/IP stacks, and then writes corresponding members to the RTEDEF library.

    Strictly speaking, for this minimal runtime environment, you can skip this step, because this runtime environment will run only the z/OS agent, which does not require any subsystem parameters. However, performing the DISCOVER action is still a useful exercise, because it prepares the RTEDEF library for extending the runtime environment to run other agents.

    Reuse the same JCL as before, with the following changes:

     1 
    Optionally, change the program name in the JCL EXEC statement to KCIALPHA.

    KCIALPHA is an APF-authorized version of KCIOMEGA. APF-authorization enables the program to discover more subsystem details.

     2 
    Change the action to DISCOVER.

    Example JCL:

    Figure 5. Example JCL to perform the DISCOVER action
    //UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=<lpar>
//S1       EXEC PGM=KCIALPHA,REGION=0M,DYNAMNBR=256  1 
//STEPLIB  DD DISP=SHR,DSN=<tlib_hlq>.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=<tlib_hlq>.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
ACTION            DISCOVER  2 
RTE_NAME          <rte_name>
RTE_PLIB_HILEV    <rte_plib_hilev>
/*
  4. Submit a job that performs the GENERATE action.

    Reuse the same JCL as before, with the following changes:

     1 
    If you changed the program name to KCIALPHA for the DISCOVER action, change it back to KCIOMEGA before performing the GENERATE action.
     2 
    Change the action to GENERATE.

    Example JCL:

    Figure 6. Example JCL to perform the GENERATE action. 
    //UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=<lpar>
//S1       EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256  1 
//STEPLIB  DD DISP=SHR,DSN=<tlib_hlq>.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=<tlib_hlq>.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
ACTION            GENERATE  2 
RTE_NAME          <rte_name>
RTE_PLIB_HILEV    <rte_plib_hilev>
/*
    The GENERATE action generates the runtime members for the runtime environment, including the started tasks.

    You have completed the steps that involve the configuration software, Monitoring Configuration Manager.

    The remaining steps complete the configuration of the runtime environment outside of the configuration software.

    These complete the configuration steps depend on your site-specific procedures and the requirements of the components, such as the monitoring agents, that you have chosen to configure in the runtime environment. The requirements of each component are described in the separate product documentation for each component.

    Typically, at this point in the procedure for creating a runtime environment, you would need to refer to that separate documentation. However, to help make this first runtime environment procedure stand-alone, and because in this procedure we have selected a fixed set of specific components, the complete the configuration steps are presented here.

    Depending on your user privileges, you might need to ask someone else to perform some or all of the following steps. For example, only z/OS system administrators are typically allowed to write to system libraries.

  5. Use your site-specific procedures to copy the runtime members for started tasks and VTAM definitions to your system libraries.

    Copy the members from the following libraries to your corresponding PROCLIB, VTAMLIB, and VTAMLST system libraries:

    • rte_hilev.SYS1.PROCLIB
    • rte_hilev.SYS1.VTAMLIB
    • rte_hilev.SYS1.VTAMLST

    The default value of the RTE_HILEV parameter is the value of RTE_PLIB_HILEV.

If you followed the earlier tip to set the RTE_X_STC_INAPF_INCLUDE_FLAG parameter to Y, then you can skip the next two steps. However, you should still read these steps to understand the requirements of the runtime environment for VTAM resources and APF-authorized libraries.

  1. Activate the VTAM resources defined by this runtime environment.

    Issue the following VARY ACT MVS system command:

    VARY NET,ACT,ID=rte_vtam_applid_prefixNODE,SCOPE=ALL

    The ID parameter of the VARY ACT command must match the value of the runtime environment parameter RTE_VTAM_GBL_MAJOR_NODE.

    The default value of RTE_VTAM_GBL_MAJOR_NODE is the value of RTE_VTAM_APPLID_PREFIX followed by the string NODE. If you use the RTE_VTAM_APPLID_PREFIX initial value of OMxx, then the default value of RTE_VTAM_GBL_MAJOR_NODE is OMxxNODE, where xx is the value of the z/OS static system symbol SYSCLONE. For example, if the system (LPAR) name is ZOS1, then specify ID=OMS1NODE.

  2. APF-authorize libraries.

    Add the following data sets to the authorized program facility (APF) list:

    • The following runtime environment library:
      • rte_hilev.rte_name.RKANMODU
    • The following target libraries, under the high-level qualifiers of the STEPLIB of the Monitoring Configuration Manager job:
      • TKANMOD
      • TKANMODL
      • TKANMODP
      • TKANMODR

    The runtime member rte_hilev.SYS1.PROCLIB(rte_stc_prefixAPF) contains VARY ACT and SETPROG APF commands for this runtime environment. Different runtime environments require different VTAM resources and APF-authorized libraries, depending on the configured products.

    If you specify the parameter RTE_X_STC_INAPF_INCLUDE_FLAG Y in the RTEDEF(rte_name) member, and then perform the GENERATE action, some started tasks will contain an INCLUDE statement to include that member, so that you do not need to issue these commands separately. Whether started tasks are allowed to perform such commands depends on your local site practices.

    Setting RTE_X_STC_INAPF_INCLUDE_FLAG can be expedient for initial testing. However, typical best practice is to activate VTAM resources and APF-authorize libraries during system initialization rather than each time you start a task. Use the generated SYS1.PROCLIB(rte_stc_prefixAPF) member to identify which libraries you need to add to the APF list at system initialization.

  3. Start at least the following tasks: rte_stc_prefixCN, rte_stc_prefixDS, and rte_stc_prefixTOM.

    The user ID that you associate with these started tasks must have z/OS UNIX superuser privileges and access to the runtime members.

    rte_stc_prefixCN
    OMEGAMON subsystem.

    The OMEGAMON subsystem does not belong to a runtime environment. You only need one OMEGAMON subsystem per LPAR.

    If the OMEGAMON subsystem has already been started, the job for this started task will fail. The JESMSGLG output data set for the failed job will contain the following messages:

    CNDL018I  OMEGAMON SUBSYSTEM ALREADY ACTIVE ... 
CNDL002I  OMEGAMON SUBSYSTEM Vvrm TERMINATED ...

    This is not a problem: your runtime environment will use the already-active subsystem.

    rte_stc_prefixDS
    Monitoring server.
    rte_stc_prefixTOM
    Enhanced 3270 user interface.

What to do next

Logon to the enhanced 3270 user interface and view the monitoring data from the z/OS agent.