INGCF

Purpose

The INGCF command supports all the functions of SA z/OS® that deal with coupling facilities. It supports full mode and line mode; for line mode capability, see INGCFL. If you issue INGCF in line mode, only the display function is available.

The INGCF command supports the following parameters:

DRAIN
Removes all allocated structures from the coupling facility, to disconnect the coupling facility from the systems of the sysplex, and to inactivate the coupling facility.
ENABLE
Activates a coupling facility, to connect it with the systems of a sysplex and to populate it with structures.
MAINT
Puts the coupling facility into or takes it out of maintenance mode.
PATH
Displays and controls the sender paths of the target coupling facility. It sets the sender paths ONLINE and OFFLINE physically and logically.
STRUCTURE
Displays detail information and rebuilds or deletes a selected structure on the target coupling facility. It also lets you start and stop duplexing.

INGCF associates a status with every coupling facility, and a condition with every structure (instance) that is allocated on the target coupling facility. The structure condition is influenced by the release level of the system that allocated the structure. The INGCF functions use the coupling facility state and the structure conditions to determine which action can be performed in any given situation. Therefore, the DRAIN and ENABLE functions can enforce a correct sequence of actions for complex tasks such as draining or restoring a coupling facility.

If the selected action impacts the sysplex configuration it must be confirmed before execution.

Authorizations

The actions that you can initiate with INGCF depend on your authorizations. The panels show your authorization type. Note that the authorization types apply to the current function, and that your authorization type may vary for different functions.

The following authorization types exist:

DISPLAY: You cannot initiate any action that affects the sysplex configuration.
ALL BUT (ACTIVATE|SHUTDOWN): This type only occurs in the DRAIN and ENABLE command dialogs. You can rebuild structures, force the deletion of structures and set the sender paths offline and online, but you cannot inactivate or activate the coupling facility.
ALL: You can initiate all actions from the corresponding panel.

Depending on your authorizations, it is possible that you have, for example, authorization type ALL for the STRUCTURE function, and authorization type DISPLAY for the DRAIN function.

Note: The actions that modify the sysplex configuration are marked by an asterisk ('*') in the following descriptions.

Syntax

cfname

Parameters

Drain: Prepares a coupling facility for removal from the sysplex.
Enable: Integrates or reintegrates a coupling facility into a sysplex.
Maint: Controls the maintenance mode of a coupling facility.
Path: Controls the sender paths of a coupling facility.
Structure: Offers manipulation of individual structures (detail information, rebuild, deletion).
CF_name: The name of the target coupling facility for the specified function. The default is a selection panel that shows all available coupling facilities of the sysplex.
CONDITION: Specify YES if you want to get the current condition for each structure. Selecting this option increases the response time required to build the display. The default is NO.
MODE: Specify ON if you want to put the coupling facility into maintenance mode, or OFF to take it out of maintenance mode.
TARGET: For information on the TARGET parameter, refer to TARGET Parameter.
OUTMODE: For information on the OUTMODE parameter, refer to OUTMODE Parameter.

Restrictions and Limitations

The ENABLE and the PATH functions require that the active IODF is catalogued. Otherwise, sender path information cannot be retrieved in certain situations.

INGCF ENABLE assumes that the receiver paths from the coupling facility to the systems of the sysplex have been defined and activated. This requires a POR of the CPC that the coupling facility resides on.

Coupling Facility States

The status of a coupling facility can be as follows:

