Syntax for HSAPRM00

Notes:
  1. A sample member called HSAPRM00 is provided in the SINGSAMP sample library.
  2. Records starting with a '*' in column 1 are treated as comments. Each parameter must be specified on a single line. Trailing comments are not supported.
  3. z/OS system symbols are supported.
  ARMWAIT=nnn
  BLOCKOMVS={YES|NO}
  BUILDTIMEOUT={ss|180}
  CFGDSN=<configuration file data set name>
  COMM=XCF
  DELAY={ss|0}
  DIAGDUPMSG={nnnnn|0}
  DIAGINFO=dsname 
  GRPID={xx|'  '}
  IOINTERVAL={n|3}
  LEOPT={any}
  LIFECYCLE={500|nnnn};MY.AGENT.DATA.SET
  LOGSTREAM={YES|NO|GRPID}
  NUMQTHDS={n|3}
  OVRDELETEDELAY={dd|0}
  PREF={n|0}
  PROMPT={YES|NO}
  SUSPENDFILE=MY.SUSPEND.FILE
  START={COLD|HOT|WARM}
  STOPDELAY={ss|30}
  TAKEOVERFILE=name
  TAKEOVERTIMEOUT={nn|12}
  FUNCTIONLEVEL={nn|0}
ARMWAIT
Maximum number of seconds the automation manager waits for ARM being up during automation manager initialization. Not specified or 0 specified does not cause the AM to wait.

A value from 0-999 seconds may be specified.

BLOCKOMVS
This parameter allows you to specify whether the automation manager blocks OMVS shutdown as long as the automation manager is active.
YES
If BLOCKOMVS=YES is specified, at the automation manager initialization time, it adds a shutdown block to OMVS. Thus OMVS does not terminate as long as the automation manager is active, even if this is requested by the operator. OMVS is stopped only when the automation manager is stopped with the AM stop command.
Notes:
  1. A STOP,DEFER causes the automation manager to terminate when all agents connected to it have terminated. Then the stop command for OMVS will get through.
  2. For BLOCKOMVS=YES the automation manager must be UID(0).
  3. For BLOCKOMVS=YES to work effectively, the stop command for OMVS must be issued as "F OMVS,SHUTDOWN".
NO
If BLOCKOMVS=NO is specified and OMVS shuts down, the automation manager abends due to cancellation by OMVS.
Note:
  1. You should not use STOP, DEFER when BLOCKOMVS=NO is specified as it will cause unpredictable results.
BUILDTIMEOUT
May be used to specify a time limit for the completion of the data structure build process that is used during a COLD or WARM start of the primary automation manager. You can specify a value from 0–180 seconds. A value of 180 (3 minutes) is assumed if omitted. A specification of 0 suppresses timing of the data structure build process.
CFGDSN
The CFGDSN value is used only on a COLD start, and may be overridden by an initialization prompt response. On other start types, the default CFGDSN is the one that was in use when automation was last active.

Specify the name of the control data set that contains the SA z/OS configuration that is read by the SA z/OS automation agent and automation manager.

The name can be a fully qualified data set name or a generation data group (GDG) name (either a GDG base name which defaults to generation level 0, or a GDG base name with a level qualifier, for example(-1)).

When you specify a GDG base name and any generation level of the data set is archived, make sure that your storage management product (for example, HSM) is available. If it cannot be guaranteed, specify a generation level which is not archived. Otherwise, you would experience messages HSAM1306I and HSAM1304A.

COMM
This parameter specifies that the automation manager will use XCF for communication with the automation agents. In this case, the takeover file provides the persistent storage medium for holding the current resource states and settings across automation manager sessions.

Using XCF for communication has the following risks:

  • All work items travelling to, queued in, or processed by the automation manager are lost when the automation manager terminates abnormally.
  • Orders for the automation agents can be broken because some orders could already have been sent at the time when the automation manager terminated abnormally.
  • A warm start is required when an irrecoverable I/O error occurs while reading from or writing to the takeover file.
DELAY
Is the number of seconds to be used as a default delay prior to determining the operational mode when the automation manager instance is started. The delay option can be used when you IPL several systems concurrently and want to ensure that the primary or secondary automation manager is started on a particular system.

Note that the DELAY parameter applies only to the IPL of a system, whereas the PREF parameter applies only in the case of a takeover.

A delay value from 0–999 seconds may be specified. A value of 0 (no delay) will be assumed if it is omitted.

This value may by overridden on an individual instance basis by the start command parameter.

This parameter will be ignored when the automation manager instance is started by Automatic Restart Manager or with the specification of TYPE=HOT.

