INGAMS

Purpose

The INGAMS command displays details about currently registered automation managers and automation agents, and lets you change the operation mode (PAM or SAM) of the automation managers. Note that it is only possible to make a secondary automation manager a primary one, not vice versa.

INGAMS lets you dynamically refresh the definition data for an automation manager and the corresponding ACFs with the contents of a specified configuration data set. The consistency of the configuration data as used by the automation agent and the associated ACFs is maintained. Data that would cause resources to contain conflicting definitions is rejected during configuration refresh with an appropriate message.

You can also use the INGAMS command to initiate and view diagnostic information for the primary automation manager.

Syntax

Read syntax diagramSkip visual syntax diagram INGAMS STATUSXSTATUSSETnameMODE=PAMSTART=HOTSTART=WARMCOLDDETAILSnameDIAGREQ=SNAPSHOTDSN= dsnameSTARTRECDSN= dsnameSTOPRECSTATSReport optionSTARTMONINTERVAL= nnnSTOPMONDISABLEENABLESUSPENDSYSTEMS=(*all| system1 system2 …)RESUMESYSTEMS=(*all| system1 system2 …)REFRESHRefresh optionsTARGET=system_namedomain_idsaplex_nameOUTDSN= dsnameOUTMODE=LINEAUTONETLOG
Report option
Read syntax diagramSkip visual syntax diagramSTATS=SUMMARYSTATS=DETAIL
Refresh options
Read syntax diagramSkip visual syntax diagramCFG=dsnamedsname(generation)**(generation)SUSPENDFILE=NOSUSPENDFORCESUSPEND

Parameters

STATUS
Displays a list of all automation manager and automation agents in the sysplex that are registered to the same XCF group.
XSTATUS
Displays a list of all automation manager and automation agents in the sysplex that are registered to the same XCF group denoted by the PLEXID specification for the local automation agent.
SET
Changes the operation mode of the specified automation manager.
name
The name of the automation manager.
MODE
Specifies the mode of operation, this can be:
PAM
Primary automation manager
START
Specifies how an automation manager switch should be carried out. Valid values are HOT, WARM, or COLD.
DETAILS
Displays detailed information about the specified automation manager.
DIAG
Displays the diagnostic panel where you can either request that a snapshot of the current state image queue be taken or that recording of the inbound work items be started or stopped. The output file must be a sequential data set.
REQ
Is the function to be performed. It can be one of the following:
SNAPSHOT
Write a snapshot of automation manager data.
STARTREC
Start recording.
STOPREC
Stop recording.
STATS
Display work item statistics.
STARTMON
Activate work item queue monitoring.
STOPMON
Stop work item queue monitoring.
INTERVAL
The time period in seconds between two monitoring cycles. The value can be in the range of 10–999.
STATS
Specify the type of work item statistics report to generate: A SUMMARY (the default) or a DETAIL report, which shows details about all tasks.
DISABLE
Causes the automation manager to stop writing to the takeover file. It also deallocates the takeover file from the automation manager. This is only necessary when performing repair operations on the takeover file.
ENABLE
Causes the automation manager to start updating the takeover file for each work item processed.
SUSPEND
Tells the automation manager to suspend sending orders to start or stop resources that are hosted by the systems that are specified with the SYSTEMS parameter.
RESUME
Tells the automation manager to resume sending orders to start or stop resources that are hosted by the suspended systems that are specified with the SYSTEMS parameter.
SYSTEMS
The parameter to define the systems that the sending of orders is suspended or resumed for. If you specify multiple systems, they must be enclosed in parentheses.

Alternatively, you can use *all to specify all the systems that are controlled by the automation manager.

REFRESH
Updates an automation manager with the definition data that is stored in the specified configuration file. This also reloads the appropriate ACFs on the active automation agents.
Notes:
  1. INGAMS REFRESH does not delete global variables that are associated with ENTRY TYPEs that were deleted from the policy database before the last build if those ENTRY TYPEs are not associated with a subsystem. However, if a keyword/value is removed from the ENTRY TYPE, this is a change to the E-T. Therefore, INGAMS REFRESH rebuilds the E-T and the deleted keyword/value pair is removed from the global variables.

    All deleted entry types and their associated global variables are reset during the next SA z/OS® COLD start or during ACF COLD processing.

  2. The configuration refresh on the automation agent runs parallel to other activities. Thus any start/stop orders may be processed before the new data is loaded.
  3. Issuing an INGAMS REFRESH command while an agent is SUSPENDED due to an Automation Manager takeover will interfere with the still ongoing load process and will result in a delay for the processing of the INGAMS REFRESH command. It is recommended that you wait until all agents are in the READY status before issuing the INGAMS REFRESH command.
