This section describes the use of the Remote Operations Command Interface (ROCI). ROCI allows both startup and shutdown of the product in multiple CICS regions from an ISPF interface.

The following screens are described in this section:

• Remote Operations Primary Menu
• Configuration File
• Add Entry
• Update Entry
• Operations Commands
• View Messages pop-up.

These screens are accessed by invoking a CLIST that has been customized for your environment by the system programmer that performed your installation.

Using the ROCI Feature

ROCI is intended for experienced system programmers. It allows the user to see and alter the status of the Code Debug CICS product within defined CICS regions. The user may activate or shut down the Code Debug CICS product in all defined CICS regions via primary commands, or perform those actions against select CICS regions via line commands.

ROCI is especially useful for shutting down and then re-activating the product after periodic maintenance has been applied to the Code Debug CICS product. The shutdown process performs a newcopy operation on all Code Debug CICS programs defined to CICS. Therefore, when maintenance must be applied to the product, the sequence of events should be:

1. Apply maintenance.
2. Shut down Code Debug CICS in all regions.
3. Activate Code Debug CICS in all regions.

Remote Operations Primary Menu

The primary menu shows the name and code number for each available function. These functions include:

• Maintain the Configuration File
• Enter Operations Commands.

Invoking the ROCI CLIST displays the Remote Operations Primary Menu.

Remote Operations Primary Menu

To select a screen, enter the screen ID in the OPTION field. The following screens are available:

• Configuration File (0): Displays the current contents of the configuration file and allows you to add, update, or delete entries on the file.
• Enter Operations Commands (1): Displays the current status of Code Debug CICS within each CICS region. Allows you to activate, shut down, or immediately shut down the product within all or individual CICS regions. Allows you to view the Code Debug CICS messages generated within the CICS regions as a result of your prior command.

Configuration File (0)

The Configuration File screen (0) displays the current contents of the configuration file and allows you to add, update, or delete entries on the file. To access this screen, type the number 0 on the Remote Operations Primary Menu.

Configuration File

Command

Primary command field. Valid entries are:

• ADD: Displays the ADD ENTRY screen.
• END: Returns you to the primary menu screen.

L

Line command field. Valid entries are:

• U (Update): Displays the UPDATE ENTRY screen.
• D (Delete): Deletes this entry from the file.

Output Fields

Applid

Application ID (or other identifier) for this CICS region. This is the key field of the VSAM KSDS configuration file.

The Application ID must be the CICS-specific APPLID if EXCI is used to communicate to this CICS region. However, for the TCP/IP CICS Sockets and CICS Web Interface (CWI) communication methods, this field must simply be unique.

Once entered and saved from the ADD ENTRY screen, this field cannot be updated. To change it, you must delete and then re-add the entry.

Description

A free-form description of the CICS region, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen.

Tran

CICS transaction code to be used by the TCP/IP CICS Sockets and CWI methods of communication, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen. The default transaction code is XPCI. It may be modified by specifying global parameter TRANSID_XPCI. Each CICS region may have a different value for specifying global parameter TRANSID_XPCI.

Tran is not used by the EXCI communication method and is ignored if that method is specified below.

C

Communication method for this CICS region, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen. Valid values are:

• EXCI
• TCP/IP CICS Sockets for CICS
• CICS Web Interface (CWI).

CICS IP Address

The IP address of this CICS region, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen.

CICS IP Address is not used by the EXCI communication method and is ignored if that method is specified.

Port

The IP port number of this CICS region, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen.

Port is not used by the EXCI communication method and is ignored if that method is specified.

ADD ENTRY Screen

This screen is used to add a record to the ROCI configuration file. To access this screen, enter primary command ADD on the Configuration File screen (0).

Add Entry

Input Fields

Command

Primary command field. Valid entries are:

• SAVE: Edits and saves the data currently displayed then returns this screen, refreshed and ready for another entry.
• END: Edits and saves the data currently displayed then returns to the Configuration File screen (0).
• CANcel: Does not edit or save the entered data. Returns to the Configuration File screen (0).

Applid

Application ID (or other identifier) for this CICS region. This required field is the key of the VSAM KSDS configuration file.

Description

A free-form description of the CICS region. This optional field is displayed on the Configuration File screen (0) and the Operations Commands screen (1) to help identify the CICS region.

Connection Type

The communication method to be used for this CICS region. Valid entries are:

• For the EXCI method
• For the TCP/IP CICS Sockets for CICS method
• For the CICS Web Interface (CWI) method.

Transaction Code

CICS transaction code to be used by the TCP/IP CICS Sockets and CWI methods of communication. This entry should match the Code Debug CICS global parameter TRANSID_XPCI for this CICS region. The transaction definition is provided with all the other CSD entries in the base Code Debug CICS installation.

Transaction code is not used by the EXCI communication method and is ignored if that method is specified.

CICS IP Address

The IP address of this CICS region. This field is required if connection type is either (2) or (3). Enter an IP address in nodal format (n.n.n.n). Each node (n) is numeric and in the range 0–255.

Port

The IP port of this CICS region. This field is required if connection type is either (2) or (3). Enter numerics in the range 1–65535.

CICS signon userID

This optional field is used only if entered and if connection type is either (2) or (3). If your installation standards require this field to be entered, provide a userID that is authorized to use the transaction code entered above.

CICS signon password

This optional field is only entered when CICS signon userID is also entered. It must be the correct password for the CICS signon userID.

The password field is not displayed. Once entered, it is encrypted using a proprietary formula and stored on the configuration file. It is only decrypted when communication with the CICS region is taking place.

If this password ever changes, an update of this field must be done after a new password has been determined. An incorrect or expired password causes the Operations Commands screen (1) to give a response of definition error for connection type (2) or authorization error for connection type (3).