DIAGDUPMSG
This is the number of message buffer IDs that are validated before send and after receive. This is for diagnostic purposes. A value for nnnnn may be chosen between 0 (no validation) and 99999. The default is 0 and performance decreases with larger values.
DIAGINFO
Specifies that the automation manager starts work item recording from the beginning. dsname is the name of the data set that will hold the work items. The data set must be a sequential file. It must exist and must be catalogued.
Note: The data set name is accepted without checking if the data set exists or if it is accessed by another user.
FUNCTIONLEVEL
System Automation user function level. You can specify a value up to 5-digit number in the range 0 - 65535. The default value is 0.

This parameter is used to control what capabilities the manager is allowed to perform when operating in a System Automation sysplex environment with systems at different service levels.

Refer to Function levels for a detailed description and when to use function levels.

GRPID
Specifies the 2-character suffix that composes the XCF group name that is used by the automation manager and the various agents when communicating among each other.

The value must be the same as specified for GRPID in the corresponding member INGXINIT.

IOINTERVAL
This defines the interval that is used to buffer any I/O to the takeover file. The value can be from 0 to 10 seconds. At the end of the interval, any deferred I/O is done. The recommended value is 3.
LEOPT
May be used to pass runtime options to the runtime environment.
  1. Options forced by the Automation Manager.

    The following LE runtime options are set by the Automation Manager during initialization:

    ALL31(ON) POSIX(ON)
    Note: These options must not be overwritten by installation default settings (CEEOPT) with the NONOVR attribute.
  2. Default options set by the Automation Manager during initialization. The following LE runtime options are set by the Automation Manager during initialization:
    ANYHEAP(3M,1M,ANYWHERE,FREE)
DEPTHCONDLMT(4)
ERRCOUNT(0)
HEAP(100M,10M,ANYWHERE,KEEP)
STACK(64K,64K,ANYWHERE,KEEP)
STORAGE(NONE,NONE,NONE,128K)
    Note: You may override these options.
  3. The recommended LE Options.

    The following LE options are recommended for the System Automation Manager:

    NONIPSTACK(4K,4K,ANYWHERE,KEEP) or THREADSTACK(ON,4K,4K,ANYWHERE,KEEP,512K,128K)
    Note: NONIPSTACK was replaced by THREADSTACK in OS/390 LE 2.10
PROFILE(OFF,'')
RTLS(OFF)
STORAGE(NONE,NONE,NONE,128K)
THREADHEAP(4K,4K,ANYWHERE,KEEP)
TRACE(OFF,4K,DUMP,LE=0)
VCTRSAVE(OFF)
XPLINK(OFF)

    The following options can be used to gather diagnostic and storage usage information, but should be removed when no longer needed:RPTSTG(ON) RPTOPTS(ON)

    The LE options below should be tuned using the LE storage reporting facility RPTSTG(ON). The initial value for HEAP storage can be calculated using the following formula:heapsize = 16 MB + nnn - 8K where nnn is the number of resources and resource groups. 

    ANYHEAP(3M,1M,ANYWHERE,FREE)
HEAP(100M,10M,ANYWHERE,KEEP)
HEAPPOOLS(ON,40,2,64,2,104,2,312,2,624,1,2024,1)
STACK(64K,64K,ANYWHERE,KEEP)

    The following option is used to direct output created as a result of specifying RPTOPTS(ON) or RPTSTG(ON). It is also used to direct diagnostic messages written to CEEMSG and CEEMOUT by the Automation Manager.

    MSGFILE(SYSOUT,FBA,121,0,NOENQ)

    The storage options for below the line heap need to be tuned.

  4. On-demand options:

    Temporarily enable these options according to IBM support instructions or according to your needs.

    Enabling dynamic dumps (DYNDUMP):

    The DYNDUMP runtime option provides a way to obtain dynamic dumps of user applications that are ordinarily lost due to the absence of a SYSMDUMP, SYSUDUMP, or SYSABEND DD statement.

    For more information refer, DYNDUMP .

    LEOPT='DYNDUMP(#hlq#,DYNAMIC,TDUMP)'

    The #hlq# defines the HLQ that is used to name the dataset where the dump data is stored. The #hlq# value is limited to 26 characters including dot (.) separators. #hlq# allows three keywords.

    If the #hlq# is omitted then it defaults to the name of the user hosting the Automation Manager STC.

Notes:
  • If an LEOPT=keyword is present in HSAPRM00, it replaces any LEOPT that may have been specified as an input parameter through JCL.
  • When specifying options in HSAPRMxx you may have tuned LEOPT statements on multiple lines, but the total length of all of the options cannot exceed 4096 characters.