CFG
This is the name of a partitioned data set that holds the configuration file member and the ACF fragments. The name can be a fully qualified data set name or generation data group (GDG) name. You can use an asterisk (*) to indicate a reload of the configuration file that was previously used or a different generation of the GDG that was previously used.
dsname
Specifies a data set name. If you specify a GDG base data set name, the latest generation (0) is used.
dsname (generation)
Specifies the name of a generation data group (GDG) and the generation number (zero or a negative signed integer) of a generation data set within the GDG, for example, *(-2).
SUSPENDFILE
Specifies how syntax errors in the suspend file are handled.
NOSUSPEND
Suspend file processing is entirely ignored.
FORCESUSPEND
Only the lines with syntax errors are ignored; all other lines are processed.

If FORCESUSPEND is specified, or neither FORCESUSPEND nor NOSUSPEND is specified, the INGAMS REFRESH command will process the suspend file only if the configuration file has been changed as well. For example, if you have added, deleted, or modified a resources.

DSN
Lets you specify the name of the data set that contains the snapshot or work item recording data. You can only use a sequential file.

The output data set must be pre-allocated with a RECFM FB and LREC 80. It must be allocated as a single volume data set, without candidate volumes for further expansion.

TARGET
For information on the TARGET parameter, see TARGET Parameter.
OUTDSN
For information on the OUTDSN parameter, see OUTDSN Parameter.
OUTMODE
For information on the OUTMODE parameter, see OUTMODE Parameter.

Restrictions and Limitations

None.

Security Considerations

The INGAMS command supports resource level security. If turned on, the following profiles in class SYSAUTO are checked:
Profile Authority Condition
AGT.sysplex.xcfgrp.RES._CONFIG UPDATE When function option is REFRESH
AGT.sysplex.xcfgrp.RES._MANAGER UPDATE When function option is SET
AGT.sysplex.xcfgrp.RES._MANAGER CONTROL When function option is DISABLE, ENABLE, SUSPEND or RESUME
AGT.sysplex.xcfgrp.RES._MANAGER.DIAG UPDATE When function option is DIAG for all function other than STATS (other than REQ=STATS)

Usage other than listed in the above tables does not cause a resource level security check. For further details, refer to IBM Z System Automation Planning and Installation

Usage

The INGAMS command operates sysplexwide. For an overview see Overview of Commands that Operate Sysplexwide.

When using the DIAG parameter make sure that the data set for writing a snapshot or starting recording is online and free before issuing a command. The data set must be used exclusively by the automation manager (DISP=OLD) for making snapshots or recording.

Examples

