Code Debug Service Provider Operator Commands

This section describes the functions, syntaxes, and parameters of the Code Debug Service Provider administrative commands. These MVS operator commands can be entered at a console, an alternate console, or using the TSO operator command interface. The basic command functions are listed in the following table:

Service Provider Commands and Functions

These commands all have a similar format:

 MODIFY xdssname,COMMAND,parameterThe letter F is a valid abbreviation for MODIFY. This is followed by a required space and xdssname representing the started task or batch job name of the Code Debug Service Provider address space. This is followed immediately by a comma (,) and the actual command name.

STATUS Command

Use the STATUS command to display the status of all connected Service Requester address spaces.

An example of the STATUS command is:

 MODIFY XD01SS01,STATUSThe following is an example of output produced by using the STATUS command:

DUMP Command

Use the DUMP command to capture an SVCDUMP of the Service Provider address space and, optionally, a list of between 1 and 14 Service Requester address spaces. The DUMP command should only be used under the direction of Code Debug CICS Customer Solutions.

Examples of the DUMP command are

 MODIFY XD01SS01,DUMPwhich will capture an SVCDUMP of the Service Provider address space, and

 MODIFY XD01SS01,DUMP,ACMEC123which will capture an SVCDUMP of the Service Provider address space and the Service Requester address space ACMEC123.

The following is an example of output produced by using the DUMP command:

SHUTDOWN Command

Use the SHUTDOWN command is used to schedule normal termination of the Code Debug Service Provider address space.

An example of the SHUTDOWN command is:

 MODIFY XD01SS01,SHUTDOWNThe following is an example of output produced by using the SHUTDOWN command:

The following is an example of the output produced if there are Service Requester address spaces still connected:

XSP2502E SHUTDOWN command rejected, 4 connected Service Requester address
spacesUse the STATUS command to display the connected address spaces. The XPOF transaction can be used to terminate Code Debug in each connected address space.

INITTCP Command

Use the INITTCP command to start the TCP communications subtask. The INITTCP command can be abbreviated ITCP.

Examples of the INITTCP command are:

The PORT parameter is optional, allowing the user to override the PORT number originally specified. The PORT parameter can be abbreviated P.

The MEMBER parameter is optional, allowing the user to override the MEMBER name originally specified. The MEMBER parameter can be abbreviated M.

The following is an example of output produced by using the INITTCP command regardless of whether or not PORT or MEMBER are specified:

SHOWTCP Command

Use the SHOWTCP command to display a list of Service Providers to which this Service Provider is currently connected. The SHOWTCP command can be abbreviated STCP.

An example of the SHOWTCP command is:

MODIFY XD01SS01,SHOWTCPThe output produced from this command provides information about the “modify” Service Provider in the XSP2100 message and about all other connected Service Providers in XSP3103 messages. The following is an example of output produced by using the SHOWTCP command:

TERMTCP Command

Use the TERMTCP command to terminate the TCP communications subtask. The TERMTCP command can be abbreviated TTCP.

An example of the TERMTCP command is:

MODIFY XD01SS01,TERMTCPThe following is an example of output produced by using the TERMTCP command:

Product Termination

To completely shut off Code Debug CICS in an entire CICS region, enter the XPOF transaction from any terminal. XPOF is useful when maintenance has been applied to an Code Debug CICSor BMC AMI Common Shared Services module and you want it to take effect without cycling your CICS system.

Because all active sessions must be terminated before shutting off Code Debug CICS, this transaction notifies you of any active sessions and tells you which terminals are running them. Once you have terminated active Code Debug CICS sessions, XPOF removes all Code Debug CICS product hooks and deletes all Code Debug CICS programs.

XPOF Messages

Single Point Product Startup and Shutdown

The optional Remote Operations Command Interface (ROCI) allows both startup and shutdown of the product in multiple CICS regions with one command entered on an ISPF panel. See Installing-and-Customizing-the-Remote-Operations-Command-Interface to implement ROCI. For additional information on the use of ROCI, see section entitled “Remote-Operations-Command-Interface” in the Code Debug CICS Reference space.

Using the Batch Interface to Code Debug CICS NEWCOPY

This section describes the Batch Interface to Code Debug CICS NEWCOPY.

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 Create and Use TPCONFIG. 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.

You may use this jobstep independent of compile and/or linkedit JCL and specify multiple load module names to NEWCOPY. In addition to providing an EXEC parameter, you can supply load module names and/or the MEMBER= parameter via input DDname NEWCINP. You can also provide all data via input DDname NEWCINP and omit the EXEC parameter. Data provided via the EXEC parameter is parsed before any data provided via input DDname NEWCINP. Regardless of input source, only one TP configuration file MEMBER name may be provided.