Sample LEOPTS statements are supplied in sample member HSAPRM00.
LIFECYCLE=nnnn;dataset
This parameter allows you to prepare for Life Cycle Recording in order to debug automation manager-related problems. Normally, SA z/OS Service will advise when Life Cycle Recording should be enabled. Specify the following:
nnnn
Defines the size of the data space in number of megabytes (1 through 2097). A value of 500 is recommended and is sufficient in most situations.
dataset
Specifies the fully-qualified DSN to be used when offloading the dataspace to disk.
Note: nnnn and dataset must be separated by a semicolon without intervening blanks. The total length of 'nnnn;dataset' can be a maximum of 44 bytes.
LOGSTREAM
The parameter defines if the automation manager establishes a connection to the system logger at initialization time. The default is YES which causes the automation manager to connect to the following log streams:
  • HSA.WORKITEM.HISTORY
  • HSA.MESSAGE.LOG
You may specify GRPID instead of YES to connect to a different set of log streams:
  • HSA.GRPxx.WORKITEM.HISTORY
  • HSA.GRPxx.MESSAGE.LOG
where xx represents the value of the keyword GRPID.

Then you may separate the log streams for each subplex. Note that if you specify GRPID but the value of the keyword GRPID is blank, the automation manager returns to the default value YES.

If NO is specified, no access to any SA-related log stream is established and subsequently no data is written into them. No work item history besides that shown in the INGINFO command is available and no detailed information or warning or error messages are available for problem determination.
Note: Both values, LOGSTREAM and GRPID, must be the same as in the DSIPARM member INGXINIT that is used to start the related NetView agent(s).
NUMQTHDS
The NUMQTHDS parameter controls the number of query threads. This value limits the amount of parallel query activity that can be performed. If not specified, a default value of 3 will be used. A maximum of 9 query threads may be specified.
OVRDELETEDELAY
Is the number of days that a schedule override should be retained before being automatically deleted. A value of 0 days indicates that schedule overrides are not to be automatically deleted and is the default if no value is specified. A maximum of 366 days may be specified.
PREF
Specifies the preference given to the instance of the automation manager when determining which of the secondary automation managers (SAMs) should become the primary automation manager.

The value can range from 0 through 15, where 0 is the highest preference. The SAM will only participate in the escalation process when there is no other SAM active with a higher preference. The default is 0.

Note that the PREF parameter applies only in the case of a takeover, whereas the DELAY parameter applies only to the IPL of a system.

PROMPT
Specifying YES lets you overwrite the CFGDSN parameter (the name of the automation manager configuration file). Message HSAM1302A is issued and waits for a response. You can now specify the keyword/value pair: 
CFGDSN=<fully.qualified.data.set.name>
Alternatively you can use a null or 'U' response to indicate that no override values are to be applied.
SUSPENDFILE
This parameter specifies the name of the suspend data set which contains the SA resources that should be suspended by the SA automation manager after loading or refreshing the configuration data set. The name must be a fully qualified data set name. It can also be a member of a partitioned data set.

Per default the SUSPENDFILE parameter is not set and it is a comment within HSAPRM00.

START
Defines the start mode of the automation manager. During initialization, the automation manager retrieves input from:
  •  1  The CFGDSN parameter
  •  2  Schedule overrides
  •  3  The persistent data store (Takeover File)

The following table shows where the automation manager retrieves initialization data for the possible values for the START parameter.

  COLD WARM HOT
 1  The name of automation manager configuration file is taken from PARMLIB, the START command, or via the PROMPT=YES option. The last value that was used is taken The last value that was used is taken
 2  Deleted Taken from the last run Taken from the last run
 3  Deleted Deleted Taken from the last run

For a detailed description about what data persisted where and how, see Manager Data persistence during a COLD or WARM start.

Recommendation:
  • Use COLD for the very first time, or when the schedule override file should be cleared.
  • Use WARM if the automation policy has changed, that is, the automation manager configuration file has been rebuilt.
  • Use HOT in any other case.

The start mode does not affect the secondary automation managers. However, the secondary automation manager reads the CFGDSN parameter from the original HSAPRMxx when the SAM was started. Any changes that you make to the HSAPRMxx are not reflected in a takeover with a cold start. If you want to perform a cold start with a modified HSAPRMxx you must first stop all your SAMs and then restart them.

The START parameter can also be specified in the automation manager JCL. If the HSAPRM00 values are to be used, the START= parameter must be removed from the JCL.

STOPDELAY
Is the number of seconds to be used when an MVS F <jobname>,STOP,DEFER command is entered for the primary automation manager. This delay will be invoked only if one or more secondary automation managers are active and ready when the command is received. Specify a value in the range 0–999 seconds. The recommended value is 30 seconds.
TAKEOVERFILE
This defines the data set name of the takeover file. It must be fully qualified.
TAKEOVERTIMEOUT
The value, nn, may range from 1 to 600 seconds. The default is 12 seconds.

If the (secondary) automation manager performs a takeover, or an automation manager is started HOT, it will wait for specified seconds before the takeover is done from the takeover file. This delay may be required in order to allow VSAM to perform its cleanup activities on the takeover file.