INGGROUP
Purpose
The INGGROUP command displays the members of a group and their settings. INGGROUP can also be used to:
- Move an application from one system to another by terminating the application and starting it on a system of your choice.
- Activate or deactivate a group.
- Adjust the availability or satisfactory target (server group only).
- Initiate or cancel the rolling recycle of a group.
- Get detailed information of the specified resource(s).
Syntax
Parameters
- group_name
- This is a list of application groups, possibly including wildcards,
that are to be the target of the command.
- For an ADJUST/MOVE action, specify only a single application group.
- For an AVOID/INCLUDE/EXCLUDE action, you can specify several application groups.
- For an ACTIVATE/PACIFY action, you can specify several application groups.
- For a BOX/MEMBERS action, you can specify only a single application group.
- For a DATA action, you can specify a single resource or multiple resources.
- For the RECYCLE/CANCEL action, you can specify several application groups.
- ACTION
- The type of action for the group that the INGGROUP command performs. You can specify one of the
following values:
- EXCLUDE
- Removes resources immediately from the excluded systems. This acts to disruptively force resources from a system.
- AVOID
- No new resources are moved to the system and those that are there are removed as scheduled
service outages permit. This would be used to gradually (and non-disruptively) remove resources from
a system in preparation for an Exclude at a later point in time (mainly to reduce the disruption
caused by the Exclude). However, note that if there is no other way to maintain or restore
application availability, groups choose to ignore avoidance policies.
For instance, when a group goes in recovery mode due to the failure of an active member, another member is started even when its system is in the avoided list. However, when all systems are avoided and a group is stopped and restarted, the group is put in the compound status of AWAITING and no member is started.
- INCLUDE
- The movement of resources to the system depends on the relative preferences of the resources on that system and on other systems. It is possible that the resources will not be moved to that system until the next scheduled service outage.
- ACTIVATE
- Changes the behavior of a group to active. If used on group that is already active, there is no effect. When a group becomes active, it will distribute votes to all of its non-passive members reflecting its nature and goals. Making a group active may cause some of its members to be stopped or started.
- PACIFY
- Changes the behavior of a group to passive. If used on group that is already passive, there is no effect. When a group becomes passive, it withdraws all votes that it has propagated to its members. Making a group passive may cause some of its members to either start or stop, depending upon the votes that it had propagated.
- MEMBERS
- Displays the group members and their settings.
- ADJUST
- Indicates that you want to temporarily adjust a group's policy.
- MOVE (MOVE group model 2 only)
- Directs the automation to activate the indicated member.
- PREPMOVE (MOVE group model 2 only)
- Directs the automation to activate the indicated member when the group is recycled the next
time. Note: The selected member will be activated immediately if the group has no available members and the group's compound status is not SATISFACTORY.
- BOX
- "Box" the group. The currently active member(s) will have a preference that no other member will be selected. This means that if the system where the active member runs is terminated, no other group member will be activated instead. Boxing a group might be of interest when IPLing the system that hosts a primary group member and the "boxed" member is not a primary group member but should stay active.
- UNBOX
- Reverse the BOX action. This means each "boxed" member loses the preference that inhibits other members from being selected. Instead, the preference will be re-evaluated based on the current role and status.
- DATA
- Returns detailed information of the specified
resource(s).
The received data is returned as a multiline message, one line for each resource. The resource data
in each line is displayed in the following sequence using '00'X separator characters:
Attribute sequence Attribute description 1 Group (Member) name/Type/System name (optional) 2 Group name/Type/System name (optional) 3 Observed status 4 Desired status 5 Automation status 6 Automation flag 7 Hold flag 8 Description 9 Start type 10 Stop type 11 Service period name 12 Trigger name 13 Compound status 14 Startability status 15 Resource nature (group type) 16 Category 17 Subcategory 18 Health status 19 Job name 20 Inform list 21 Runmode qualification indicator 22 Desired default status 23 Start pacing gate 24 Stop pacing gate 25 Suspend flag value 26 Group model (1 or 2) 27 Dynamic resource (YES or blank) Leading and trailing blanks are stripped from the tokens, so some tokens might be a string of zero length.
- RESET
- Sets the following group members policies to their initial values. It applies only to MOVE and
SERVER groups.
- Preference values of group members.
- Roles of group members – model 2 groups only.
- Role positions of group members – model 2 groups only.
- Member selection (MOVE/PREPMOVE) – model 2 groups only.
- DEFAULT
- Sets the following group policies to the values that are defined in the policy database:
- Availability and satisfactory targets.
- Preference values of group members.
- Group passive attribute.
- Roles of group members – model 2 groups only.
- Role positions of group members – model 2 groups only.
- Member selection (MOVE/PREPMOVE) – model 2 groups only.
- OVERRIDES
- Displays the overrides for the specified resource groups that have been made with the INGGROUP command.
- POLICY
- Displays the policies for the specified resource groups.
- RECYCLE
- Causes a rolling recycle to be initiated for each selected server or move group. Note: If you specify more than one group and any of them have common members, only one of the groups can be involved in a complete rolling recycle. The other groups are flagged as being involved in a partial recycle, that is, some of their members (possibly all of them) are being or have been recycled.Specify CHUNK to indicate the number of server group members to recycle in parallel. Refer to CHUNK for further details. If the systems in a Server group all have the same preference value, the system that is active after a rolling recycle has completed may not be the same one as before the rolling recycle. Thus, triggering a rolling recycle always results in a move occurring. If you set the preference of the original system more than 250 points higher than that of any other system, the rolling recycle is followed by a second move to return the application to that system. This leads to an increase in the application downtime.Note:
- Preference values do not influence the order in which resources are recycled. The resources of the group are recycled from last to first as they are displayed in the list of group members.
- If rolling recycle is used for a server group, the Prepare Move option specified in the policy controls the group's high availability. If Prepare Move is YES, a member will not be stopped until the started replacement is available. If Prepare Move is NO, it might lead to a temporary outage as some members might be stopped faster than recycled members become available. To avoid this situation, either set Prepare Move to YES or force it to YES on rolling recycle. For more information, see Defining Automation Policy.
- CANCEL
- Causes any rolling recycles among the selected groups to be canceled.
- SYSTEMS
- Is the list of systems to be excluded or included. If no groups are specified, all application
groups with resources in these systems are affected.
This parameter must be specified for INCLUDE, AVOID, and EXCLUDE actions.
- GROUPTYPE
- Specifies the type (nature) of the resource group. More than one value can be specified.
- CHUNK
- Indicates the number of SERVER group members to recycle in parallel. Note: SA z/OS adjusts the chunk size to ensure that at least one group member is active at any time to avoid an application outage. This is the case when the chunk size is greater or equal to the number of active group members. However, the chunk size is only adjusted when it is possible in a meaningful way. For instance, when CHUNK=1 is specified and there is only one active SERVER group member, there is no possible adjustment and this last member will be recycled.
- AVTGT (server group only)
- Specifies the availability target that is to be set for the group. It determines the number of
group members that should be made available when the group has to be available.
You can specify the following values:
- An absolute positive integer.
- A relative positive or negative integer, for example,
AVTGT=+1, orAVTGT=-2. - *, which resets the AVTGT parameter to the value that is specified in the policy database.
This parameter can be specified for an ADJUST action.
For details of how the AVTGT changes apply, see SATTGT below.
- SATTGT (server group only)
- Specifies the number of members in the group that must be active before the automation manager treats the group as being in a satisfactory state.
You can specify the following values:
- An absolute positive integer.
- A relative positive or negative integer, for example,
SATTGT=+1, orSATTGT=-2. - *, which resets the SATTGT parameter to the value that is specified in the policy database.
This parameter can be specified for an ADJUST action.
Changes to target values, as set by the AVTGT and SATTGT parameters, apply in the following manner:- The Availability and Satisfactory Target values in the automation policy are not affected.
- An adjustment value is calculated that, when applied to the corresponding target value in the automation policy, produces the "result" value. (See also "RESOURCES Policy Item" in IBM Z® System Automation Defining Automation Policy).
- The "result" target value is then used by the automation when a target value is required.
- The adjustment value, rather than the "result" value, is preserved when performing an automation manager HOT restart or an INGAMS REFRESH if the target is defined as *ALL in the automation policy. Alternatively, if the target value is explicitly defined to be numerically equal to the "Number of selected Resources" in the automation policy, the "result" value is preserved rather than the adjustment.
- MEMBERS
- Specifies a list of group members that the preference value should
be set for. Wildcards may not be used.
This parameter may only be specified on an ADJUST action.
- PREF (model 1 only)
- Specifies a preference value that is to be used for each specified member. The number of values
specified should be the same as the number of members specified. Each preference is an integer value
that replaces the member's current preference value. You can also specify *, which resets the PREF
parameter to the value that is specified in the policy database.
Preference values are used to determine which members in the group are selected to make the group active.
This parameter may only be specified on an ADJUST action when a list of members has been specified.
Changes to preference values, as set by the PREF parameter, apply in the following manner:
- The preference value in the automation policy is not affected.
- An adjustment value is calculated that, when applied to the preference value in the automation policy, produces the "result" value.
- The "result" preference value is then used by the automation when a preference value is required.
- The adjustment value, rather than the "result" value, is preserved when performing an
automation manager HOT restart or an INGAMS REFRESH, but is
lost during WARM and COLD restarts.
If an adjustment was made via the INGGROUP or INGMOVE command and to the base preference via the customization dialogs, the current effective preference and the new base preference will be taken to calculate a new adjusted preference. As a result, the old effective preference will be preserved.
- ROLE (model 2 only)
- Specifies a new role that is to be used for the corresponding member. Or, resets the role of the
corresponding member to the role defined in the policy.
Roles are used to determine which members in the group are selected to make the group active.
The following roles can be specified:- O
- Assign the member the role of an OPERATOR member.
- P[n]
- Assign the member the role of a PRIMARY member with the position "n". "n" ranges from 1 to 99 and defaults to 1 when omitted. (SERVER group only)
- R
- Reset the role to the role defined in the policy.
Changes to roles, as set by the ROLES parameter, apply in the following manner:- The role value in the automation policy is not affected.
- A new role will be used by the group for member actions.
- The member role of OPERATOR will cause the group to stop the member and not use it for recovery purposes.
- The override value is preserved when performing an automation manager HOT restart or an INGAMS REFRESH, but is lost during WARM and COLD restarts.
- WAIT
- Specifies whether or not to wait until the request is complete.
The default is YES.
nnn is the number of seconds to wait before giving up and reporting that a timeout has occurred. The maximum time interval is 999 seconds.
- TARGET
- For information on the TARGET parameter, see TARGET Parameter.
- OUTMODE
- For information on the OUTMODE parameter, see OUTMODE Parameter.
- FDBK (introduced in OA59461)
-
The feedback parameter will send a message after a notification condition has been met. If the observed status of the resource matches the expected status, the message ING300I is issued. Otherwise, if the specified wait time max_time has been exceeded, the message ING301I will be returned.
- MSG
- The command process does not wait until a notification condition has been met. Either the
originator of the command determined by the NetView OPID(S) function or the user specified with the
userid option will receive a message.
- userid
- Identifies the NetView user ID of the person to be notified if different to the originating user.
- Use the following values to specify when to issue the message:
- G
- Issue the message only when the resource has reached its expected status.
- F
- Issue the message only if the resource did not reach its expected state in the specified time interval.
- B
- Issue the message in all cases.
- WAIT
- The command process waits until a notification condition has been met and a message will be directly returned to the originator of the command. Note that the WAIT option is rejected when the INGGROUP command executes on a work operator.
- max_time
- The time interval in NetView format (mm:ss, :ss, mm or hh:mm:ss) that SA z/OS will wait. If the specified resource has not reached the expected state, the command is considered to have failed and the operation is posted in error.
- exp_status
- The observed status that the resource should be in to consider command
processing to be complete. The status can be abbreviated, for example, AV for Available. More than
one status can be specified and separated by a blank. Here is a list of possible
Observed Status values and their shortest possible abbreviations: AVAILABLE (A), UNKNOWN (U),
SYSGONE (SY), SOFTDOWN (SO), HARDDOWN (H), STARTING (STAR), DEGRADED (D), STOPPING (STO), PROBLEM
(P), WASAVAILABLE (W), and STANDBY (STAN).
If a resource is of type APG with Status Determination flag CSONLY and the AOF_AAO_FDBK_HONOR_CS global variable is set to '1', then the command processing will be considered complete when the resource's compound status is SATISFACTORY, and its observed status reaches the expected status or ends up in STARTING (for a start action), or STOPPING/DEGRADED (both for a stop action).
Restrictions and Limitations
None.
Security Considerations
The INGGROUP command supports resource level security. If turned on, the following profiles in class SYSAUTO are checked:
| Profile | Authority | Condition |
|---|---|---|
| AGT.sysplex.xcfgrp.RES.resname.restype[.ressys] | UPDATE | When action option is RECYCLE, CANCEL, RESET, DEFAULT, EXCLUDE, AVOID, or INCLUDE. |
| CONTROL | When action option is ACTIVATE, PACIFY, ADJUST, BOX, UNBOX, MOVE, or PREPMOVE. |
Usage other than listed in the table does not cause a resource level security check. If multiple resources are affected, multiple resources are checked. The request is carried out or rejected as a whole.
For further details, refer to IBM Z System Automation Planning and Installation.
Usage
The INGGROUP command operates sysplexwide. For an overview, see Overview of Commands that Operate Sysplexwide.
Automation policy overrides that have been entered using the INGGROUP command are preserved when performing an automation manager HOT restart and an INGAMS REFRESH, but are lost during WARM and COLD restarts.
Example 1
inggroup, a panel similar to Figure 1
is displayed. INGKYGRA SA z/OS - Command Dialogs
Domain ID = IPUFA ---------- INGGROUP ---------- Date = 09/17/19
Operator ID = NETOP1 Sysplex = AOCAPLEX Time = 14:52:51
Specify or revise the following data:
Target => System name, domain id or sysplex name
Action => EXCLUDE-AVOID-INCLUDE or ACTIVATE-PACIFY or
MEMBERS or BOX-UNBOX (model 2 only)
RESET-DEFAULT or OVERRIDES or POLICY or RECYCLE-CANCEL
Opt.Parms =>
Group(s) =>
System(s) =>
Command ===>
PF1=Help PF2=End PF3=Return PF4=Members PF6=Roll
PF10=GO PF12=RetrieveThis panel allows you to change the policy of application groups. You may specify:
- The target sysplex for the command with the Target field. If omitted, this defaults to the local system or sysplex. Specify the system name only when viewing or changing the policy of an application group that is not part of the local sysplex.
- The policy change that you want to make with the Action field. See the online help for details about the policy items that you can change.
- Next, you must specify in the Group(s) field either the name of the
target group or a set of templates that will match one or more groups. All policy items work with a
list of group name templates, and apply to all Move and Server groups that match those names.
Although applying a policy to a Basic group is not an error, it will not achieve anything either.
Note: A group name of
xxxxwill be automatically expanded intoxxxx/APG/*orxxxx/APG, except for ADJUST and MEMBERS actions. - For the Exclude, Avoid, and Include policy items, you can specify a list of names of systems that the policy is to be set for. Specify a question mark (?) to see the list of systems within the sysplex.
After entering the appropriate information in the fields for the policy item that you want to change, press PF10 or Enter to make your changes active and proceed with the action.
You can press PF4 to display the members detail panel (Figure 3), where you can fine-tune the group by changing the preferences
(Model 1) or roles (Model 2) of its individual members. For Model 2 groups, the panel also allows to
trigger Move and Prepare Move actions for individual members. If you do not specify a group on
the main INGGROUP panel, a selection panel (Figure 2) displays all
the groups that are currently available, with the message Multiple instances found for
*/APG. Select one application group and press Enter.
AOFKSEL4 SA z/OS - Command Dialogs Line 1 of 160
Domain ID = IPUFA ---------- INGGROUP ---------- Date = 07/11/19
Operator ID = NETOP1 Time = 15:54:24
Multiple instances found for */APG
Select one item to be processed, then press ENTER.
Sel Name Type System Description
--- ----------- ---- -------- ------------------------------------------
AMAPG APG APG for Automation Managers
BASE_APPL APG AOCA Base z/OS Applications
BASE_APPL APG AOCB Base z/OS Applications
BASE_APPL APG AOCC Base z/OS Applications
BASE_APPL APG AOCD Base z/OS Applications
BASE_SUPP APG AOCA Base z/OS Support Functions
BASE_SUPP APG AOCB Base z/OS Support Functions
BASE_SUPP APG AOCC Base z/OS Support Functions
BASE_SUPP APG AOCD Base z/OS Support Functions
BASE_SYS APG AOCA Base z/OS Components
BASE_SYS APG AOCB Base z/OS Components
Command ===>
PF1=Help PF2=End PF3=Return
PF6=Roll PF8=Forward PF12=RetrieveThe members detail panel, as shown in Figure 3, allows you to change the preference policy values for the members of Move and Server groups of model 1.
INGKYGRB SA z/OS - Command Dialogs Line 1 of 3
INGKYGRB SA z/OS - Command Dialogs Line 1 of 4
Domain Id . : IPUFD ------------ INGGROUP ------------ Date . . : 07/11/19
Operator Id : OPER Sysplex = AOCAPLEX Time . . : 10:23:36
Group . . . : PPREFD/APG Nature / Model . . . : Server / 1
Description : Server Battery with Backups
Excluded . . :
Avoided . . :
Mode / Suspend : Normal / Passive . . . . . . : NO
Rolling Recycle : None
Target Policy Adjust Result
------------ ------ ------ ------
Availability 3 0 3
Satisfactory 0
Name Type System Pref Adj Result Avl Eff Stat Act Sus
----------- ---- -------- ---- ----- ------ --- ---- ---- --- ---
PPREFD APL AOCA 700 0 700 Yes 950 Sel -- --
PPREFD APL AOCB 700 0 700 Yes 950 Sel -- --
PPREFD APL AOCC 700 0 700 Nst 0 Uns -- --
PPREFD APL AOCD 300 0 300 No 0 Rcv -- --
Command ===>
PF1=Help PF2=End PF3=Return PF6=Roll
PF9=Refresh PF10=GO PF11=Reset PF12=RetrieveOn this panel you can change the values in the Result field to change the availability target for that server group. Also, in the Result column you can change the preference value for that member. The effective preference value is shown in the Eff column. (Preference value changes are also possible for move groups).
Changes to preference values for members, as set with the Result field are implemented in the following manner:
- The preference value in the automation policy is not affected.
- An adjustment value is calculated, which produces the Result value, when it was applied to the preference value in the automation policy.
- The Result preference value is used by the automation when a preference value is required.
- The adjustment value, not the Result, is preserved across automation manager HOT restart and across INGAMS REFRESH, but is lost during WARM and COLD restarts.
To make your changes active, press PF10. To reset the initial settings, press PF11.
The action taken after PF10 is pressed may differ from the assumed or proposed action displayed in the action column of panel INGKYGRB. This is because the assumed or proposed action is calculated by processing the group's resources in alphanumeric sequence, while the actual action performed is calculated by the automation manager that processes the group's resources in a random sequence.
For further details about this panel and how to use it, and sample preference scenarios, see the online help.
INGGROUP group1 TSO/APG ACTION=EXCLUDEExample 2
The following example shows how to use INGGROUP ACTION=DATA in a REXX program to parse output data.
sp='00'x /*set separator character*/
resource_name = '...' /*specify the resource name(s)*/
...
'PIPE NETV INGGROUP ' resource_name ' action=data', /*call INGGROUP ACTION=DATA*/
' | STEM output. ' /*store result into output. stem*/
Do i=1 to output.0 /*for each line parse token with separator*/
Parse Var output.i rname (sp) gdata (sp) o_stat (sp),
d_st (sp) a_st (sp) a_fl (sp) ,
h_fl (sp) desc (sp) st_type (sp) .
say rname ': ' desc /*display resource name and description*/
End