Comment statements, identified by an asterisk (*) in position 1, may be included in the NEWCINP input data.

Batch Interface to Code Debug CICS NEWCOPY Usage of the Code Debug TP Configuration File

The Code Debug TP configuration file (TPCONFIG) is used for two purposes:

• To identify Code Debug Service Providers that are to share CICSPlex information.
• To identify all of the CICS regions that should be contacted by the Batch Interface to Code Debug CICS NEWCOPY.

Efficiency Considerations

Technically, each member of the TPCONFIG partitioned data set may contain entries for both possible uses mentioned above. This is because each record within a member starts with a record identifier, and records with an identifier for a different purpose are ignored. However, even though it is technically feasible to have all of the information in one member, doing so would be inefficient.

It is possible to lump all Batch NEWCOPY records (NEWC) into one TPCONFIG member, but then each time the Batch Interface to Code Debug CICS NEWCOPY is used, the program will try to contact all CICS regions. The volume of regions contacted could clutter the report produced and extend the Batch Interface’s runtime. In addition, regions that do not contain the program being newcopied would always report errors, increasing the likelihood of other errors being overlooked. Therefore, BMC recommends logically grouping your NEWC entries into members that mirror your site’s program (load library) distribution.

Record Identifiers for Batch Interface to Code Debug CICS NEWCOPY Records

Records in a TPCONFIG member with an asterisk in position one are considered comment records and are ignored. Records that have a blank in position one are scanned for a following record identifier.

The record identifier for the Batch Interface to Code Debug CICS NEWCOPY records is NEWC. Each CICS region that you want to be contacted to attempt NEWCOPY should have a record in the member.

Following the NEWC record identifier are:

• one or more blanks
• the transaction ID to be initiated in CICS (XPNC is recommended)
• one or more blanks
• the IP Port Number for the CICS region (or keyword EXCI if the EXCI communication method is to be used)
• one or more blanks
• the IP Address for the CICS region (or APPLID of the CICS region if the EXCI communication method is to be used).

If a Domain Name Server is available for GETHOSTBYNAME calls, then the Domain Name may be specified instead of the IP Address.

Sample TPCONFIG Records for Batch Interface to Code Debug CICS NEWCOPY

To enable the Batch Interface to Code Debug CICS NEWCOPY, add records similar to those shown in the following figure to your TPCONFIG data set.

TPCONFIG Records for Batch Interface to Code Debug CICS NEWCOPY

Batch Interface to Code Debug CICS NEWCOPY JCL

To utilize the Batch Interface to Code Debug CICS NEWCOPY, add the JCL provided in SMXDSAMP member JCLNEWC to your existing compile/link JCL procedure.

This jobstep communicates to CICS via MVS Sockets, TCPIPSERVICE, or EXCI. This communication is similar to that used for Code Debug’s ROCI capability as described in Installing-and-Customizing-the-Remote-Operations-Command-Interface. You should choose the communications method you are familiar with and that already exists in your CICS environments. BMC recommends using the same connection technique and connection name that was used for ROCI.

Example Batch SYSPRINT Messages

The Batch Interface to Code Debug CICS NEWCOPY writes a message to the log listing the date, SYSID, and APPLID for the program PHASEIN and indicating whether the action was successful. An example is shown in the following figure.

Example of SYSPRINT Messages from Batch Interface to Code Debug CICS NEWCOPY

Canceling AID Blocks

You can use CICS commands to cancel Automatic Initiator Descriptor (AID) control blocks. This is done using the SET TERMINAL or SET CONNECTION operands of the CEMT transaction, the CECI transaction, or EXEC CICS system programming commands. This facility must be used with care when Code Debug CICS is active. Code Debug CICS uses START requests (creating AIDs) to initiate display tasks (DBXG) for remote debugging sessions.

If these tasks are deleted, the remote trap will not be automatically scheduled on the trapping terminal, and the program being debugged will be left in a wait state. These tasks will then have to be manually selected for debugging using the List Abends screen (1.3) or the List All Tasks screen (9.3). For more information on the List Abends (1.3) and List All Tasks (9.3) screens, see Code Debug CICS Reference space.

Suppressing System Dumps Resulting from ASRA and ASRB Abends

CICS by default produces MVS system dumps preceding ASRA and ASRB abends. This is controlled by the System Initialization Table (SIT) parameter DUMP and the entries in the CICS System Dump table. To suppress these system dumps, see DUMP parameter and the section “Suppressing system dumps that precede ASRx abends” in the IBM documentation site.