Installing and Customizing the Remote Operations Command Interface

Task 13.1 Define and Initialize the Configuration File

Within the SMXDSAMP data set, member DBCDEFCI is a job that both defines and initializes the VSAM data set used by ROCI. Your actual data will be added interactively via the ISPF interface. When fully loaded, the data set will contain one 90-byte record per CICS APPLID. It is a VSAM KSDS. Modify the SPACE and VOLUME parameters according to your installation’s needs.

Security on access to the configuration file can be used to limit access to this feature.

Task 13.2 Copy and Customize the CLIST

The Remote Operations Command Interface is an ISPF application driven from a CLIST. Within the SMXDSAMP data set, member DBUGCI is a CLIST that must be copied to either a new or existing CLIST library of your choice, then customized. The customization instructions, which are also provided at the top of the CLIST, are as follows:

change the NODE keyword value on line 1 of the CLIST from CPWR.cMXD170 to the site-specific value for your Code Debug CICS SMXDPDSE and SMXDSAMP libraries.

All of the ISPF panels and messages used by this interface are in SMXDSAMP. LIBDEF will be done within the CLIST to add them to ISPPLIB and ISPMLIB, respectively.

Change the ROCI keyword on line 2 of the CLIST from XPED.ROCI.CONFIG.FILE to the value you used in DBCDEFCI when the data set was defined and initialized.
Change the EXCILIB keyword on line 3 of the CLIST from YOUR.CICS.SDFHEXCI to the name of your CICS EXCI load library. Use the highest CICS release that you are licensed for.
Change the TCPLIB keyword on line 4 of the CLIST from TCPIP.SEZALOAD to the name of your MVS TCP/IP load library.

All of the application programs invoked by this interface are in SMXDPDSE. LIBDEF will be done within the CLIST to add SMXDPDSE, EXCILIB, and TCPLIB to ISPLLIB.

If your terminal displays KATAKANA characters, change the LANG keyword on line 5 of the CLIST to LANG(JAPANESE).
As shipped, the SYSOUT report XDCIRPT will be deleted at close. This report contains all of the Code Debug CICS messages pertaining to startup and shutdown that were generated by CICS regions during this use of the Remote Operations Command Interface. If you want to save this report, modify the ALLOCATE statement for XDCIRPT within the CLIST to include a class [SYSOUT(class)] and/or other valid TSO parameters. For further information on allocating SYSOUT data sets, see section “Allocating Data Sets with the TSO ALLOCATE Command” in the IBM documentation site
The customized CLIST may either be added to your site’s vendor dialogs (or whatever you call such dialogs), invoked from your ISR@PRIM, or it may simply be invoked from the ISPF Primary Option Menu’s ISPF Command Shell option, then entered as: EX CLISTlibraryname(DBUGCI). For assistance in modifying your site’s ISR@PRIM, see your ISPF systems programmer.

Task 13.3 Add Necessary Definitions to CICS Regions

ROCI communicates from ISPF to the various CICS regions via any combination of External CICS Interface (EXCI), TCP/IP CICS Sockets (CICS Sockets), and/or CICS Web Interface (CWI), as specified by the CICS systems programmer. Based on MVS configuration and current use (or lack of use) of TCP/IP, choose one communication method for each CICS region.

EXCI is the most efficient and secure of the three communication methods. BMC recommends that EXCI be used, if possible.

To use the EXCI communication method, both the ISPF interface and the CICS region must be in the same MVS image, unless the CICS region is running in a sysplex that supports cross-system MRO (XCF/MRO). If that is not the case, choose one of the other communications options for that CICS region.

If you are not currently a user of TCP/IP CICS Sockets within the CICS region, BMC recommends that you use the CICS Web Interface (CWI) communication method instead.

Follow the applicable following instructions to install your chosen communications method in your CICS region.

Task 13.3.1 Install EXCI

To define the CICS EXCI Connection and Sessions, see SMXDSAMP member CSDEXCI that contains a sample RDO group.

IBM requires that your CICS region SIT parameters include IRCSTRT=YES for EXCI to be used.

The EXCI connection in CICS is defined as specific. Therefore, security is based on the ISPF userID. Ensure that RACF, or whatever external security manager you use, has appropriate entries for MRO logon and bind-time security, for that ISPF userID. For additional information, see section entitled “Security for EXCI” in the IBM documentation site.

Task 13.3.2 Install TCP/IP CICS Sockets (CICS Sockets)

To install this communications method in your CICS region, see IBM Communications Server space, IP CICS Sockets space.

If you already use this communications method within a CICS region, you may be able to use your current definitions (IP address and port number), depending on compatibility with your current security setup and listener.

Using this communication method, ROCI sends the userID and password (if they were entered when the CICS region was added to the ROCI configuration file) to CICS along with the XPCI transaction code (or user-specified replacement) and a function code. An EXEC CICS VERIFY is done against the userID and password if they are present. Then the userID (if present) is tested to ensure that it is authorized to use the transaction code. If the userID and password are not entered in the ROCI configuration file record for this CICS region, no security checking is performed.

If the procedure just described is compatible with your current CICS listener, no new TCP/IP definitions are required; the region’s existing IP address and port number can be provided to ROCI when you add this region to the configuration file.

If your current CICS listener has been customized such that ROCI cannot use it, you must either define and start the IBM default listener on another port in this region, or use one of the other communication methods. If a new listener is used, see your MVS TCP/IP systems programmer for definition of an IP address and port number to use.

Task 13.3.3 Install CICS Web Interface (CWI)

This communication method requires a CICS SIT setting, an RDO group, and at least one TCPIPSERVICE definition within the CICS region.

In the SIT, ensure option TCPIP is set to YES.
RDO groups installed must include DFHWEB.
The TCPIPSERVICE definition to be installed must be HTTP. Within that definition, the URM parameter should be DFHWBADX or a user-customized module based on DFHWBADX that supports the CWI standard URL. The SSL parameter must be NO. The AUTHENTICATE parameter must be either NO or BASIC. If you specify BASIC, a valid CICS userID and password must be provided when the CICS region is added to the ROCI configuration file.

If you already have a TCPIPSERVICE definition installed in the CICS region that is compatible with the above criteria, no new TCPIPSERVICE definition is required; the existing TCPIPSERVICE IP address and port number can be provided to ROCI when you add this CICS region to the configuration file.

If you must define a new TCPIPSERVICE RDO entry, see your MVS TCP/IP systems programmer for an IP address and port number to use.