FCONTROL EMERGENC

Purpose

The FCONTROL EMERGENC subcommand allows you to control Performance Toolkit's emergency safeguard feature (ESF). With this feature enabled, Performance Toolkit will automatically save any unsaved data collected during normal monitoring in the event of an emergency, such as a z/VM shutdown or a sudden shortage in virtual memory. Data that can be saved includes printed reports, as well as trend and summary files.

In addition to saving data, Performance Toolkit will also call any user-defined EXEC procedure you've specified when an emergency event occurs.

Format

Read syntax diagramSkip visual syntax diagramFControlEMergencQueryONOFfEXecprocnameORderPrintInterimTrendSummaryRemprintExecproc

Parameters

Query
Returns a list of all the emergency safeguard feature (ESF) specifications as they are currently set. This is the default if no further argument is entered.
ESF status can be one of the following:
Disabled
No special actions are taken in emergency situations. This is the default setting.
Enabled
Emergency events detection activated, ready to take specified actions.
Suspended
Emergency events detection activated, but they will be ignored because permanent data collection is not active. Use FC MONCOLL ON command to activate it.
ON
Activates the emergency safeguard feature.
OFf
Deactivates the emergency safeguard feature.
EXecproc name
Defines name EXEC as the CMS EXEC procedure that will be called upon detection of an emergency event. Note that you must also specify the order in which all actions, including this EXEC procedure, will be specified, using an additional FC EMERGENC ORDER command.

For more information on this parameter, see Usage Note 4.

ORder
Allows specification of the actions that will be done, as well as their order, when an emergency event is detected. Multiple selections are possible. Note that each subsequent FC EMERGENC ORDER command invocation will clear any previously defined actions.
The valid actions are as follows:
Print
Indicates that the print reports defined with the FC MONCOLL RESET hh:mm:ssP command(s) will be created.
Interim
Indicates that the print reports defined with the FC MONCOLL RESET hh:mm:ssI command(s) will be created.
Trend
Indicates that the trend records defined with the FC MONCOLL RESET hh:mm:ssT command(s) will be processed and saved.
Summary
Indicates that the summary records defined with the FC MONCOLL RESET hh:mm:ssS command(s) will be processed and saved.
Remprint
Indicates that the print reports defined with the FC SETEVENT ... PRINTRMT command(s) will be created.
Execproc
Indicates that the CMS EXEC procedure previously defined by the FC EMERGENC EXECPROC command will be called.

Usage

  1. If an emergency event occurs and any of the PRINT, INTERIM, TREND or SUMMARY actions have been specified with the FC EMERGENC ORDER command, Performance Toolkit will attempt to save any collected data by scanning the reset chain (as defined by the FC MONCOLL RESET command) to find any appropriate actions that have been scheduled before the next reset. If any such actions are found, Performance Toolkit will perform the corresponding report printing, trend/summary file creation, or both, just as if they had been defined using the FC MONCOLL RESET command. Performance Toolkit will avoid any unnecessary duplicate actions.
  2. For the REMPRINT action, the operation is similar to that described above, except in this case Performance Toolkit will scan the event chain defined with the FC SETEVENT command, looking for only those event elements that reference the PRINTRMT command. If any scheduled PRINTRMT commands are found, Performance Toolkit will process them, avoiding any duplicate actions.
  3. When performing the emergency safeguard actions, there are special timing considerations that must be kept in mind regarding TREND and SUMMARY reports. Because the overall time available for performing these safeguard actions may be limited by the system (as defined by the CP SET SHUTDOWNTIME command), care should be taken when defining the order in which these actions are taken, so that the most valuable data is saved first.

    Note that Performance Toolkit keeps trend data in records with a fixed size of 4K bytes, while summary data records have variable lengths. Because of this format difference, trend files can be written to disk much faster.

  4. Special notes for the EXECPROC option:
    1. Remember that you must specify a user-defined EXEC procedure in two separate commands – an FC EMERGENC EXECPROC name command to define the actual EXEC procedure, and an FC EMERGENC ORDER command to specify the order in which all actions, including this EXEC procedure, will be specified.
    2. A user-defined EXEC procedure will be notified of the emergency event reason by way of a special parameter that will be passed to it. The possible parameter values and their meanings are as follows:
      *SHUTDWN
      A signal shutdown event has been detected.
      *NOMEM
      Performance Toolkit ran out of virtual storage.
      *NOCONS
      A permanent Performance Toolkit console I/O error (it was detached or redefined with a different device number).
      *UNKNOWN
      All others (this value should not occur).
      A sample parameter handling code is shown below: 
      
/* Sample Emergency Safeguard Feature EXEC procedure */            
Arg emgparm .                                                          
Select                                                                 
  When emgparm = '*SHUTDWN' Then reason = 'SHUTDOWN'                   
  When emgparm = '*NOMEM'   Then reason = 'Performance Toolkit memory shortage'    
  When emgparm = '*NOCONS'  Then reason = 'Permanent console I/O error'
  When emgparm = '*UNKNOWN' Then reason = 'unknown reason'             
  Otherwise Nop                                                        
End                                                                    
'tell OP1 Emergency exit is being taken due to' reason
    3. When writing a user-defined EXEC procedure, remember that certain restrictions may apply, due to the nature of the emergency of event. In the case of a system shutdown, for instance, the same timing consideration as described in Usage Note 3 will apply. If the procedure is called due to a lack of virtual storage, any further storage-intensive functions may lead to a CMS system abend. (Although note that a special reserved free storage buffer will be provided to help mitigate this possibility.)