INGREQ

Purpose

The INGREQ command lets you:

Initiate the shutdown process for one or more resources
Initiate the startup process for one or more resources
Cancel a request that was previously made for the specified resource

Syntax

To start up or shut down resources:

Startup parms

Shutdown parms

To cancel a request:

Feedback option

Parameters

NETVASIS

Prefix the INGREQ command with NETVASIS if you want to pass the description text in lower or mixed case.

resource

Specifies the name of the resource to be processed. The format is name[/type[/system]]. Resources of type DMN are not supported.

Wildcards are supported. In fullscreen mode, if more than one resource matches the wildcard specification, a selection panel is displayed. In line mode, if more than one resource matches the wildcard specification and MULT=YES is specified, all selected resources are processed. Multiple resource specification in line mode without MULT=YES causes an error message to be displayed.

To shut down all resources for a system, specify name/SYG/name, where name is the system name. Alternatively, you can specify ALL.

Note: You need not specify the full name of the resource. This applies to the system as well as to the type. If the resource name is unique within the name space of the automation manager, the system name needs not be specified. If the resource name is unique within the appropriate types, the type needs not be specified. A valid resource name could be, for example, CICSPROD.

REQ

Specifies the request to be carried out. It can be either START or STOP. Alternatively you can use UP or DOWN.

Specify CANCEL if you want to cancel a request.

PRI

Specifies the priority given to the request. It can be:

FORCE: Takes precedence over requests posted with HIGH priority, for example, INGREQ=START PRI=FORCE overrules an INGREQ=STOP PRI=HIGH request.
HIGH: High priority.
LOW: Low priority. This is the default.

EXPIRE

Specifies the expiry date and time of the request. The request is automatically removed when it expires. The date format is yyyy-mm-dd; an asterisk (*) is used as today's date. The time format is hh:mm.

Alternatively, you can specify a relative time, for example, +04:00. The relative time will be automatically converted into the absolute date/time. The maximum relative time interval is 24:00 hours.

TIMEOUT

Specifies the interval used to check whether the request has been successfully completed. Either a message is issued, or the request is canceled if the request has not been satisfied after that time. The format is mm.

MSG: Specifies that a message should be issued telling the notify operator that the request was not satisfied within the expected time interval. The default is to issue a message.
CANCEL: Specifies that the request should be canceled.

JOB

Indicates the specified resource is a job name. The job name can contain a wildcard.

REMOVE

Indicates the condition when the request is automatically removed, regardless of whether the request is satisfied or not. If the specified condition matches the observed status of the resource, the request is deleted.

AVAILABLE: When starting a resource and specifying REMOVE=AVAILABLE, this causes the request to be removed from the system as soon as the resource becomes available.
DEGRADED: As soon as the observed status of the resource becomes DEGRADED, the start request is removed. Thus there will be no requests outstanding for the resource and an INGREQ ALL will go through even with low priority.
SYSGONE: If the system where the automation agent runs leaves the sysplex, the observed status of all resources running on that system becomes SYSGONE.
UNKNOWN: If the automation agent stops, the observed status of all resources controlled by the automation agent becomes UNKNOWN.

Alternatively you can specify an asterisk (*) or NO to reset the installation-defined default.

OVERRIDE

Specifies the overrides to be considered for the request. These can be one or more of the following:

NO: Specifies that no override is done. For example, a resource will not be started unless its startup flag is set on and its trigger, if used, is satisfied. This is the default.
ALL: Sets the DPY, FLG, STS, TRG and SUS flags to on. For startup, it means that the resource is made available regardless of the state of the start dependencies defined for the resource, the automation flag settings, its observed status, its trigger setting, or the suspend requests on the resource. For shutdown, it means that the resource is made unavailable regardless of the state of the stop dependencies defined for the resource, its automation flag settings, its observed status, its trigger setting, or the suspend requests on the resource.
DPY: Causes the status of the relevant START/STOP dependencies that are defined for the resource to be ignored.
Note: This parameter should only be used with STOP SCOPE=ONLY.
FLG: The appropriate automation flags will be ignored for the resource.
STS: The current observed status of the resource is ignored by the agent during INGREQ precheck processing. Override STS does not affect automation manager processing. Therefore, the automation manager may still reject the request after the agent has forwarded it to the automation manager.
TRG: The current trigger settings will be ignored when determining whether or not the resource can be started or stopped.
SUS: If there are any suspend requests on the resource, these requests are ignored and the start or stop process is executed.