ACTIVATING: The coupling facility is being activated and will then become DRAINED.
DEACTIVATING: The coupling facility is being deactivated and will then become INACTIVE.
DRAINING: The coupling facility is being disconnected from the connected systems.
DRAINED: The coupling facility does not have a connection to any system and can be removed from the sysplex.
DRAINED NOHWACC: The coupling facility does not have a connection to any system, but cannot be removed from the sysplex because the BCP (Basic Control Program) internal interface is not available.
Note: This status is also displayed when the coupling facility has been deactivated from the HMC (Hardware Management Console) but the XCF display commands still return the name of the coupling facility.
ENABLING: The coupling facility is being connected to the systems of the sysplex that use it.
FORCING: Allocated structures are being deleted from the coupling facility. This only happens with structures that have no active connectors, and with these only when they cannot be rebuilt by system-managed rebuild.
INACTIVE: The coupling facility is not active.
INACTIVE NOHWACC: The coupling facility is not active and cannot be activated because the BCP Internal Interface does not have access to the appropriate Support Element.
MAINTMODE: The coupling facility is in maintenance mode and has not allocated any structures. It can now be removed from the configuration or deactivated without touching the sender paths. If you want to move structures back to the coupling facility you need to take it out of maintenance mode before populating it.
MAINTMODE OFFLINE: The coupling facility is in maintenance mode and may have allocated structures. At least one system has set all its sender paths to the coupling facility to OFFLINE. XCF will reject any rebuild command to the coupling facility.
MAINTMODE NOHWACC: The coupling facility is in maintenance mode and has not allocated any structures. It can now be removed from the configuration without touching the sender paths. However, this must be done manually because automation does not have access to the appropriate Support Element. If you want to move structures back to the coupling facility you need to take it out of maintenance mode before populating it.
NORMAL: The coupling facility may have allocated structures and is connected to all systems.
NORMAL MAINTMODE: The coupling facility is in maintenance mode but has allocated one or more structures. The coupling facility is no longer eligible for structure allocations.
NORMAL OFFLINE: The coupling facility may have allocated structures. At least one system has set all its sender paths to this coupling facility to OFFLINE. XES will reject any rebuild request for this coupling facility.
NOTINPOLICY: The coupling facility is active but not defined in the active CFRM policy.
POPULATING: The coupling facility is being populated with all those structures that have it on the first place in their preference list.
REBUILDING: Either all allocated structures that can be rebuilt are being removed from the coupling facility by the XES rebuild process (initiated by DRAIN), or one particular such structure is being removed (initiated by the STRUCTURE).

Structure Conditions

The condition of an allocated structure can be:

Rebuild is not supported.

The structure can neither be rebuilt, nor can its deletion be forced.

The structure has at least one active connector that does not support user-managed rebuild, and at least one active connector that does not support system-managed rebuild.

System-managed processes not supported.

The structure cannot be rebuilt, nor can its deletion be forced.

System-managed rebuild, which is a system-managed process, is not possible for one of the following reasons:

The structure was allocated from a system with OS/390® V2.7 or earlier.
The CFRM couple data sets have not been formatted to support system-managed processes (ITEM NAME(SMREBLD) NUMBER(1) was not specified).

Note: In certain rare cases system-managed processes are not supported although the condition that is displayed on the DRAIN panel seems to indicate the contrary. Then, the rebuild will be initiated, but will fail with message IXC367I indicating that system-managed processes are not supported for the structure.

No alternate coupling facility defined or available.

The structure can neither be rebuilt, nor can its deletion be forced.

The structure has an active connector and supports rebuild but does not have an alternate coupling facility defined in its preference list, or the alternate coupling facilities that are defined in the preference list are currently unavailable.

Insufficient space detected for rebuild.

The structure cannot or could not be rebuilt. Its deletion cannot be forced.

No alternate coupling facility has enough space to rebuild the structure.

Preference list is empty.

The structure cannot be rebuilt because its preference list is currently empty. A possible reason for this is a pending policy change, see P column.

Structure is pending deallocation.

XES accepted a forced deletion of the structure but does the real deallocation later.

Note: This status can only occur when MVS APAR OW39404 has not been installed.

Structure is being rebuilt.

The structure is being rebuilt to another coupling facility.

Duplex rebuild is being stopped.

Two instances of the structure were maintained on different coupling facilities. The application is being disconnected from that instance that is allocated on the target coupling facility. After disconnecting, the instance is deleted.

No connection exists.

The structure cannot be rebuilt, but you can force its deletion.

The structure does not have any connections and cannot be rebuilt with system-managed rebuild.

No alternate coupling facility for structure with no connections.

The structure cannot be rebuilt, but you can force its deletion.

The structure does not have any connections. It could be rebuilt with system-managed rebuild, but no alternate coupling facility is defined in its preference list or available.

No alternate coupling facility for structure with no active connections.