If you enter ingams a panel similar to Figure 1 is displayed.
Figure 1. INGAMS Command Dialog Panel
 INGKYAM0                  SA z/OS  - Command Dialogs      Line  1    of 4 
 Domain ID   = IPUND     ---------- INGAMS   ----------    Date = 07/17/19 
 Operator ID = NETOP1          Sysplex = AOCAPLEX          Time = 16:33:35 
                                                                    
 Cmd:  A Manage       B Show Details  C Refresh Configuration  D Diagnostic  
                                                                          
 CMD System   Member    Role  Status     Sysplex  XCF Group Release Comm E2E 
 --- -------- --------- ----- ---------- -------- --------- ------- ---- --- 
     AOCA     AOCA$$$$2 SAM   READY      AOCAPLEX INGXSGX0  V4R2M0  XCF
     AOCA     AOCA      AGENT READY      AOCAPLEX INGXSGX0  V4R2M0  XCF   
     AOCB     AOCB$$$$1 PAM   READY      AOCAPLEX INGXSGX0  V4R2M0  XCF  YES
     AOCB     AOCB      AGENT READY      AOCAPLEX INGXSGX0  V4R2M0  XCF     
     AOCC     AOCC      AGENT READY      AOCAPLEX INGXSGX0  V4R2M0  XCF  YES
     AOCD     AOCD      AGENT READY      AOCAPLEX INGXSGX0  V4R2M0  XCF 
                                       

 Command ===>             
  PF1=Help   PF2=End    PF3=Return                                 PF6=Roll     
                        PF9=Refresh   PF10=Previous   PF11=Next   PF12=Retrieve
  • The Cmd field allows you to specify command codes to initiate various activities related to automation managers. To use one of the command codes shown, type the appropriate letter next to the resource name, and press Enter. The amount of data displayed depends on the screen size. Press PF10/PF11 for horizontal scrolling. The following command codes are available:
    A
    Displays the automation manager menu panel allowing you to:
    • Modify the automation manager operation mode. You can only change a secondary automation manager to a primary one.
    • Enable and disable takeover file processing
    • Suspend or resume the sending of orders from the automation manager to the automation agent on the system specified. This is useful if, for example, you have erroneously issued a command to shut down a system or sysplex. In such a situation, you now have the chance to rectify the error.

      You should also note that while the automation manager is suspended for a particular system, it continues to respond to queries (such as INGLIST or INGVOTE) and any automation action for other systems within its scope.

    See Controlling the Secondary Automation Manager Functions.
    B
    Displays additional information about the automation manager or automation agent. For an automation agent, the DISPSYS command is issued to show details about the agent and the environment the agent runs on. See Showing Details about the Automation Manager.
    C
    Displays the refresh configuration data panel where you enter the name of the data set that contains the automation manager configuration members. This is then used to update the definition data for the automation manager in real time and to reload the corresponding automation configuration files for the active automation agents. This command thus maintains the consistency of the configuration data that is used by the automation agent and its automation configuration files. See Refreshing the Configuration Data Sysplexwide.
    D
    Displays the utility panel where you can perform the following diagnostic functions:
    • Write snapshot.
    • Start or stop recording.
    • Display work item statistics
    • Start or stop monitoring of the work item queue.

    For further information, see Diagnostic Functions and How to Use the Diagnostic Option of INGAMS in IBM Z System Automation User's Guide.

  • The System field shows the name of the system where an instance of the automation manager or automation agent runs.
  • The Member field shows the name of the agent or manager. The name must be unique within the XCF group. The member name for an automation manager is automatically generated and consists of the z/OS system name plus a 1-character suffix running from 1 to 9. The z/OS system name is padded with '$' to create an 8-character system name before appending the suffix.
    Note: The member name of an automation agent is equal to the z/OS system name.
  • The Role field shows the type of the system. It can be one of the following:
    AGENT
    An automation agent.
    PAM
    The primary automation manager.
    SAM
    The secondary automation manager. There can be more than one.
  • The Status field shows the status of the member. It can be one of the following:
    COMM
    Is the type of communication being used between the automation manager and the automation agent.
    NOT READY
    The automation agent or manager is initializing.
    PENDING
    The automation manager is in the process of initializing as a primary automation manager (PAM).
    READY
    The member is completely initialized.
    REFRESH
    The automation manager is performing a configuration refresh.
    SELECTED
    The automation manager is selected to become the next primary automation manager (PAM).
    STOPPING
    The automation manager is terminating.
    SUSPENDED
    The automation agent has been placed in suspended mode.
  • The Sysplex field shows the name of the sysplex.
  • The XCF-Group field shows the name of the associated XCF-Group.
  • The Release field shows the SA z/OS Version and Release of the automation manager or automation agent.
  • The Comm field shows the type of communication in use between the automation manager and the automation agent.
  • The E2E field shows that the E2E adapter is running on this system, if the system is an AGENT and this field contains YES. If the system is a PAM and this field contains YES, it shows that the PAM is also the end-to-end manager.
  • The Runmode field shows the Runmode assigned to this system (agents only).
  • The Pref field shows the preference value assigned to various automation instances.
  • The SMF ID field shows the SMF ID assigned to the system.
  • The Primary FP field shows the name of the primary focal point defined to the system.
  • The Backup FP field shows the name of the backup focal point defined to the system.

Values for the columns SMF ID, Primary FP and Backup FP are only available if the agent is a member of the extended XCF communication group.

The FIND/RFIND/SORT commands are supported. See Varying the Format of the Command Output for information.