The Batch Interface to Code Debug CICS NEWCOPY allows batch compile and link jobs (or standalone linkedit jobs) to communicate with one or more CICS regions and request the NEWCOPY (PHASEIN) of the just-linked load module.

Code Debug CICS does not need to be turned on in a CICS region to use this feature. However, Code Debug CICS transaction and program definitions must be installed in each CICS region referenced, and the Code Debug CICS load library must be in the DFHRPL concatenation or in an installed LIBRARY.

Sample JCL to merge into your existing compile and link (or standalone linkedit) procedures is in SAMPLIB member JCLNEWC. Customize the data set name in the TPCONFIG DD statement. This data set was created in Enabling Debugging Across Multiple-LPARs  in a CICSPlex. Then modify the two related parameters LMOD and CFGMBR to fit into your procedures. Specify the load module name of the newly-linked program in LMOD. Specify your TPCONFIG member name in CFGMBR. Depending on the requirements of your environment, CFGMBR could be a static value.

Task 5.1 Add Necessary Definitions to CICS Regions

The Batch Interface to Code Debug CICS NEWCOPY uses either EXCI, MVS Sockets, or the CICS Web Interface (CWI) to communicate to CICS regions. 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 batch job 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 MVS Sockets within the CICS region, BMC recommends that you use the CICS Web Interface (CWI) communication method instead.

Task 5.1.1 Choose a Communication Method

Select your desired communications method, then follow the applicable following instructions to install the chosen communications method in each CICS region.

Task 5.1.2 Install EXCI

To define the CICS EXCI Connection and Sessions, see SMXDSAMP member CSDEXCI, which 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 batch job's userID. Ensure that RACF, or whatever external security manager you use, has appropriate entries for MRO logon and bind-time security for that userID. For additional information, see section entitled “Security for EXCI” in the IBM Knowledge Center.

Task 5.1.3 Install TCP/IP CICS Sockets (MVS Sockets)

To install this communications method in your CICS region, see IBM Communications Server manual 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. When using this communication method, no security checking is performed.

If that 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 when you add this region to the TPCONFIG member. If your current CICS listener has been customized such that the batch interface 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 a port number to use.

Task 5.1.4 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 NO.

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 port number can be provided when you add this CICS region to the TPCONFIG member.

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

Additional Considerations

The TPCONFIG partitioned data set member referenced in the batch JCL contains NEWC entries which specify which regions to be contacted and the communication method for each region. For example NEWC entries, see SMXDSAMP member MBRTPCNF . Change the transaction code XPNC only if you also changed your definition in the corresponding CICS region. If you specify a transaction code other than CSMI on an EXCI entry, your transaction code will be ignored.

The batch job executes program XPEDNEWC. That program produces a report with a result for each CICS region in the TPCONFIG member used. The return code from XPEDNEWC will also indicate the overall results:

• Return code 00 indicates all CICS regions were successfully contacted and all NEWCOPY requests were successfully performed.
• Return code 04 indicates some CICS regions could not be contacted (might not be "up").
• Return code 08 indicates NEWCOPY failed in one or more of the CICS regions that were successfully contacted.
• Return code 12 indicates that a problem occurred while opening the TPCONFIG data set, that no NEWC entries were in the specified member, or that the specified member name was not found.