Configuring the CLIP agent back-end on z/OS

Configure the CLIP agent back-end on z/OS®, so that you can use HCL OneTest™ API to record and virtualize DB2® on z/OS applications.

You must be a z/OS systems administrator to configure the CLIP agent back-end. The following changes are needed:

Security profiles

The CLIP requires that the user IDs that are used to run the test programs (including the user id associated with CICS) have OMVS segments and have sufficient access permits to specified security profiles. If the user does not have the required permit, the CLIP session will not start. The CLIP verifies access to the profiles listed in the following table to determine which permits are granted.
Note:

When your security software cannot determine whether a user has access authorization to a profile, CLIP assumes that the user has no access authorization. An example of such a situation is when the profile is not defined.

Table 1. The System Authorization Facility (SAF) information for CLIP functions
FACILITY profile Required access Result
AQE.AUTHDEBUG.STDPGM READ User can record and virtualize problem-state applications.
AQE.AUTHDEBUG.AUTHPGM READ User can record and virtualize problem-state and authorized applications.
For example, the following sample security definitions allow the RITUSR user to debug problem-state applications:
RDEFINE FACILITY (AQE.AUTHDEBUG.STDPGM) -
UACC(NONE) DATA(’RATIONAL HCL OneTest API – PROBLEM-STATE’)
PERMIT AQE.AUTHDEBUG.STDPGM CLASS(FACILITY) -
ID(RITUSER) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
To allow only the RITUSR user to debug authorized programs in an RACF environment, the following commands can be used:
RDEFINE FACILITY (AQE.AUTHDEBUG.AUTHPGM) - 
UACC(NONE) DATA(’RATIONAL HCL OneTest API – AUTHORIZED’) 
PERMIT AQE.AUTHDEBUG.AUTHPGM CLASS(FACILITY) - 
ID(RITUSER) ACCESS(READ) 
SETROPTS RACLIST(FACILITY) REFRESH
Also, associate the RITMGR started task with a user ID authorized to access the BPX.SERVER facility and authorized to execute programs out of the HRELPA dataset.

Server auto-start in COMMNDxx

Add a start command for the RITMGR server to SYS1.PARMLIB(COMMANDxx) to start it automatically at next system IPL. Define CMD=xx in the IEASYSxx parmlib member to specify which COMMNDxx parmlib member should be used during IPL.

After the server is defined and configured, it can be started dynamically (until the next IPL) with the following console command:
S RITMGR

SVC definitions in IEASVCxx

Installation-defined SVCs are defined in SYS1.PARMLIB(IEASVCxx). This method of defining SVCs requires an IPL to be activated. The related load module must be loaded in LPA at IPL time. Define SVC=xx in the IEASYSxx parmlib member to specify which IEASVCxx parmlib member should be used during IPL.

Specify the following in IEASVCxx to define the Compiled Language Interception Processor SVC:
SVCPARM 253,REPLACE,TYPE(3),EPNAME(HRESVC03) /* RDz debug */

SVC number 253 is the default, but any value, within the 200-255 range dictated by z/OS, can be used. The CLIP will detect which SVC number is used.

Avoiding the need to IPL by dynamically installing the SVC

The HCL OneTest API Session Manager started task will dynamically install the SVC. During startup, the HCL OneTest API Session Manager started task, RITMGR, will verify the following items, and will then take the related action, as documented in the following table:
  • Whether the SVC is defined
  • The version of active SVC (if defined) and new SVC (in HRELPA)
  • Whether the SVC=svc_number startup argument specified, where svc_number is the desired SVC number
Table 2. Dynamic Compiled Language Interception Processor SVC update
Operand SVC is defined SVC is not defined
Version of active and new SVC match
  • No action, SVC is already active and current
  • SVC startup argument is ignored
  • Dynamically define SVC by using HRELPA load module
  • SVC startup argument is required
Version of active and new SVC do not match
  • Update SVC by using the HRELPA load module
  • SVC startup argument is ignored
  • Dynamically define SVC using HRELPA load module
  • SVC startup argument is required

LPA definitions in LPALSTxx

LPA data sets are defined in SYS1.PARMLIB(LPALSTxx). Define LPA=xx in the IEASYSxx parmlib member to specify which LPALSTxx parmlib member should be used during IPL.