PRECHECK

Specifies whether or not the startup or shutdown process should pre-validate any actions before actually performing them. The value can be:

YES: Validation is performed for the entry resources. This is the default.
NO: Validation is not performed before the command is issued.

The following validation is done for each resource that is to be affected by the INGREQ request:

START or STOP ability, depending on current status
The automation manager will not order the start of a resource that is in a Harddown status. A check is performed to make sure that the resource is not in STOPPED, BROKEN, or CTLDOWN status. The resource is also checked to verify that it is not currently involved in an automated shutdown. For a stop request, a check is performed to verify that the resource is not currently involved in an automated startup.
Automation flag checks, depending on the request type
If the global automation flag is on, for a start request, the initstart flag is checked when the resource is currently in DOWN status. For any other down state, the restart flag is checked.

For a stop request, the terminate flag is checked.
Existence of start or stop commands
A check is performed to make sure that the definitions for appropriate start or stop commands exist.

These checks are made on each automation agent that hosts a specific resource before any automation manager involvement in the request. Any failure that is detected during the precheck phase results in an INGREQ request failure. This is indicated by a nonzero return code and a relevant error message that is issued and delivered as set by the OUTMODE parameter.

VERIFY

Specifies whether the startup or shutdown process should be verified. The following specifications are valid:

YES: Depending on the NetView task type that the INGREQ command is running on, the verification is either displayed on a fullscreen panel or, in line mode, shown on the console. The latter is also done when OUTMODE=LINE is coded.
WTOR: The list of affected resources is displayed before the startup or shutdown begins. The operator is prompted to verify the list via WTOR.
NO: No verification is performed. VERIFY is set to NO for unattended tasks. Otherwise it is set to YES.

The default depends on the type of task that the INGREQ command runs on.

SOURCE

Specifies the originator of the request. The default is OPERATOR for an OST and AUTOOPS for an autotask. When REQ=CANCEL, this parameter is used as a filter. Only those requests from the named source are canceled. Wildcards are supported, for example, OP*. An asterisk (*) matches a string of arbitrary length and a percentage sign (%) matches a single character.

WAIT

Specifies whether or not to wait until the request is complete. The default is YES.

The variable 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.

CMT

Specifies descriptive information about the request. The maximum length is 120 characters. If the text contains embedded blanks, it must be enclosed in quotation marks or parentheses.

TARGET

For information on the TARGET parameter, see TARGET Parameter.

OUTMODE

For information on the OUTMODE parameter, see OUTMODE Parameter.

APPLPARMS

The content of APPLPARMS is put into the &APPLPARMS variable.

MULT

Specifies that more than one resource will be accepted when running in line mode, if the resource wildcard specification results in multiple resources.

SCOPE

Specifies whether the startup or shutdown affects a resource or its descendants, or both. Valid options are:

ONLY: Specifies that only the specified resource is started or stopped. This is the default for startup.
ALL: Specifies that the resource and its descendants are started or stopped. This is the default for shutdown.
CHILDREN (shutdown only): Specifies that only the descendants of the resource are stopped.

TYPE

Specifies the type of the startup or shutdown. Each type must be defined in the policy database. Valid options are:

NORM (startup or shutdown): Specifies a normal startup or shutdown. This is the default.
IMMED (shutdown only): Specifies an immediate shutdown.
FORCE (shutdown only): Specifies a forced shutdown.
user (startup only): Specifies a user-defined startup type.

Note: If no startup commands are defined for the specified start type, the startup commands for start type NORM are issued.

