System Management Guide

Chapter 5. Managing Switch Communications

This section explains how to view, update, delete, and create a new clone for the switch configuration information, and how to start and stop switch communications.

Configuring Switch Descriptions

A switch description must be stored within CallPath/CICS for each supported switch. This description provides the information needed to set up communications between CallPath/CICS and CallPath SwitchServer/2 for each switch. It also contains information about the functions that each switch supports.

Switch description records are supplied with CallPath/CICS and these should be installed following the procedure described in "Task 5: Creating Switch Description Records". After the records are installed, you need to add further configuration information to the switch descriptions using the panels described in this section. You can update this information whenever you need to.

Viewing Switch Description Configuration Information

To view switch description configuration information:  

1. On the System Administration Menu, select Switch description configuration to see a list of switches you have defined to your system.

   Figure 9. Switch Description Configuration List Panel
   
   
   

   EQZMI01 Switch Description Configuration List Type one or more of these action codes. Then press Enter. 1=View 2=Update 3=Delete 4=Clone Action Switch Type Description _ SWITCH01 COM300 IBM Com300 - switch number 1 _ SWITCH02 COM300 IBM Com300 - switch number 2 F1=Help F3=Exit F5=Refresh F7=Backward F8=Forward F11=Panel ID F12=Cancel

   
      

2. Type 1 (View) next to one or more switches. Then press Enter.

The Switch Description Configuration Details panel displays the description configuration for the switch you chose. If you typed action codes next to more than one switch, the panel is displayed for each in turn. When you have finished viewing the information, press Enter.

Adding or Updating Switch Description Configuration Information

To add or update switch description details:

1. On the System Administration Menu, select Switch description configuration.

   You see the Switch Description Configuration List panel (Figure 9) that lists all the switches defined to your system.

2. Enter 2 (Update) next to the switch or switches you want to update.

   You see the Switch Description Configuration Details panel (Figure 10).

   Figure 10. Switch Description Configuration Details Panel
   
   
   

   EQZMI02 Switch Description Configuration Details Update the details. Then press Enter. Switch name . . . . . . . . . . . . : SWITCH01 Transmit process ID . . . . . . . . : GTRA Receive process ID . . . . . . . . : GREC Profile name . . . . . . . . . . . . ________ Transmit connection name . . . . . . ________ Receive connection name . . . . . . . ________ Type . . . . . . . . . . . . . . . . __________ Model . . . . . . . . . . . . . . . . __________ Description . . . . . . . . . . . . . ______________________________ Switch communications . . . . . . . . _ 1. Automatic startup 2. Manual startup F1=Help F11=Panel ID F12=Cancel

   
   

3. Type the requested information. You can overtype information in all fields except in the Switch name, Transmit process ID, and Receive process ID fields.

4. Press Enter to save your changes.

You can update information about a switch while the switch is in use, but any information that you change does not take effect until communications with the switch are stopped and restarted.

What to Enter in Each Field

The Switch name field is filled in by the system using the switch description records that are already installed. The Transmit process ID and the Receive process ID     are the names of the CallPath SwitchServer/2 transmit processes that the event handler initiates, and the CallPath SwitchServer/2 receive process that the request handler initiates using the LU6.2 facility for communicating between two processes. These are set to GTRA and GREC. Although some of the remaining fields are optional, it is recommended that you complete all the fields.

Table 10. What to Enter on the Switch Description Configuration Details Panel.

Field	What to Enter
Profile name (as defined in "Task 8: Creating Communication Links").	The name of the CICS profile you want to use for your connection to CallPath SwitchServer/2. Up to 8 characters.
Transmit connection name	The name of the CICS connection that points to the LU used by the CallPath SwitchServer/2 transmit process.
Receive connection name	The name of the CICS connection that points to the LU used by the CallPath SwitchServer/2 receive process.
Type (optional)	Switch type. Up to 10 characters.
Model (optional)	Switch model. Up to 10 characters.
Description (optional)	A single line of text describing the switch. Up to 30 characters.
Switch communications	Enter 1 to have communications with the switch started automatically at subsystem startup. Enter 2 to suppress automatic startup.

Deleting Switch Description Configuration Information

Note: This option deletes all the switch description configuration information about the switch you specify. If you want to continue to communicate with the switch after using this option, you must reload the switch description. (See "Task 5: Creating Switch Description Records".)

To delete switch configuration information:

1. On the System Administration Menu panel, select Switch description configuration.

   You see the Switch Description Configuration List panel (Figure 9) listing all the switches defined to your system.

