INGHWSRV

Purpose

This service and diagnostic command can help you to recover from SA-BCPii connection problems. It also can help to better handle planned Support Element re-boots, which normally would be disruptive to active SA-BCPii connections. The INGHWSRV command lets you:

  • Terminate all BCP internal interface connections and disable the BCP internal interface for this SA agent instance
  • Display Processor Operations and BCP internal interface NetView common global variables (CGLOBALs)
  • Display specific target hardware or system NetView common global variables (CGLOBALs)
  • Free control blocks that are associated with abended hardware system connection and clear hanging software locks
  • Force to terminate the BCPii connection to a specified target hardware or establish a BCPii connection to this target hardware
  • Permanently suspends the usage of a BCPii connection to the specified target hardware or resume from this connection mode afterwards
  • Enforce BCPii session priority for nominated applications
  • Display status details of the connection to the specified target hardware

Syntax

Read syntax diagramSkip visual syntax diagram INGHWSRV TERMGLOBALLCHECKLOCALCPCBCPIIPRIOGDPSNONEtarget_system_nametarget_hardware_nameFORCECONNECTSTATCOMSUSPENDHOLDRESUME

Parameters

TERM
Terminates all BCP internal interface connections and disable the BCP internal interface completely. An System Automation agent restart or an ACF COLD start may be required to re-establish the SA-BCPii again.
GLOBAL
Displays Processor Operations and BCP internal interface common global variables.
LCHECK
Scans NetView CGlobal pool for any available SA-BCPii lock variable and delete it. This command issues no additional message.
LOCALCPC
Returns the processor name of the local CPC as defined in the active PDB, followed by netid.nau address of the attached support element.
Note: This data is returned in a PIPE KEEP, which has the name LOCALCPC.
BCPIIPRIO appl_designator
SA-BCPii protocol usage is shared between SA z/OS and applications like GDPS. Currently no serialization mechanism grants exclusive non-disruptive usage of an SA-BCPii session when needed.

The BCPIIPRIO flag allows you to prevent active SA-BCPii sessions from being terminated by SA z/OS.

While this flag is set, the internal SA-BCPii session management will not try to terminate SA-BCPii connections relevant for the application identified by the designator. The setting of this flag is not persistent. It must be set after each System Automation agent start. The scope of the flag is the System Automation agent where it was set. The currently supported appl_designators are:
GDPS
If the IBM Service Offering GDPS is installed, configured and running, SA_BCPii session terminations to processors also defined in the GEOPLEX domain/options of this System Automation agent will NOT be executed by the internal SA-BCPii session management. However, session terminations issued by GDPS or by using a INGHWSRV command function will still work.
NONE
Clears the existing BCPIIPRIO setting, if any. The internal SA-BCPii session management may now terminate active SA-BCPii sessions again.
Note, that specifying BCPIIPRIO without an appl_designator shows the current flag setting in WTO message ING823I.
target_system_name
Displays NetView common global variables (CGLOBALs) for the specified target system name.
target_hardware_name (no parameters)
Displays NetView common global variables (CGLOBALs) for the specified target hardware name.
target_hardware_name_FORCE
Enforces termination of the BCPii connection to the target hardware.
target_hardware_name_CONNECT
Establishes the BCPii connection to the target hardware.
target_hardware_name_STATCOM (added in OA61513)
Displays the BCPii connection details to the target hardware.
target_hardware_name_SUSPEND
The BCPii connection to the target hardware is put into SUSPENDED mode, a running connection is terminated before it is suspended. The only action possible for a suspended connection is RESUME.
target_hardware_name_SUSPEND_HOLD (added in OA61513)
The BCPii connection to the target hardware is put into HOLD mode while a running connection is maintained. The only action possible for a suspended connection is RESUME.
target_hardware_name_RESUME
A previously suspended BCPii connection is put back into normal mode. In that mode, a CONNECT can be issued again.

Restrictions and Limitations

This command is provided as a diagnostic service and recovery tool for SA-BCPii connections only. Do not use it for normal SA-BCPii operation. Be also aware of this restriction when this command is called from an automation script.

The setting of the BCPIIPRIO flag has side effects for 'INGAMS REFRESH' and 'ACF COLD' processing if processor/system/lpar related ACF data was changed. The internal SA-BCPii session management may trigger the termination and restart for one or multiple processor connections. With the flag set, the termination step is always skipped. The re-initialization of a still active SA-BCPii session will always end successfully, but configuration changes, if any, will not be picked up for this session.

Usage

You should use the FORCE option only after a connection failure to free control blocks that are associated with the target hardware name or as a last option to terminate a SA-BCPii session, if no other application provided method (for example, GDPS) is possible.

The CONNECT tries to start an asynchronous SA-BCPii session to the target hardware, but does not register for specific events. It is expected that applications (for example, GDPS) take care of this.

It is recommended to use SUSPEND as part of an operational procedure before allowing an IBM customer engineer (CE) to perform a repair or a MCL upgrade action which requires an SE reboot or restart. Use RESUME to recover a previously suspended SA-BCPii SE connection, once the IBM CE has ended the repair/upgrade action.

Note, that SA-BCPii application such as GDPS, may provide SUSPEND/RESUME support in their user interfaces or APIs. It is recommended to use the application-provided support in those cases.

A typical use case for BCPIIPRIO with GDPS would be to make sure, that before complex HW operations management actions like IPLs or CPC capacity changes are started, the flag is set and after successful execution set back to NONE again. This reduces the risk that an unwanted automatic SA-BCPii session management action is disruptive for your HW automation. Please note, that technical session problems cannot be avoided with this flag. This also applies to uncoordinated SE maintenance actions, which may require a SE reboot.