If the specified stop type is not defined in the policy when shutting down the resource, SA z/OS uses the next lower stop type instead.

The value specified here will be overridden by the INGSET STARTTYPE/STOPTYPE value if previously specified. However, a stop type of FORCE, wherever specified, will always be honored.

Use the VERIFY option to view the TYPE value that will be used for this request.

Once a shutdown has got to a PROBLEM or DENIED state, you can submit another shutdown request against the resource, specifying a different shutdown type or override parameters or both.

If you want to escalate the shutdown of a child subsystem, you can issue the INGREQ directly against it, but you must use a higher priority than the shutdown request against the parent was made with.

RESTART (shutdown only)

Specifies whether the resource should be restarted automatically when it has been shut down completely. Valid options are:

NO: Specifies that no restart is performed. This is the default.
YES: Specifies that a restart is performed.

INTERRUPT (shutdown only)

Specifies whether or not a request to shut down a resource should interrupt the startup phase of the resource:

NO: If the resource is starting, the automation manager waits for the resource's UP message before proceeding with the shutdown. This is the default.
YES: The automation manager interrupts the startup process as soon as this stop request is submitted.

BOOST (shutdown only)

Specifies whether or not the System Recovery Boost should be enabled upon system shutdown automatically. This parameter is used only for system shutdowns and is ignored for shutdown of any other resource.

YES: If a system is shut down, System Recovery Boost is enabled automatically. This is the default.
NO: If a system is shut down, it explicitly opts out from enabling System Recovery Boost, regardless of the setting of the BOOST system parameter in IEASYSxx.

FDBK

Specifies the feedback parameter that causes the final result of the command to be reported back to the designated instance.

MSG

Causes message signaling of the successful or unsuccessful completion of the command to be performed.

The message is sent back to the originator of the command. The originator is determined by the NetView OPID(S) function unless the user ID is specified. Depending on the status, either message ING300I or ING301I is issued. The message text contains the command that was processed successfully or failed.

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

To wait for the completion of the command (denoted by the max_time parameter). Note that the WAIT option is rejected when the INGREQ 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).

Restrictions and Limitations

To use the INGREQ command system operations must be initialized.

The FDBK parameter will only monitor resources within the local sysplex.

Security Considerations

The INGREQ 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	Unless authority is CONTROL
AGT.`sysplex.xcfgrp` .RES`.resname.restype[.ressys]`	CONTROL	When SCOPE, OVERRIDE, or INTERRUPT is used with a value other than the default (IBM supplied or installation default)

If multiple resources are affected, multiple profiles are checked. START and STOP requests are carried out or rejected as a whole. CANCEL requests are processed individually.

For further details, refer to IBM System Automation for z/OS Planning and Installation.

Usage

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

By default, System Recovery Boost is enabled during shutdown of a system when the hardware and software prerequisites are met and the BOOST system parameter is not set to NONE. For further details, refer to IBM System Automation for z/OS Planning and Installation.

Examples

If you enter INGREQ a panel similar to Figure 1 is displayed.

Figure 1. INGREQ Command Dialog Panel 1

 INGKYRU0                  SA z/OS  - Command Dialogs      Page   1 of 2        
 Domain ID   = IPSFP     ---------- INGREQ   ----------    Date = 04/27/06      
 Operator ID = NETOP1                                      Time = 18:52:41      
                                                                                
   Resource    =>  CICS/APL/KEY4                      format: name/type/system  
   Target      =>              System name, domain ID or sysplex name           
                                                                                
   Request     =>  START       Request type (START/UP, STOP/DOWN or CANCEL)     
   Type        =>  NORM        Type of processing (NORM/IMMED/FORCE/user) or ?  
   Scope       =>              Request scope (ONLY/CHILDREN/ALL)                
   Priority    =>  LOW         Priority of request (FORCE/HIGH/LOW)             
   Expire      =>             ,         Expiration date(yyyy-mm-dd), time(hh:mm) 
   AutoRemove  =>                                           - see help for list 
   Restart     =>  NO          Restart resource after shutdown (YES/NO)         
   Override    =>  NO                        (ALL/NO/TRG/FLG/DPY/STS/SUS)  
   Verify      =>  YES         Check affected resources (YES/NO/WTOR)           
   Comment     =>                                                               
                                                                                
   Appl Parms  =>  ,CN                                                          
                                                                                
                                                                                
 Command ===>                                                                   
    PF1=Help     PF2=End      PF3=Return                           PF6=Roll     
                                                     PF11=Next    PF12=Retrieve