You can set LPA definitions dynamically (until the next IPL) with the following console command:
SETPROG LPA,ADD,DSN=&HLQ.RIT.HRVD870.HRELPA
Keep in mind the following points when you define the LPA data sets.
  • Data sets listed in LPALSTxx must be cataloged in the master catalog or a user catalog identified in the LPALSTxx member.
  • Adding a new data set to LPALSTxx requires an IPL with CLPA (create LPA) to be activated. To add datasets to the LPA without IPLing, use the SETPROG command.
  • All libraries that are loaded into LPA are automatically considered to be APF-authorized and program controlled. Ensure that you have proper security controls in place for these libraries.

APF authorizations in PROGxx

APF authorizations are defined in SYS1.PARMLIB(PROGxx) by default. Define PROG=xx in the IEASYSxx parmlib member to specify which PROGxx parmlib member should be used during IPL.

You can set APF authorizations dynamically (until the next IPL) with the following console commands, where volser is the volume on which the data set resides if it is not SMS-managed:
SETPROG APF,ADD,DSN=&HLQ.RIT.HRVD870.HRELPA,SMS
SETPROG APF,ADD,DSN=CEE.SCEERUN,VOL=volser
SETPROG APF,ADD,DSN=CEE.SCEERUN2,VOL=volser

LINKLIST definitions in PROGxx

LINKLIST data sets are defined in SYS1.PARMLIB(PROGxx). Define PROG=xx in the IEASYSxx parmlib member to specify which PROGxx parmlib member should be used during IPL.

The required definitions will look like the following example, where listname is the name of the LINKLIST set that will be activated, and volser is the volume on which the data set resides if it is not cataloged in the master catalog:
LNKLST ADD NAME(listname) DSNAME(&HLQ.RIT.HRVD870.HRELOAD) VOLUME(volser)
You can create LINKLIST definitions dynamically (until the next IPL) with the following group of console commands, where volser is the volume on which the data set resides if it is not cataloged in the master catalog:
1. SETPROG LNKLST DEFINE,NAME=LLTMP,COPYFROM=CURRENT 
2. SETPROG LNKLST ADD NAME=LLTMP,DSN=&HLQ.RIT.HRVD870.HRELOAD,VOL=volser 
3. SETPROG LNKLST ACTIVATE,NAME=LLTMP

RITMGR, HCL OneTest API Session Manager started task

Customize the &HLQ.RIT.HRVD870.HRESAMP(HREJCL) sample started task member, as described within the member, and copy it to a dataset in your JES PROCLIB concatenation as member RITMGR. As shown in the following code sample, provide the following information:
  • The time-zone offset. The default EST5DST.
  • The SVC number used by the Compiled Language Interception Processor. The default is 253.
  • The high-level qualifier of the load library. The default is HRV.
//*
//* RIT Session Manager
//*
//RITMGR   PROC PRM=,                   * PRM=DEBUG TO START TRACING
//            LEPRM='RPTOPTS(ON)',
//            TZ='EST5EDT',
//            CLIENT=5435,              * not used
//            HOST=5436,                * not used
//            SVC=253,
//            HLQ=HRV
//*
//RITMGR   EXEC PGM=HREZPCM,REGION=0M,TIME=NOLIMIT,
//            PARM=('&LEPRM ENVAR("TZ=&TZ")/&HOST &CLIENT &SVC &PRM')
//STEPLIB  DD DISP=SHR,DSN=&HLQ..HRELPA
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//         PEND
//*
  • If the Compiled Language Interception Processor SVC is already loaded, the SVC number specified here is ignored and the active SVC number is used.

CLIP and DBRM files

To record and virtualize programs makingCICS® Db2 calls, the Compiled Language Interception Processor needs access to a DBRM data set (PDS or PDS/E). Provide the data set name by using the AQE_DBG_DBRM environment variable. For information about how to set this environment variable, see Setting up the CICS Db2 environment and Setting up the MVS Batch Db2 environment.

CLIP and other Language Environment based debuggers