Output Fields

There are no output fields on this screen.

UPDATE ENTRY Screen

This screen is used to update a record already on the ROCI configuration file. To access this screen, enter line command U on the Configuration File screen (0).

Update Entry

Input Fields

Command

Primary command field. Valid entries are:

• END: Edits and saves the data currently displayed, then returns to the Configuration File screen (0).
• CANcel: Does not edit or save the entered data. Returns to the Configuration File screen (0).

Description

A free-form description of the CICS region. This optional field is displayed on the Configuration File screen (0) and the Operations Commands screen (1) to aid in identifying the CICS region.

Connection Type

The communication method to be used for this CICS region. Valid entries are:

• For the EXCI method
• For the TCP/IP CICS Sockets for CICS method
• For the CICS Web Interface (CWI) method.

Transaction Code

CICS transaction code to be used by the TCP/IP CICS Sockets and CWI methods of communication. This entry should match the TRANSID_XPCI field of the Code Debug CICS global options within the CICS region. The transaction definition is provided with all the other CSD entries in the base Code Debug CICS installation.

Transaction code is not used by the EXCI communication method and is ignored if that method is specified.

CICS IP Address

The IP address of this CICS region. This field is required if connection type is either (2) or (3). Enter an IP address in nodal format (n.n.n.n). Each node (n) is numeric and in the range 0–255.

Port

The IP port of this CICS region. This field is required if connection type is either (2) or (3). Enter numerics in the range 1–65535.

CICS signon userID

This optional field is used only if entered and if connection type is either (2) or (3). If your installation standards require this field to be entered, provide a userID that is authorized to use the transaction code entered above.

CICS signon password

This optional field is only entered when CICS signon userID is also specified. It must be the correct password for the CICS signon userID.

Because the original entry in this field is not decrypted and re-displayed during update operations, this field must be re-entered every time an update is required and the CICS signon userID field is non-blank.

The password field is not displayed. Once entered, it is encrypted using a proprietary formula and stored on the configuration file in that format. It is only decrypted when communication with the CICS region is taking place.

If this password is ever changed, an update of this field must be done after a new password has been determined. An incorrect or expired password causes the Operations Commands screen (1) to give a response of definition error for connection type (2) or authorization error for connection type (3).

Output Field

Applid

Application ID (or other identifier) for this CICS region. This field is the key of the VSAM KSDS Configuration file.

Operations Commands Screen (1)

This screen provides the current status of CICS regions defined to the configuration file, and allows the user to send requests to those CICS regions that are connected at the current time. To access this screen, type the number 1 on the Remote Operations Primary Menu.

Operations Commands

Input Fields

Command

Primary command field. Valid entries are:

• ACTIVate: Sends an ACTIVATE request to every CICS region on the configuration file that is inactive, including those CICS regions not shown on the current screen.
• STOP: Sends a SHUTDOWN request to every CICS region on the configuration file that is active, including those CICS regions not shown on the current screen.

If any Code Debug CICS debugging sessions still exist in the CICS region, the STOP request will fail and the REASON field will contain View Messages. The messages will contain a list of terminal and user IDs for those debugging sessions.

• STOP IMMEDiate: Sends a SHUTDOWN FORCE request to every CICS region on the configuration file that is active, including those CICS regions not shown on the current screen.

If any Code Debug CICS debugging sessions still exist in the CICS region, the STOP IMMED request will force them to end. However, the IMMEDiate option will also cause Code Debug CICS to force the end of any long-running tasks in the CICS region. Use STOP IMMED with caution.

• RESet: Clears all Line Command fields on the screen.

L

Line command field. This field is only enterable when the CICS region’s status allows for entry of a line command (a CICS region with no connection cannot act on a line command). Valid entries are:

• A (Activate): Sends an ACTIVATE request to this CICS region.
• S (Stop): Sends a SHUTDOWN request to this CICS region. See the detailed description of this primary command.
• I (Stop Immediate): Sends a SHUTDOWN FORCE request to this CICS region. See the detailed description of this primary command.
• V (View Messages): Causes a scrollable pop-up window to display, containing the Code Debug CICS messages generated as a result of the previous command sent to this CICS region. This is helpful when the result of the previous command is not what was expected.

Output Fields

Applid

Application ID (or other identifier) for this CICS region. This is the key field of the VSAM KSDS configuration file.

Description

A free-form description of the CICS region, as entered on the ADD ENTRY screen and/or updated on the UPDATE ENTRY screen.

Response

Values you may see in this field include:

• CICS N/A: Attempts to connect to this CICS region have failed. The region may not be started or the communication method may not be installed/activated within it.
• Active: Connection to this CICS region has been established, and the Code Debug CICS product is on.
• Inactive: Connection to this CICS region has been established, and the Code Debug CICS product is not on.
• Defn error: Connection to this CICS region has been established, but an error has occurred. Review the CICS region log for more information. Possible causes include:
  • Transaction code is not defined to CICS.
  • Programs are not defined to CICS or are not found in the DFHRPL concatenation.
  • (For connection type 2) A security error has occurred.
• Auth error: Connection to this CICS region has been established. This CICS region requires a signon but either no userID/password were sent, or the userID/password combination sent were invalid.

Reason

Values you may see in this field include:

• View Messages: The previous request sent to this CICS region failed. Use line command V to view the Code Debug CICS messages generated by that previous request in a pop-up window. Viewing those messages resets this field. Primary command RESET also clears this field.
• In progress: The previous request sent to this CICS region has not yet completed. Wait a reasonable interval of time, then press Enter to refresh the entire screen and clear this field.
• Invalid: An invalid line command value has been detected. Clear the line command field.