The Resource field shows the name of the resource to be processed. The format is name/type[/system]. Resources of type DMN are not supported. Wildcard is supported.
The Target field shows the name of the system (system name, domain ID, or sysplex name) that the command should be routed to. Specifying this is only necessary if the resources are not part of the local sysplex.
The Request field shows the request to be carried out. This is either START or STOP. Alternatively you can use UP or DOWN. To remove a previously made request from the same source specify CANCEL.
The Type field shows the type of the startup or shutdown. Valid shutdown types are NORM, IMMED and FORCE as well as any other type defined in the policy database for the resource. Specify a question mark (?) to display the list of defined startup types.
The Scope field shows whether the startup or shutdown affects this resource or its descendants, or both.
The Priority field shows the priority given to the request.
The Expire field shows the expiry date and time when the request will be removed.
The AutoRemove field shows the condition when the request is automatically removed regardless of whether the request is satisfied or not.
The Restart field shows whether the resource should be restarted automatically when it has been shut down completely. This applies only when requesting a shutdown of a resource.
The Override field shows the overrides to be considered for the request. The parameter can be used to bypass the conditions or settings that would otherwise prevent a resource, or resources, from starting or shutting down.
The Verify field shows whether the startup or shutdown process should be verified. If YES or WTOR is entered, the list of affected resources is displayed before the startup or shutdown begins. You will be prompted to verify the list. If WTOR is specified, you will be prompted via a WTOR. If NO is entered, the startup or shutdown begins immediately. The default is YES.
The Comment field lets you specify descriptive information, for example, why the request was made.
The Appl Parms field shows modifications or parameters to the START or STOP request.

If you press PF11 a panel similar to Figure 2 is displayed.

Figure 2. INGREQ Command Dialog Panel 2

 INGKYRU2                  SA z/OS  - Command Dialogs      Page   2 of 2        
 Domain ID   = IPSFP     ---------- INGREQ   ----------    Date = 04/27/06      
 Operator ID = NETOP1                                      Time = 18:53:03      
                                                                                
   Resource    =>  CICS/APL/KEY4                      format: name/type/system  
   Target      =>              System name, domain ID or sysplex name           
                                                                                
   Timeout     =>  0   / MSG     Interval in minutes / Option (MSG/CANCEL)      
   Precheck    =>  YES         Precheck for flags and passes (YES/NO)           
   Interrupt   =>  NO          Specify YES to terminate Startup processes      
   Boost       =>  YES         Specify NO to opt out from System Recovery Boost
                               during system shutdown 
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
 Command ===>                                                                   
    PF1=Help    PF2=End     PF3=Return                             PF6=Roll     
                                          PF10=Previous           PF12=Retrieve

The Timeout field shows the time period that the request must complete in. After this time interval either a message is issued, or the request is canceled.
The Precheck field shows whether or not the startup or shutdown process should perform up-front validation.
The Interrupt field shows whether or not a request to shut down a resource should interrupt the startup phase of a resource:

YES

The automation manager interrupts the startup process as soon as this stop request is submitted.

NO

If the resource is starting, the automation manager waits for the resource's UP message before proceeding with the shutdown. This is the default.
The Boost field shows whether or not the System Recovery Boost should be enabled upon system shutdown automatically. This parameter is used only for system shutdowns and is ignored for shutdown of any other resource.

YES

If a system is shut down, System Recovery Boost is enabled automatically. This is the default.

NO

If a system is shut down, it explicitly opts out from enabling System Recovery Boost, regardless of the setting of the BOOST system parameter in IEASYSxx.