The structure cannot be rebuilt, but you can force its deletion.

The structure has only DISCONNECTING, FAILED, or FAILED-PERSISTENT connections. It could be rebuilt with system-managed rebuild, but no alternate coupling facility is defined in its preference list or available.

The structure’s initial size is less than its actual size.

The SIZE value is greater by twice the INITSIZE value. The structure can be rebuilt, but a SIZE value that is greater than twice the INITSIZE might cause the following:

It might be impossible to allocate a structure at a size of INITSIZE, because the amount of control storage that is required to support the SIZE value might actually be larger than INITSIZE.
If the allocation succeeds, it might result in a structure with a proportionally large amount of its storage allotted to structure controls, leaving too few structure objects to be exploited usefully by the associated application.

For example, if you have requested a maximum size that is very much larger than the initial size, the system will attempt to use a proportionally large amount of the allocated storage for its controls. The result could be that the allocated storage contains control structures for the future maximum size of the structure and insufficient storage might remain for the application's initial use.

No active connection exists.

The structure cannot be rebuilt, but you can force its deletion.

The structure has only DISCONNECTING, FAILED, or FAILED-PERSISTENT connections and cannot be rebuilt with system-managed rebuild.

Note: INGCF DRAIN deallocates structures with this condition as part of the REBUILD action (see REBUILD(10) in INGCF DRAIN). INGCF STRUCTURE accepts a rebuild request for structures with this condition, but deallocates them (see Rebuild (R)).

No connections. System-managed rebuild supported.

The structure can be rebuilt.

The structure does not have any connections, but can be rebuilt with system-managed rebuild.

No active connections. System-managed rebuild supported.

The structure can be rebuilt with system-managed rebuild.

User-managed rebuild is not possible for the structure because it has only DISCONNECTING, FAILED, or FAILED-PERSISTENT connections.

System-managed rebuild is supported

The structure can be rebuilt.

The structure has active connectors. At least one active connector does not support user-managed rebuild, but all active connectors support system-managed rebuild.

Duplex rebuild is active.

The application is connected to two instances of the same structure on different coupling facilities.

[No condition]

When no condition is displayed, the structure can be rebuilt.

The structure has at least one active connection, and all its active connectors support user-managed rebuild.

Structure is awaiting rebuild.

The structure has been selected for rebuild but has not been processed yet.

Structure is currently allocated on cf_name.

The structure can be rebuilt on the target coupling facility with the POPULATE action of the ENABLE function. It is currently allocated on the cf_name coupling facility, but the target coupling facility precedes cf_name in the structure's preference list. This condition is displayed only in the ENABLE command dialog.

Structure allocated in cf_name cannot be rebuilt to this CF.

The structure can probably not be rebuilt on the target coupling facility with the POPULATE action of the ENABLE function. It is currently allocated in the cf_name coupling facility, but the target coupling facility precedes cf_name in the structure’s preference list. And, the actual size of the structure is greater than the free space of the target coupling facility. This condition is displayed only in the ENABLE command dialog.

Example

If you issue INGCF without any parameters, a panel with all coupling facilities of the sysplex is displayed, as shown in Figure 1.

Figure 1. INGCF Selection Panel

 INGLX900                  SA z/OS  - Command Dialogs      Line   1   of 2
 Domain Id   = IPSFO      ---------- INGCF ----------           Date = 02/23/03
 Operator Id = NETOP1                                           Time = 13:42:35

 Sysplex . . . . . . : KEY1PLEX          SM process level  . : 12
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 Cmds: D drain CF / E enable CF / M start or stop maintenance mode              
       P display sender paths / S display structures                            

   CF Name  Total Space Free Space Free% V Lvl LP Node Descriptor
   -------- ----------- ---------- ----- - --- -- ------------------------------
 _ CF01        507392 K   446976 K 88.09 Y  11  D 009672.RX6.IBM.51.000000064516
 _ CF02        245248 K   210944 K 86.01 Y  11  E 009672.RX6.IBM.51.000000064516









 Command ===>
 F1=Help      F2=End       F3=Return                              F6=Roll
                           F9=Refresh                            F12=Retrieve

Specify a function for a selected coupling facility and press Enter.