2. Type 3 (Delete) next to the switch or switches whose configuration details you want to delete. Then press Enter.

   You see the Switch Description Configuration Details panel (Figure 10).

3. Press Enter to delete the information. You are asked to confirm your request before the information is deleted.

Adding new Clone Switch Description

To add a Clone switch:

1. On the System Administration Menu, select Switch description configuration.

   You see the Switch Description Configuration List panel (Figure 9) that lists all the switches defined to your system.

2. Enter 4 (Clone) next to the switch or switches you want to base your new switch on.

   You see the Switch Description Configuration Details panel (Figure 11).

   Figure 11. Switch Description Configuration Details Panel
   
   
   

   EQZMI02 Switch Description Configuration Details You must change switch and connection details. Then Press enter. Switch name . . . . . . . . . . . . : CLONE3 Transmit process ID . . . . . . . . : GTRA Receive process ID . . . . . . . . : GREC Profile name . . . . . . . . . . . . RACK Transmit connection name . . . . . . TRN3 Receive connection name . . . . . . . REC3 Type . . . . . . . . . . . . . . . . Q Model . . . . . . . . . . . . . . . . __________ Description . . . . . . . . . . . . . GENERAL-ALL SWITCH FUNCTIONS Switch communications . . . . . . . . 1 1. Automatic startup 2. Manual startup F1=Help F11=Panel ID F12=Cancel

   
   Type the requested information. You can overtype information in all fields except in the Transmit process ID and Receive process ID fields.

   There are three mandatory changes, the Switch Name field is the record key and must be unique so a new name is required, the Transmit and Receive connection names also need to be changed as CICS will not allow duplicate connections.

3. Press Enter to save your changes.

You can update information about a switch while the switch is in use, but any information that you change does not take effect until communications with the switch are stopped and restarted.

What to Enter in Each Field

The Switch name field is filled in by the system using the switch description records that are already installed. The Transmit process ID and the Receive process ID     are the names of the CallPath SwitchServer/2 transmit processes that the event handler initiates, and the CallPath SwitchServer/2 receive process that the request handler initiates using the LU6.2 facility for communicating between two processes. These are set to GTRA and GREC. Although some of the remaining fields are optional, it is recommended that you complete all the fields.

Table 11. What to Enter on the Switch Description Configuration

Field	What to Enter
Switch name This must be entered	The name you want to use for the new switch. If this is a duplicate, an error message will appear.
Profile name (as defined in "Task 8: Creating Communication Links").	The name of the CICS profile you want to use for your connection to CallPath SwitchServer/2. Up to 8 characters.
Transmit connection name This must be entered	The name of the CICS connection that points to the LU used by the CallPath SwitchServer/2 transmit process.
Receive connection name This must be entered	The name of the CICS connection that points to the LU used by the CallPath SwitchServer/2 receive process.
Type (optional)	Switch type. Up to 10 characters. If no type information exists for the selected switch, this field is filled with Clone.
Model (optional)	Switch model. Up to 10 characters.
Description (optional)	A single line of text describing the switch. Up to 30 characters.
Switch communications	Enter 1 to have communications with the switch started automatically at subsystem startup. Enter 2 to suppress automatic startup.

Starting and Stopping Switch Communications

You can start and stop communications with each of your switches independently. You can choose communications to start automatically when the administration subsystem starts. Communications stop automatically when the administration subsystem stops; you have no choice about this. You can also stop and start communications manually at any time.

Communication with the switches can take place only when the administration subsystem is running. For information on how to start and stop the administration subsystem, see "Starting and Stopping the Administration Subsystem".

Both the request handler session and the event handler session to CallPath SwitchServer/2 must be active for communication with the switch to be successful. These sessions are automatically activated and deactivated when you start and stop switch communications.

Controlling Switch Communications Automatically

To have switch communications automatically started when the administration subsystem starts:

1. On the System Administration Menu, select Switch description configuration.

   You see the Switch Description Configuration List panel (Figure 9) listing all the switches defined to your system.

2. Enter 2 next to the switch or switches of your choice.

   You see the Switch Description Configuration Details panel (Figure 10).

3. In the Switch communications field, enter 1 for automatic startup.

Controlling Switch Communications Manually

• On the System Administration Menu, select Switch communications startup/shutdown.

  You see the Switch Communications Startup/Shutdown panel.

To start communications:

• Enter 1 next to the switch or switches of your choice.

  Communication with the switch is started. When communication links are established successfully, the status of the request handler and event handler are set to active. If the CallPath SwitchServer/2 link to the switch is active, switch status is set to active.

To stop communications:

• Enter 2 next to the switch or switches of your choice.

  When communication with the switch is stopped, the switch name is no longer displayed on the switch status panel. You are asked to confirm your request before switch communications are stopped.

Program control of switches

You can use the Switch_Control (STLSWCH) program call in your application to control or view the status of a specified switch, see "Switch_Control (STLSWCH)". For details of how to use the program calls in your applications, refer to the CallPath/CICS for OS/390 Application Programming Guide.

Controlling Communications with Switches in Simulation Mode

This is part of the switch simulator, which application programmers can use to test CallPath Services application programs without a switch and CallPath SwitchServer/2. For more information about the switch simulator, refer to the CallPath/CICS for OS/390 Application Programming Guide.

You can start and stop communications with a simulation of any of your switches. A simulated switch can generate either positive responses or negative responses. You need to choose the response type before starting the simulated switch. (You can change the response type using the simulator panels while the simulated switch is active.)

To start communications:

1. On the System Administration Menu, select Switch communications startup/shutdown.

   You see the Switch Communications Startup/Shutdown panel.

2. Enter 3 next to the switch or switches of your choice.

   You see the Confirm Simulated Switch Startup panel.

3. Specify the type of response you want the simulated switch to generate:

   • For positive responses only, enter: 1

   • For negative responses only, enter: 2

   A simulation of the switch is started. When it is running successfully, switch status is set to simulated.

To stop communications:

1. Enter 2 next to the switch or switches of your choice.

2. On the System Administration Menu, select Switch communications startup/shutdown.

   When the simulation of the switch is stopped, the switch name is no longer displayed on the system status panel. You are asked to confirm your request before switch communications are stopped.

Automatic communications restart

If communications between CallPath/CICS and CallPath SwitchServer/2 are terminated in any way except by a request to stop communications from the system administrator's screen, CallPath/CICS will attempt to restart them automatically.

If the attempt is unsuccessful, CallPath/CICS will wait for a period, then try again. The wait period is 30 seconds for the first ten attempts, and 1 minute thereafter. CallPath/CICS will keep trying to restart communications for 20 minutes. After 20 minutes, it is unlikely automatic restart will succeed without external intervention, and CallPath/CICS no longer tries to restart communications. If a switch that is down is stopped or manually restarted using the EQAC menu, the automatic restart process is abandoned.

Switch_Control (STLSWCH)

An application uses the Switch_Control (STLSWCH) program call to control or view the status of a specified switch. Switch_Control is optional but when used it provides a problem program with the ability to ascertain the status of a particular switch with respect to CallPath/CICS. Switch_Control also permits an application to START or STOP a switch that has been defined to the Callpath services subsystem.

Format

Parameters

switch_name

Specifies the 8 character switch name that is to be controlled.

switch_action

Specifies the action to be performed on behalf of the switch_name. This 8 character action code can be START, STOP or STATUS. If the switch_action is STATUS the API returns the request handler, event handler, actual switch and simulation status for that switch in the last 4 bytes of the switch_action field.

return_code

Specifies the result of the program call execution, which is returned to the program. The return_code variable can have one of the following values:

• STL_OK
• STL_PROGRAM_PARAMETER_CHECK
  This value indicates one of these:
  • The switch_name specifies a value that is not defined to CallPath/CICS, the switch may not be active.
  • The switch_action specifies a value that is not supported by the program call.
• STL_PRODUCT_SPECIFIC_ERR
• STL_CALLPATH_SERVICES_UNAVAIL

  This value indicates that the switch has never been activated and no information is available to the status call.

Usage Notes

The START and STOP switch_action are executed asynchronously so a return code of STL_OK informs the application that the request has been accepted by CallPath/CICS The STATUS switch_action executes synchronously and returns either STL_OK or STL_PROGRAM_PARAMETER_CHECK.
The data returned in the last 4 bytes of switch_action when a STATUS call is made is shown in Table 12.

If the switch has been auto started there will no Simulation Mode information until the switch is stopped and re-started.

Table 12. Status returned by STATUS call

CHAR(1)	Request handler status for this switch	X'00' = Inactive X'10' = Start Request X'20' = Starting X'50' = Shutdown Requested X'60' = Ending X'70' = Link Inactive X'80' = Active X'90' = End Abnormal
CHAR(1)	Event handler status for this switch	X'00' = Inactive X'10' = Start Request X'20' = Starting X'50' = Shutdown Requested X'60' = Ending X'70' = Link Inactive X'80' = Active X'90' = End Abnormal
CHAR(1)	Actual Switch Status.	X'00' = Inactive X'80' = Active
CHAR(1)	Switch in Simulation Mode	'Y' = Simulated 'N' = Not Simulated