The CLIP uses Language Environment® (LE) debug facilities. Normally, only one LE-based debugger can be active in a given application, CICS region, Db2 stored procedure, or IMS™ transaction. Because of this limitation, you cannot use CLIP with most other LE-based debuggers. A good indication that a debugger is an LE-based debugger is that it provides a CEEEVDBG load module or alias that must be available to the application.

However, the Compiled Language Interception Processor can coexist with Rational® Developer for System z® Integrated Debugger or IBM® Debug Tool for z/OS. To coexist with these debuggers, the CLIP datasets must be located before the datasets of Rational Developer for System z® Integrated Debugger or IBM® Debug Tool for z/OS datasets in DFHRPL, STEPLIB, or LNKLST concatenations.

Additional LINKLIST considerations

  • Language Environment (LE) must be able to invoke the Compiled Language Interception Processor. Therefore, place the &HLQ.RIT.HRVD870.HRELOAD library either in the LINKLIST or the STEPLIB of the application to be debugged. For more information, see LINKLIST definitions in PROGxx. Keep in mind the following points when you configure the probe:
    • When using LINKLIST, ensure that &HLQ.RIT.HRVD870.HRELOAD is located before the libraries of other LE-based debuggers that hold the CEEEVDBG load module, for example, IBM Debug Tool for z/OS uses hlq.SEQA* libraries.
    • To avoid conflicts, define only one LE-based debugger in LINKLIST.
    • The Compiled Language Interception Processor can coexist with Rational Developer for System Z Integrated Debugger and IBM Debug Tool for z/OS, if the Compiled Language Interception Processor is loaded first by the application.
    • Except for the HCL OneTest API Session Manager started task, the Compiled Language Interception Processor load modules in &HLQ.RIT.HRVD870.HRELOAD do not require authorization to run. The load modules reside here so they can be utilized in an environment that requires authorization.
  • The Compiled Language Interception Processor uses the z/OS Binder. Therefore, place SYS1.MIGLIB in the LINKLIST, or STEPLIB. For details, see the LINKLIST definitions in PROGxx and LPA definitions in LPALSTxx.
  • The Compiled Language Interception Processor uses the z/OS Binder API. This API is available since z/OS 1.10 as /usr/lib/iewbndd.so, and since z/OS 1.13 also as SYS1.SIEAMIGE(IEWBNDD). For z/OS 1.13 and later, place SYS1.SIEAMIGE in the LINKLIST or STEPLIB. For details, see LINKLIST and LPA definitions.
    Note: If SYS1.SIEAMIGE is not in LINKLIST or STEPLIB on z/OS 1.13 and later systems, the Compiled Language Interception Processor will issue the following message and attempt to use /usr/lib/iewbndd.so:
    CEE3501S The module //IEWBNDD was not found

CLIP CICS updates

To record and virtualize CICS transactions, Compiled Language Interception Processor requires the following CICS updates.
  • CICS system initialization (SIT) parameter updates:
    • Specify DEBUGTOOL=YES.
    • Specify TCPIP=YES.
    • Specify RENTPGM=NOPROTECT.
    • Specify at least 500M for the value of EDSALIM.
    • If you rely on LINKLIST to fetch a load module from the DFHRPL DD concatenation, specify LLACOPY=YES.
  • CICS JCL updates:
    • Specify REGION=0M on the EXEC statement.
    • Define the &HLQ.RIT.HRVD870.HRELOAD load library in the region’s DFHRPL DD statement. If SIT parameter LLACOPY=YES is specified, the library can also reside in LINKLIST.
    • Define the SYS1.MIGLIB load library in the region’s DFHRPL DD statement. If SIT parameter LLACOPY=YES is specified, the library can also reside in LINKLIST.
    • For z/OS 1.13 and later, define the SYS1.SIEAMIGE load library in the region’s DFHRPL DD statement. If SIT parameter LLACOPY=YES is specified, the library can also reside in LINKLIST. For details, see the z/OS Binder API information in the CLIP parmlib updates.
    Note: The CICS region user ID requires UPDATE permission to the CSVLLA.dataset profile in the FACILITY class for SIT parameter LLACOPY=YES to work as designed.
  • CICS CSD updates:

    Define the Compiled Language Interception Processor to a CICS region, as documented in the HRECSD sample CSD update job. HRECSD is located in &HLQ.RIT.HRVD870.HRESAMP.

Feedback