DISCOVER

Edit online

The DISCOVER action discovers CICS® regions, Db2® subsystems, IMS control regions, MQ subsystems, TCP/IP stacks and system symbols on an LPAR, and then creates corresponding members in the runtime environment definition library.

Before you begin

This documentation uses subsystem as an informal collective term for CICS regions, Db2 subsystems, IMS control regions, MQ subsystems, and TCP/IP stacks.

Discovery is not limited to the products that you have configured using CONFIGURE_* parameters. The DISCOVER action always discovers all the subsystems it can.

It is recommended that you review the following topics, which describe the results of the DISCOVER action:

Tip: Bring up all the subsystems you intend to monitor before you run the DISCOVER action. You can re-run the DISCOVER action if any subsystems are added or started on your LPAR after your initial discovery run. In this case, you need to consolidate the respective discovery output in your RTEDEF data set (that is, merge the generated members accordingly).

About this task

The DISCOVER action discovers subsystems and system symbols on an LPAR, and then creates corresponding members in the runtime environment definition library ( rte_plib_hilev.RTEDEF) and populates the members with the discovered data.

The following list provides details about the DISCOVER action:

Run the DISCOVER action on the LPAR whose subsystems you want to discover. For example, insert a JES2 SYSAFF job parameter after the JOB statement to ensure that the job runs on the correct LPAR:
```
/*JOBPARM SYSAFF=<lpar>
```
Use the KCIALPHA program to discover more details. Optionally, for the DISCOVER action only, change the program name in the JCL EXEC statement from KCIOMEGA to KCIALPHA. KCIALPHA is an APF-authorized version of KCIOMEGA. APF authorization enables KCIALPHA to discover more subsystem details, which would otherwise need to be entered manually. If KCIALPHA is run from a load library that is not APF authorized, partial discovery will still be completed, but the job will end with return code 8.
The DISCOVER action can run stand-alone, that is, without requiring an existing RTEDEF data set as pointed to by the RTE_PLIB_HILEV parameter. The resulting RTEDEF will only contain the members produced by discovery and will use the default prefixes for VTAM applids and started task definitions. For more information about this use case, see the example Stand-alone discovery using defaults.
For some subsystem data sets, if an alias is defined for the data set, the DISCOVER action will use the alias name instead of the original data set name. The following parameters will be populated with alias names if they exist: KD2_DBnn_DB2_LOADLIB, KI2_I1nn_CLASSIC_IMS_RESLIB, KN3_TCPXnn_TCPIP_PROFILES_DSN.
After performing a DISCOVER action, review the messages about discovery in the KCIPRINT SYSOUT data set.
The output of the DISCOVER action depends on the subsystem. For more information, see the following topics:
- Parameters created by the DISCOVER action
- Members created by the DISCOVER action
On the first run, the DISCOVER action creates members for each type of subsystem it discovers. On subsequent runs, if the discovery member for a subsystem exists, it will not be overwritten, but instead a comment member (Kpp#lpar) will be created. You must then review the members and manually apply the updates that you want to keep. For more information, see First-time discovery versus rediscovery.

To run a discovery using the DISCOVER action, use the following procedure.

Procedure

Modify the KFJJMCM sample job in TKANSAM (see example below) to select a DISCOVER action.
Specify values for the required parameters RTE_NAME and RTE_PLIB_HILEV.
Run the KFJJMCM job to discover the available subsystems.
The DISCOVER action creates the discovery members in the RTEDEF data set and populates the parameters with discovered values. Job messages for the DISCOVER action are written to the KCIPRINT SYSOUT data set.
Review the content in the discovery members and update as necessary.

Example

Discovering subsystems

The following JCL discovers subsystems on the LPAR ZOS1 and creates corresponding members in TSOUID.MONSUITE.RTEDEF. For example, if the DISCOVER action discovers Db2 subsystems, then it creates the member KD5@ZOS1; or, if that member already exists, KD5#ZOS1.

Figure 1. Example JCL to perform the DISCOVER action

//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=ZOS1
//S1       EXEC PGM=KCIALPHA,REGION=0M,DYNAMNBR=256
//STEPLIB  DD DISP=SHR,DSN=MONSUITE.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
ACTION            DISCOVER
RTE_NAME          RTE1
RTE_PLIB_HILEV    TSOUID.MONSUITE
/*

The JES2 SYSAFF job parameter ensures that the job runs, and the DISCOVER action discovers subsystems, on LPAR ZOS1.

Stand-alone discovery using defaults

The following JCL is used to perform a stand-alone discovery that uses default values.

If you want to discover IMS systems using the stand-alone run of the DISCOVER action and specify different prefixes for started task and VTAM applids, specify the prefixes of your choice in the RTE_VTAM_APPLID_PREFIX and RTE_STC_PREFIX parameters. This way the VTAM and started task prefixes will be honored accordingly in member RTEDEF(KI5@lpar).

Figure 2. Example JCL to perform a stand-alone discovery using the DISCOVER action

//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=ZOS1
//S1 EXEC PGM=KCIALPHA,REGION=0M,DYNAMNBR=256
//STEPLIB DD DISP=SHR,DSN=MONSUITE.TKANMOD
//KCIFLOW DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA)
//KCIVARS DD *
ACTION                     DISCOVER
RTE_NAME                   RTE1
RTE_PLIB_HILEV             TSOUID.MONSUITE

RTE_STC_PREFIX             OMEG
RTE_VTAM_APPLID_PREFIX     OM&SYSCLONE.
/*

If you do not have any SMP/E target libraries on the system on which you want to run a stand-alone DISCOVER action, you can use the utility, TKANSAM(KFJMAINT), with action BLDREMDS to build the necessary minimum data sets (TKANSAM, TKANMOD, and TKANCUS libraries) needed to run the action. Make sure you transfer the created data sets to your remote system where the stand-alone DISCOVER should run and where the necessary APF authorization of the TKANMOD library is made.