Syntax and parameters for HZSPRMxx and MODIFY hzsproc
Syntax and parameters for HZSPRMxx and MODIFY hzsproc |
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The parameters are:
- filters
- ACTIVATE
ACTIVATE,filters
Sets the specified check or checks to the active state. If the check is eligible to run, ACTIVATE will cause the check to run immediately, or, if SYNCVAL is in effect, to re-calculate the start time for its next run based on SYNCVAL and reset the interval for the check. You must specify filter CHECK=(check_owner,check_name) with ACTIVATE. Other filters are optional. See filters.
ACTIVATE, filters
is equivalent to the UPDATE,filters,ACTIVE command. See the UPDATE ACTIVE and INACTIVE parameters.- ADDNEW
ADDNEW
ADDNEW adds checks to IBM Health Checker for z/OS.- For checks defined and added by a HZSADDCHECK exit routine, ADDNEW calls the HZSADDCHECK exit to add checks to IBM Health Checker for z/OS
- For checks defined and added in an HZSPRMxx parmlib member (using the ADD|ADDREPLACE,CHECK parameters), ADDNEW processes the definitions in parmlib to add checks to IBM® Health Checker for z/OS®
- Applies any installation updates in the policy to the default values for the check.
- Loads the check routine, if this is a local check.
- Loads the message table, if it is a local or a REXX exec check.
You can use ADDNEW to undelete a check that has been deleted. See Why does my check reappear after I delete it? Understanding delete processing.
- DEACTIVATE
DEACTIVATE disables running of the specified check until ACTIVATE is specified. You must specify filter CHECK=(check_owner,check_name) with DEACTIVATE. Other filters are optional. See filters.DEACTIVATE,filters
DEACTIVATE is the same as the UPDATE,filters,INACTIVE command. See UPDATE ACTIVE and INACTIVE parameters.
- DELETE
DELETE,filters[,FORCE={NO | YES}]
Remove the specified check(s) from the IBM Health Checker for z/OS. The delete request will be completed asynchronously and if the specified check or checks are running when the command is issued, the system waits until they are finished running before deleting them (see FORCE={NO | YES} for exceptions to this). You must specify filter CHECK=(check_owner,check_name) with DELETE. Other filters are optional. See filters.
You can undelete a deleted check using the ADDNEW parameter. See Why does my check reappear after I delete it? Understanding delete processing for more information about DELETE processing.
- FORCE={NO | YES}
- Specifies whether or not you want to force deletion of a check even if the check is running.
FORCE=NO is the default. Use FORCE=YES only as a last resort after trying the DELETE parameter with FORCE=NO because:
- FORCE=YES causes a check to be interrupted in the middle of its processing:
- FORCE=YES issued against a local check results in a non-retriable abend on the third try.
- FORCE=YES issued against a remote or REXX exec check results in a non-retriable abend.
- FORCE=YES deletes checks that are still in the process of running.
- FORCE=YES causes a check to be interrupted in the middle of its processing:
- DISPLAY
- DISPLAY issues messages with information specified. The
different options display the information, as follows:
DISPLAY { [CHECKS[,filters][,LOCALE=(HZSPROC|REMOTE|REXX|NOTHZSPROC)][,SUMMARY|,DETAIL][,ANY|,NOTDELETED|,DELETED] [,POLICYEXCEPTIONS][,EXCEPTIONS][,DIAG]] | [filters[,LOCALE=(HZSPROC|REMOTE|REXX|NOTHZSPROC)][,SUMMARY|,DETAIL][,ANY|,NOTDELETED|,DELETED][,POLICYEXCEPTIONS] [,EXCEPTIONS][,DIAG]] | [POLICY[=policyname][,STATEMENT=name][,SUMMARY|,DETAIL]} [,CHECK=(check_owner,check_name)[,SUMMARY|,DETAIL][,OUTDATED] | [STATUS] | POLICIES } [,L=n]
- CHECKS
- CHECKS displays information about checks.
- L=n
- Optionally specifies the display area, n, where the display is to appear. If you omit this operand, the display is presented in the first available display area or the message area of the console through which you enter the command.
- filters
- You must specify filter CHECK=(check_owner,check_name) with DISPLAY, unless you specify DISPLAY,CHECKSfilters. Other filters are optional. See filters.
- LOCALE=(HZSPROC | REMOTE | REXX | NOHZSPROC)
- Specifies whether you want to display local or remote checks:
- HZSPROC specifies that you want to display only local checks that run in the hzsproc address space.
- REMOTE specifies that you want to display only remote checks that run in the caller's address space.
- REXX specifies that you want to display only REXX exec checks running under System REXX.
- NOTHZSPROC specifies that you want to display both remote and REXX exec checks, but not local checks.
- SUMMARY
- IBM Health Checker for z/OS issues message HZS200I with summary
information about the specified checks. See the "Example of DISPLAY SUMMARY message output". For
each check matching the specified criteria, the following information is returned:
- Check owner
- Check name
- The name of any category the check is a member of
- The current status of the check.
- DETAIL
- IBM Health Checker for z/OS issues message HZS0201I (See
"Example of DISPLAY DETAIL message output") with detailed information about the specified check
including:
- Check name
- Check owner
- The name of any category the check is a member of
- The Date and time the check was last executed
- The current status of the check
- The check values, such as severity, routing codes, and descriptor codes.
- ANY
- Displays information about both deleted and non-deleted checks. ANY is the default.
- NOTDELETED
- Displays information about checks that have not been deleted.
- DELETED
- Displays information about checks that have been deleted.
- POLICYEXCEPTIONS
- Display information about checks for which a policy statement matching the check was not applied because the date on the policy statement is older than the check date.
- EXCEPTIONS
- Display information about checks that completed with a non-zero return value.
- DIAG
- Displays additional diagnostic data such as the check routine address and message table address. See "Example of DISPLAY DIAG message output".
- POLICY
- Displays the specified policy statements. You can filter DISPLAY POLICY by:
- Policy name
- Policy statement name
- Check owner or name
- POLICY=policyname
- Specifies the 1-16 character name of the policy whose policy statements you wish to display. If you do not specify policyname , the system displays the current active policy statements. If policyname contains wildcards, the system displays all applicable policies and their statements, with a blank line separating each policy.
- STATEMENT=name
- STATEMENT specifies the 1-16 character name of the policy statement whose policy statements you wish to display.
- CHECK=(check_owner,check_name)
- check_owner specifies the 1-16 character check owner name . check_name specifies the 1-32 character check name. The system displays the policy statements that apply to the specified checks.
- STATUS
- Displays status information about IBM Health Checker for z/OS
and checks in message HZS0203I (see "Example of DISPLAY STATUS message output"), including the
following information:
- Number of checks that are eligible to run
- Number of active checks that are running
- Number of checks that are not eligible to run
- Number of deleted checks
- ASID of the IBM Health Checker for z/OS address space
- The log stream name and its status
- The current HZSPRMxx parmlib suffix list
- POLICIES
- Displays the names of all policies defined for IBM Health Checker for z/OS.
- HZSPDATA
Specifies the name and optional volume for the HZSPDATA data set you want IBM Health Checker for z/OS to use to save data required by checks as part of their processing between restarts of the system or IBM Health Checker for z/OS. See Allocate the HZSPDATA data set to save check data between restarts for more information.HZSPDATA=datasetname[,VOLUME=volser]
- SET,OPTION
- CHKMSG_NOCONSID=[ON|OFF]
- When turned ON this option can prevent routing problems for check exception messages by omitting the console ID parameter on WTOs sent for health check exception messages.
MODIFY HZSPROC,DISPLAY,STATUS
- LOGGER
Use the LOGGER parameter to connect to and use a pre-defined log stream whenever a check generates output.LOGGER={OFF|ON|ON,LOGSTREAMNAME=logstreamname}
- LOGGER=ON,LOGSTREAMNAME=logstreamname
- The first time you use the LOGGER parameter to connect to the log stream for IBM Health Checker for z/OS, you must specify a log stream name. The log
stream name must begin with HZS and must follow system logger naming rules. See z/OS MVS Setting Up a Sysplex for
information on setting up and managing a log stream.
The system rejects this parameter if the log stream is already in use without any errors. If a log stream is in use with errors when you use the LOGGER parameter, the system disconnects from the current log stream.
After initially specifying LOGGER=ON,LOGSTREAMNAME=logstreamname, you can use LOGGER=ON and LOGGER=OFF to toggle use of the log stream on and off.
- LOGGER=ON
- Connects to and begins using the log stream for check routine messages.
- LOGGER=ON is rejected if a log stream has not already been provided.
- LOGGER=ON has no effect if the log stream is already in use without any errors.
- LOGGER=OFF
- Stops using the log stream for check routine messages. LOGGER=OFF is the default.
- REFRESH
REFRESH,filters
Refreshes the specified check or checks. Refresh processing first deletes a check from the IBM Health Checker for z/OS and does the ADDNEW function (ADDNEW parameter).
When you issue a command with the REFRESH parameter on it, the system processes the policy statements and applies any changes to check values that the policy statements contain. See How IBM Health Checker for z/OS builds policies from policy statements.
You must specify filter CHECK=(check_owner,check_name) with REFRESH. Other filters are optional. See filters.
- RUN,filters
- Run the specified check(s) immediately, one time. Specifying RUN does not reset the check interval. You must specify filter CHECK=(check_owner,check_name) with RUN. Other filters are optional. See filters.
- STOP
- Stop IBM Health Checker for
z/OS. Do not use STOP unless absolutely necessary; every time
you STOP the IBM Health Checker for z/OS address space, that address
space identifier (ASID) becomes unavailable.To start IBM Health Checker for z/OS, use one of the following commands:
-
START hzsproc
-
START hzsproc,HZSPRM=xx
-
- UPDATE
UPDATE,filters [,ACTIVE|INACTIVE] [,ADDCAT=(cat1,...,cat16)] [,DATE={date | (date,NOCHECK)}] [,DEBUG={OFF|ON}] [,VERBOSE={NO|YES}] [,DESCCODE=(desccode1,...,desccoden)] [,INTERVAL={ONETIME|hhh:mm}] [,EXCEPTINTERVAL={SYSTEM|HALF|hhh:mm}] [,SYNCVAL={SYSTEM|hh:mm|*:mm}] [,PARM=parameter,REASON=reason,DATE={date | (date,NOCHECK)}] [,REASON=reason] [,REPCAT=(cat1[,cat2[,...,cat16]])] [,REMCAT=(cat1[,cat2[,...,cat16]])] [,REXXTIMELIMIT=timelimit] [,REXXHLQ=hlq] [,ROUTCODE=(routcode1,...,routcoden)] [,SEVERITY={HIGH|MEDIUM|LOW|NONE}] [,WTOTYPE={CRITICAL|EVENTUAL|INFORMATIONAL|HARDCOPY|NONE}]
UPDATE allows you to temporarily update the current default or override values for the specified checks. Values updated are in effect until the next refresh for specified checks. You cannot update checks that are deleted or have a delete pending against. Note that adding or removing the check from a category does not effect the current check implementations.
You must specify filter CHECK=(check_owner,check_name) with UPDATE. Other filters are optional. See filters.
If an UPDATE request does not actually change anything, the system takes no action in response to the request. For example, if you use an UPDATE request to make the severity HIGH for a check whose severity is already HIGH, the system does not process the request, and nothing is done.- ACTIVE | INACTIVE
- Use the ACTIVE and INACTIVE parameters to change the state of the check. See Understanding check state and status. These parameters are equivalent to "ACTIVATE parameter" and "DEACTIVATE parameter".
- ADDCAT=(cat1,...,catn)
- ADDCAT adds specified checks into each of the listed categories. You can specify up to 16 categories, each a 1-16 character category name.
- DATE={date | (date,NOCHECK)}
- DATE specifies when the values for a check were last updated. The date is specified in
the format yyyymmdd. If the date specified on the UPDATE parameter is earlier
than the date for the check, the system does not process the values specified on the UPDATE
parameter because the UPDATE statement may no longer be appropriate for the check.
- NOCHECK
- IBM Health Checker for z/OS verifies the date for the UPDATE
statement, making sure that it is equal to or newer than the date for the check that the statement
applies to. Use NOCHECK to bypass date verification so that you do not have to update the UPDATE
statement date for minor changes to a check.
If you use the NOCHECK parameter, you must use parentheses on the DATE parameter. For example, you can specify either
DATE=date
orDATE=(date,NOCHECK)
.If your POLICY UPDATE statement contains any of the following, NOCHECK is ignored: PARM, ACTIVE, INACTIVE, SEVERITY, INTERVAL. NOCHECK is also ignored for a POLICY DELETE statement.
- DEBUG={OFF|ON}
- DEBUG specifies the debug mode desired:
- OFF specifies that debug mode is off, which is the default.
- ON specifies that you want to run with debug mode on. Turning debug mode ON lets you see
debug messages, if the check produces any, which are designed to help a product or installation
debug a check routine or to display additional check information. Debug messages are only issued
when the check is in debug mode. See the individual check descriptions in IBM Health Checker for z/OS checks
to see if a check issues additional information when you specify DEBUG=ON.
Using SDSF to view check output in the message buffer when the debug mode is ON allows you to see the message IDs of debug messages.
Debug mode ON will not take effect until you re-run the check or checks. For example, after you issue a command to turn debug mode ON, you could issue the command with the RUN parameter, which will run the check or checks with debug mode ON.
For a REXX exec check, DEBUG must be ON for the check to write data or error messages to an output data set.
- VERBOSE={NO|YES}
- VERBOSE specifies the verbose mode desired:
- NO specifies that you do not want to run in verbose mode.
- YES specifies that you want to run in verbose mode. Running in verbose mode you see
additional messages about non-exception conditions, if the check supports verbose mode. These
messages are only issued when the check is in verbose mode. See the individual check descriptions in
IBM Health Checker for z/OS checks to see if a check supports issues additional messages if you specify
VERBOSE=YES.
Verbose mode does not take effect until you re-run the check or checks. For example, after you issue a command to turn verbose mode on, you could issue the
F hzsproc
command with the RUN parameter to run the check or checks with verbose mode on.
- DESCCODE=(desccode1[,...,desccoden])
- DESCCODE specifies descriptor code(s) in addition to the system default descriptor
code used when an exception message is issued by the specified check. You can specify a list of up
to 13 descriptor codes, each with a value between 1 and 13
See"WTOTYPE" for a list of the message types and corresponding default descriptor codes. For example, if you specify DESCODE=(7) for a low severity check, the system uses descriptor code 7 in addition to the default descriptor code of 12 for the check. See Descriptor codes in z/OS MVS System Messages, Vol 1 (ABA-AOM).
If you do not specify DESCCODE or if you specify DESCCODE=0, the system uses just the system-default descriptor code when the exception message is issued.
- INTERVAL={ONETIME|hhh:mm}
- INTERVAL specifies how often the check should run:
- ONETIME specifies that the check should run only once, kicked off either by refresh
processing or by the SYNCVAL scheduled run time.Note: Note that the system might still schedule this check to run more than once. The system will continue to schedule the check to run until the check reports success if both of the following are true:
- The check finds an exception during its very first run.
- The check is configured with an exception interval of the form EXCEPTINTERVAL(hhh:mm).
- hhh:mm provides a specific interval for the check to run. The check will run
at refresh time and periodically afterwards at the interval specified or in alignment with the
SYNCVAL parameter.
hhh indicates the number of hours, from 0 to 999. mm indicates the number of minutes, from 0 to 59.
The system starts processing the interval depending on whether you are using the SYNCVAL parameter:- If you are using SYNCVAL={hh:mm|*:mm}, the specified interval time starts ticking away when the check is scheduled to run, to align it with the SYNCVAL start time.
- If you are not using SYNCVAL or using SYNCVAL=SYSTEM, the specified interval time starts ticking away when a check finishes running.
- ONETIME specifies that the check should run only once, kicked off either by refresh
processing or by the SYNCVAL scheduled run time.
- EXCEPTINTERVAL={SYSTEM | HALF | hhh:mm}
- EXCEPTINTERVAL specifies how often the check should run after the check has found an
exception. This parameter allows you to specify a shorter check interval for checks that have found
an exception.
- SYSTEM, which is the default, specifies that the EXCEPTINTERVAL is the same as the INTERVAL.
- HALF specifies that the exception interval is defined to be half of the normal interval.
For example, the exception interval will be set to 30 seconds, if the normal interval is set to 1
minute.
Note that if you change the INTERVAL parameter for a check, the system will also recalculate the exception interval.
- hhh:mm provides a specific exception interval for the check. After raising an exception, the check will run at the exception interval specified. hhh indicates the number of hours, from 0 to 999. mm indicates the number of minutes, from 0 to 59.
The system starts processing the interval depending on whether you are using the SYNCVAL parameter:- If you are not using SYNCVAL or using SYNCVAL=SYSTEM|HALF, the specified interval time starts ticking away when a check finishes running.
- If you are using SYNCVAL={hh:mm|*:mm}, the specified interval time starts ticking away when the check starts running, to align it with the SYNCVAL start time.
- SYNCVAL={SYSTEM|hh:mm|*:mm}
- SYNCVAL specifies a synchronization value you can use to control when a check is
scheduled to run. SYNCVAL works with both the INTERVAL and EXCEPTINTERVAL parameters, so the values
must be coordinated.
You can only use SYNCVAL in a policy statement - it is valid only on an
ADD|ADDREPLACE, POLICY STMT(statement_name) UPDATE,filters,update_options
statement in the update_options.See Using SYNCVAL in a policy to specify the time of day that a check runs for examples and how to coordinate SYNCVAL with INTERVAL and EXCEPTINTERVAL.
The values for SYNCVAL include:- SYSTEM
- Specifies that the check run immediately after being added, if eligible, and subsequently at the interval defined for the check. The specified interval time starts ticking away when a check finishes running. SYSTEM is the default.
- hh:mm
- Specifies a specific time in hours and minutes in the day to schedule the check to run for the
first time, as well as any subsequent iterations synchronized with the current INTERVAL or
EXCEPTINTERVAL value.
Check run time is scheduled to aligned with the SYNCVAL start time. The INTERVAL time for the check starts ticking away when the check starts running.
- hh
- Valid values are 0 through 23.
- mm
- Valid values are 0 through 59.
Make sure that the values for SYNCVAL and INTERVAL/EXCEPTINTERVAL parameters work validly together. These parameters must be coordinated whether you specify SYNCVAL and INTERVAL/EXCEPTINTERVAL on the same policy statement, or just use the currently defined INTERVAL/EXCEPTINTERVAL for the check. For SYNCVAL(hh:mm) and INTERVAL(hhh:mm), the hhh:mm value in total minutes (hhh*60 + mm) must be a divisor or multiple of 1440 minutes (24 hours).
- *:mm
- Specifies the minute in an hour the check is scheduled to run for the first time, as well as for
subsequent runs, synchronized with the current INTERVAL or EXCEPTINTERVAL value. If the given minute
has already passed for the current hour, the check is scheduled for the specified minute in the next
hour.
Check run time is scheduled to aligned with the SYNCVAL start time. The INTERVAL time for the check starts ticking away when the check starts running.
Make sure that the values for SYNCVAL and INTERVAL/EXCEPTINTERVAL parameters work validly together. These parameters must be coordinated whether you specify SYNCVAL and INTERVAL/EXCEPTINTERVAL on the same policy statement, or just use the currently defined INTERVAL/EXCEPTINTERVAL for the check. For SYNCVAL(*:mm) and INTERVAL(hhh:mm), the hhh:mm value in total minutes (hhh*60 + mm) must be a divisor or multiple of 60 minutes (1 hour).
Valid values for mm are 0 to 59.
- PARM=parameter
- PARM specifies the check specific parameters being passed to the check. The value for
parameter can be 1-256 text characters. You can specify these characters as:
- A single value enclosed in single quotes.
- Multiple values, where either each value is enclosed in single quotes or the group of values is enclosed is single quotes. The system will separate these values from each other by a comma. For example, both PARM='p1,p2,p3' and PARM=('p1','p2','p3') will both resolve to a parameter value of p1,p2,p3.
You can also specify PARM with a null parameter string, PARM=(), to remove all parameters and clear a parameter error for a check that does not accept parameters.
You must specify the REASON and DATE parameters when you specify PARM.When you issue a command with the PARM parameter, the check runs immediately.
- REASON=reason
- REASON specifies the unique reason the check specific parameters are being overridden.
The value for reason can be 1-126 text characters. You can specify these
characters as:
- A single value enclosed in single quotes.
- Multiple values, where either each value is enclosed in single quotes or the group of values is enclosed is single quotes. The system will separate these values from each other by a blank. For example, both REASON='r1 r2 r3' and REASON=('r1','r2','r3') will both resolve to a reason of r1 r2 r3.
- REMCAT=(cat1,...,catn)
- REMCAT removes the specified checks from the categories listed. You can specify up to 16 categories, each a 1-16 character category name.
- REPCAT=(cat1,...,catn)
- REPCAT removes the specified checks from any existing categories they belong to and adds them to the categories listed.
- REXXHLQ=hlq
- REXXHLQ is an optional input parameter that specifies the high level qualifier for data sets that are made available to the REXX exec in each check iteration. See REXXIN data set naming conventions and REXXOUT data set naming conventions for information about how the system determines the name of your input or output data set.
- REXXTIMELIMIT=timelimit
- REXXTIMELIMIT specifies an optional input parameter that is the number of seconds to which the
execution of an iteration of the exec is to be limited. You can specify a value between 0 and
21474536 for REXXTIMELIMIT.
A value of 0 is treated the same as no time limit. The default is that there is no time limit.
- ROUTCODE=(routcode1,...,routcoden)
- ROUTCODE specifies the routing codes to be used when an exception message is issued by
the specified check. You can specify a list of up to 128 routing codes, each with a value between 1
and 128.
If ROUTCODE is not specified, or if ROUTCODE=0 is specified, the system uses the system-default routing codes for exception messages.
- SEVERITY={HIGH | MEDIUM | LOW | NONE}
- SEVERITY overrides the default check severity. The severity you pick determines how the
exception messages the check routine issues with the HZSFMSG service are written.
- HIGH indicates that the check routine is checking for high-severity problems. All exception messages that the check issues with the HZSFMSG service will be issued to the console as critical eventual action messages. HZS0003E is issued, which includes message text defined by the check owner.
- MEDIUM indicates that the check routine is looking for medium-severity problems. All exception messages the check issues with HZSFMSG will be issued to the console as eventual action messages. HZS0002E is issued which includes message text defined by the check owner.
- LOW indicates that the check is looking for low-severity problems. All exception messages the check issues with HZSFMSG will be issued to the console as informational messages. HZS0001I is issued which includes message text defined by the check owner.
- NONE indicates that you're assigning no severity to this check. Exception messages issued by the check with HZSFMSG are issued to the hardcopy log, rather than the console. HZS0004I is issued which includes message text defined by the check owner.
Note that there are a couple of things that can override the SEVERITY specifications and implicit behaviors derived from SEVERITY:- The WTOTYPE parameter overrides the implicit WTO type derived from the SEVERITY defined for a check - see "WTOTYPE".
- A check using the dynamic check severity function can override the SEVERITY you define for a check - see Writing a check with dynamic severity levels.
- WTOTYPE={CRITICAL|EVENTUAL|INFORMATIONAL|HARDCOPY|NONE}
- WTOTYPE specifies the type of WTO you want the system to issue when the check finds an
exception. This parameter includes all WTOs issued by a check. The WTOTYPE specified on the UPDATE CHECK statement overrides the implicit WTO type derived from either:
- The SEVERITY specified for the check on either the ADD or UPDATE CHECK statement.
- The dynamic severity specified by the check. See Writing a check with dynamic severity levels.
Note that the WTOTYPE only determines what type of action is associated with a check exception WTO. Check status (such as EXCEPTION, MEDIUM, or SUCCESSFUL), remains unaffected by WTOTYPE because it is derived solely from the current severity specified in either the check definition or dynamically by the check itself.
- CRITICAL
- Specifies that the system issue an critical eventual action message (with a descriptor code of 11) when the check finds an exception. This is the default if SEVERITY(HIGH) is specified or defaulted to.
- EVENTUAL
- Specifies that the system issue an eventual action message (with a descriptor code of 3) when the check finds an exception. This is the default if SEVERITY(MEDIUM) is specified or defaulted to.
- INFORMATIONAL
- Specifies that an informational message with a descriptor code of 12 should be issued when an exception is found. This is the default if SEVERITY(LOW) is specified or defaulted.
- HARDCOPY
- Specifies that the system issue the message to the hardcopy log. This is the default if SEVERITY(NONE) is specified.
- NONE
- Specifies that no WTO be issued when the check finds an exception.
- {ADD | ADDREPLACE},CHECK
Allows you to add or replace a check definition in an HZSPRMxx parmlib member. The parameters correspond to the parameters in the HZSADDCK macro.{ADD | ADDREPLACE},CHECK=(check_owner,check_name) ,{CHECKROUTINE=routinename | EXEC=execname ,REXXHLQ=hlq [,REXXTIMELIMIT=timelimitvalue] { [,REXXTSO=YES] | [,REXXTSO=NO [,REXXIN={NO|YES} ] } } ,MESSAGETABLE={msgtablename|*NONE } ,SEVERITY={HIGH|MEDIUM|LOW} ,INTERVAL={ONETIME|hhh:mm} ,DATE=date ,REASON=reason [,PARM=parameter] [,GLOBAL} [,ACTIVE|INACTIVE] [,EXCEPTINTERVAL={SYSTEM|HALF|hhh:mm}] [,USS={NO|YES}] [,VERBOSE={NO|YES}] [,ENTRYCODE=entrycode|0] [,ALLOWDYNSEV={NO|YES}] [,DOM={SYSTEM|CHECK}]
- ADD
- Allows you to add a check definition to an HZSPRMxx parmlib member. If you use ADD,CHECK to add a check that has already been defined, the request is rejected. When a check that was added in this way is subsequently deleted, the check definition still remains. ADDNEW or REFRESH command processing will bring the check back exactly as it was defined.
- ADDREPLACE
- Specifies that the system either add or replace the check definition, as appropriate. If the check defiinition is new, the system will add it. If the check definition exists already, the system will replace it with the one specified.
- CHECK=(check_owner,check_name)
-
- check_owner
- A required input parameter that specifies the owner of the check being added. The check owner and check name identify the check. IBM recommends that you use your company name followed by the short component name (for example, IBMGRS) as the owner. Upper and lower case alphabetic characters (a-z), numerics (0-9), national characters (@,$,#) and the underscore ('_') are allowed. Lower case alphabetic characters are folded to upper case and are treated as equivalent to their corresponding upper case value. Do not use as the check owner any of the following: QUERY, MESSAGES, ACTIVATE, DEACTIVATE, UPDATE, RUN, REFRESH, DELETE, ADDNEW. The check owner can not be longer than 16 characters.
- check_name
- A required input parameter that specifies the name of the check being added. IBM recommends using the naming convention of a short component reference followed by a descriptive title (for example, GRS_MODE). Upper and lower case alphabetic characters (a-z), numerics (0-9), national characters (@,$,#) and the underscore ('_') are allowed. Lower case alphabetic characters are folded to upper case and are treated as equivalent to their corresponding upper case value. The check owner can not be longer than 32 characters.
- CHECKROUTINE=routinename | EXEC=execname
- Use CHECKROUTINE or EXEC to specify the type of check you are adding or replacing.
- CHECKROUTINE=routinename specifies that you are defining a local or remote assembler check. Required parameter specifies a module name for the check you are adding or replacing. The system gives control to the entry point of this module to run the check. The check routine module must be in an APF-authorized library and the system must be able to locate the check routine within the joblib or steplib of the IBM Health Checker for z/OS address space, the LPA, or the LNKLST, and the check routine's AMODE is expected to be AMODE 31.
- EXEC=execname specifies that you are defining a REXX exec check. Required parameter specifies an exec name for the check you are adding or replacing. The exec does not have to be in an APF-authorized library.
- REXXHLQ=hlq
- When EXEC=execname is specified, REXXHLQ is a required input parameter specifying the high level qualifier for data sets(s) to be made available to the REXX exec. See Using REXXOUT data sets for information on how the system determines the name of your input or output data set.
- REXXTIMELIMIT=timelimit
- When EXEC is specified, REXXTIMELIMIT specifies an optional input parameter that is the number
of seconds to which the execution of an iteration of the exec is to be limited. You can specify a
value between 0 and 21474536 for REXXTIMELIMIT.
A value of 0 is treated the same as no time limit. The default is that there is no time limit.
- REXXTSO=YES
- Specifies that you are adding or replacing a TSO REXX exec check. A TSO check runs in a TSO
environment and can use TSO services. See Writing REXX checks for more information.
REXXTSO=YES is the default.
- REXXTSO=NO
- Specifies that you are adding or replacing a non-TSO REXX exec check. A non-TSO check does not
run in a TSO environment, and cannot use TSO services. See Writing REXX checks for more
information.
- REXXIN={NO|YES}
- Specifies whether or not a non-TSO check requires a sequential input data set.
You can specify REXXIN(YES) only for a non-TSO REXX exec check defined with REXXTSO(NO). See Using REXXOUT data sets for information on how the system determines the name of your input set for information for a non-TSO check.
REXXIN=NO is the default.
- MESSAGETABLE=msgtablename|*NONE
- Required parameter specifies the module name of the message table that will be used when
generating messages for the check you are adding or replacing:
- msgtablename specifies a name for the message table. The message table must be built using HZSMSGEN. The message table module must be in an APF-authorized library and the system must be able to locate the check routine within the joblib or steplib of the IBM Health Checker for z/OS address space, the LPA, or the LNKLST.
- *NONE indicates that you are adding or replacing a check that has no associated message table, using instead HZSFMSG REQUEST=DIRECTMSG or HZSLFMSG_REQUEST='DIRECTMSG' to issue messages directly from the check routine. See Issuing messages for your check - message table checks versus DIRECTMSG checks.
- SEVERITY={HIGH|MEDIUM|LOW}
- Required parameter SEVERITY defines default check severity for the check you are adding
or replacing. The severity you pick determines how the exception messages the check routine issues
with the HZSFMSG service are written.
- HIGH indicates that the check routine is checking for high-severity problems. All exception messages that the check issues with the HZSFMSG service will be issued to the console as critical eventual action messages. HZS0003E is issued, which includes message text defined by the check owner.
- MEDIUM indicates that the check routine is looking for medium-severity problems. All exception messages the check issues with HZSFMSG will be issued to the console as eventual action messages. HZS0002E is issued which includes message text defined by the check owner.
- LOW indicates that the check is looking for low-severity problems. All exception messages the check issues with HZSFMSG will be issued to the console as informational messages. HZS0001I is issued which includes message text defined by the check owner.
Note that there are a couple of things that can override the SEVERITY specifications and implicit behaviors derived from SEVERITY:- The WTOTYPE parameter overrides the implicit WTO type derived from the SEVERITY defined for a check - see"WTOTYPE".
- A check using the dynamic check severity function can override the SEVERITY you define for a check - see Writing a check with dynamic severity levels.
- INTERVAL={ONETIME|hhh:mm}
- Required parameter INTERVAL specifies how often the check should run:
- ONETIME specifies that the check should run only once, kicked off by refresh processing
or in alignment to a SYNCVAL value for the check.Note: Note that the system might still schedule this check to run more than once. The system will continue to schedule the check to run until the check reports success if both of the following are true:
- The check finds an exception during its very first run.
- The check is configured with an exception interval of the form EXCEPTINTERVAL(hhh:mm).
- hhh:mm provides a specific interval for the check to run. The check will run at refresh time and periodically afterwards at the interval specified. hhh indicates the number of hours, from 0 to 999. mm indicates the number of minutes, from 0 to 59.
The system starts processing the interval depending on whether you are using the SYNCVAL parameter:- If you are not using SYNCVAL or using SYNCVAL=SYSTEM, the specified interval time starts ticking away when a check finishes running.
- If you are using SYNCVAL={hh:mm|*:mm}, the specified interval time starts ticking away when the check starts running, to align it with the SYNCVAL start time.
- ONETIME specifies that the check should run only once, kicked off by refresh processing
or in alignment to a SYNCVAL value for the check.
- DATE=date
- Required parameter DATE specifies when you define the check you are adding or replacing. The date is specified in the format yyyymmdd. If the date specified on the ADDREPLACE parameter is earlier than the original date for the check, the system does not process the values specified on the ADDREPLACE parameter because it may no longer be appropriate for the check. When the date provided on a matching UPDATE, POLICY UPDATE or POLICY DELETE statement is older than this date, that policy statement is not applied to this check.
- REASON=reason
- Required parameter REASON specifies what the check routine validates. The value for
reason can be 1-126 text characters. You can specify these characters as:
- A single value enclosed in single quotes.
- Multiple values, where either each value is enclosed in single quotes or the group of values is enclosed is single quotes. The system will separate these values from each other by a blank. For example, both REASON='r1 r2 r3' and REASON=('r1','r2','r3') will both resolve to a reason of r1 r2 r3.
- PARM=parameter
- PARM specifies the check specific parameters being passed to the check you are adding or
replacing. The value for parameter can be 1-256 text characters. You can specify
these characters as:
- A single value enclosed in single quotes.
- Multiple values, where either each value is enclosed in single quotes or the group of values is enclosed is single quotes. The system will separate these values from each other by a comma. For example, both PARM='p1,p2,p3' and PARM=('p1','p2','p3') will both resolve to a parameter value of p1,p2,p3.
- GLOBAL
- Specifies that the check you are adding or replacing is global, which means that it runs on one system but reports on sysplex-wide values and practices. If you do not specify GLOBAL, the systems assumes that the check is local, which means that it will run on each system in the sysplex where it is active and enabled.
- ACTIVE|INACTIVE
- Use the ACTIVE and INACTIVE parameters to specify the state of the check you are adding or replacing. See Understanding check state and status. These parameters are equivalent to "ACTIVATE parameter" and "DEACTIVATE parameter".
- EXCEPTINTERVAL={SYSTEM|HALF|hhh:mm}
- EXCEPTINTERVAL specifies how often the check you are adding or replacing should run after
the check has found an exception. This parameter allows you to specify a shorter check interval for
checks that have found an exception.
- SYSTEM, which is the default, specifies that the EXCEPTINTERVAL is the same as the INTERVAL.
- HALF specifies that the exception interval is defined to be half of the normal interval.
For example, the exception interval will be set 30 seconds, if the normal interval is set to 1
minute.
Note that if you change the INTERVAL parameter for a check, the system will also recalculate the exception interval.
- hhh:mm provides a specific exception interval for the check. After raising an exception, the check will run at the exception interval specified. hhh indicates the number of hours, from 0 to 999. mm indicates the number of minutes, from 0 to 59.
The system starts processing the interval depending on whether you are using the SYNCVAL parameter:- If you are not using SYNCVAL or using SYNCVAL=SYSTEM, the specified interval time starts ticking away when a check finishes running.
- If you are using SYNCVAL={hh:mm|*:mm}, the specified interval time starts ticking away when the check starts running, to align it with the SYNCVAL start time.
- USS={NO|YES}
- USS specifies whether the check uses z/OS
UNIX System Services.
- NO, which is the default, specifies that your check does not require z/OS UNIX System Services.
- YES specifies that your check requires z/OS
UNIX System Services. If you specify USS=YES, the following occurs:
- IBM Health Checker for z/OS will wait for this check to complete before shutting down z/OS UNIX System Services
- This check will not run if z/OS UNIX System Services is down.
- VERBOSE={NO|YES}
- VERBOSE specifies the verbose mode desired for the check you are adding or replacing:
- NO specifies that you do not want to run in verbose mode.
- YES specifies that you want to run in verbose mode. Running in verbose mode you see
additional messages about non-exception conditions. These messages are only issued when the check is
in verbose mode.
Verbose mode does not take effect until you re-run the check or checks. For example, after you issue a command to turn verbose mode on, you could issue the
F hzsproc
command with the RUN parameter to run the check or checks with verbose mode on.
- ENTRYCODE=entrycode
- ENTRYCODE specifies an optional unique check entry value needed when a check routine contains multiple checks. This value is passed to the check routine in the field Pqe_EntryCode in mapping macro HZSPQE.
- ALLOWDYNSEV={NO|YES}
- Optional parameter ALLOWDYNSEV specifies whether this check can issue check exception
messages with a dynamically varying severity level.
- ALLOWDYNSEV=NO, which is the default, specifies that the check is not allowed to specify a dynamic severity. The system uses the SEVERITY defined for the check in either the HZSADDCK service or the ADD|ADDREPLACE,CHECK parameter of HZSPRMxx/MODIFY hzsproc.
- ALLOWDYNSEV=YES specifies that the check can specify the severity dynamically. A check defined
with ALLOWDYNSEV=YES can use the SEVERITY parameter on the HZSFMSG service (or HZSLFMSG_SEVERITY for
REXX service HZSLFMSG) to send check exception messages with a dynamic severity.
The severity specified dynamically on HZSFMSG or HZSLFMSG overrides the severity defined for the check in either the HZSADDCK service or the UPPDATE and ADD|ADDREPLACE,CHECK parameter of HZSPRMxx/MODIFY hzsproc.
- DOM={SYSTEM|CHECK}
- Optional parameter DOM specifies whether the check or the system delete the write to operator
(WTO) messages from previous check iterations using delete operator message (DOM) requests.
- DOM=SYSTEM, which is the default, indicates that the system issues DOM requests to delete any WTOs from previous check iterations just before the start of a new check iteration.
- DOM=CHECK indicates that the check is expected to issue its own DOM requests to delete previous
check exception WTOs using HZSFMSG REQUEST=DOM or HZSLFMSG_REQUEST=DOM, except in the following
cases, where the system will still take care of the DOMs:
- When a health check gets deactivated, deleted, or refreshed
- When IBM Health Checker for z/OS ends
- When a WTO was not related to a check exception. For example certain HZSFMSG REQUEST=HZSMSG WTO messages are not sent as check exceptions and will be DOMed by the system.
- ADD,PARMLIB
Adds one or more HZSPRMxx parmlib member suffixes to the list of suffixes the system uses to obtain check values. The system immediately processes the statements in the added parmlib members. You can specify a list of up to 124 suffixes. Note that you can only specify the ADD,PARMLIB statement in a F hzsproc command.ADD,PARMLIB=(suffix1,...,suffixn[,CHECK|C])
- CHECK|C
- Specifies that the system just check the syntax of the statements in the specified parmlib
members and not apply the contents of the statements.The system issues the following two messages to summarize
CHECK
findings for each HZSPRMxx parmlib member checked:
If the system finds errors as it checks an HZSPRMxx parmlib member (ASA020I), check the log for additional messages detailing the syntax problems found.ASA020I - SYNTAX CHECKING IS COMPLETE FOR PARMLIB MEMBER=memname. ERROR(S) WERE FOUND ASA021I - SYNTAX CHECKING IS COMPLETE FOR PARMLIB MEMBER=memname. NO ERRORS WERE FOUND
- REPLACE,PARMLIB
Replaces the list of HZSPRMxx parmlib members with the specified parmlib member suffixes. You can specify a list of up to 124 suffixes.REPLACE,PARMLIB=(suffix1,...,suffixn) [,{CHECKS|POLICY|ALL}]
REPLACE,PARMLIB first deletes applicable statements that had been processed from the current HZSPRMxx parmlib members and then replaces and processes the statements in the parmlib members specified in the list of suffixes. The system then applies the statements to any new checks.
You can use SET,PARMLIB as a synonym for REPLACE,PARMLIB.
- CHECKS
- Specifies that you want to delete check definitions added with ADD or ADDREPLACE CHECK statements when you issue this command to replace the list of HZSPRMxx parmlib members.
- POLICY
- Specifies that you want to delete existing POLICY statements and then add those in the parmlib members specified in the REPLACE,PARMLIB command. POLICY is the default.
- ALL
- Specifies that you want to replace both checks added with ADD | ADDREPLACE,CHECK and existing policy statements with those specified in the REPLACE,PARMLIB command. The system begins by deleting the checks added with ADD|ADDREPLACE CHECK and existing policy statements before replacing them.
- ACTIVATE,POLICY
ACTIVATE,POLICY=policyname
Specifies the 1-16 character name of the policy that you want to activate to make it the current, active policy. The policy stays in effect as the current active policy until you issue another
ACTIVATE,POLICY=policyname
command to activate a different policy.After you activate a policy, if you want to ensure that only the values from the new policy will be applied to checks, you must refresh all the relevant checks. Until you refresh the checks, the values being applied to checks will still include any values from the previous policy that are not contradicted by the new policy. See Some finer points of how policy values are applied.
- {ADD|ADDREPLACE},POLICY
Add or replace a policy statement in a policy. The check values in the policy or policy statement are applied whenever a check is added or refreshed. The check values on a new or replaced policy statement are applied when that policy statement is added or replaced.{ADD|ADDREPLACE} ,POLICY[=policyname][,STATEMENT=name],UPDATE,filters[,update_options],REASON=reason,DATE={date|(date,NOCHECK)} | ,POLICY[=policyname][,STATEMENT=name],DELETE,filters,REASON=reason,DATE={date|(date,NOCHECK)}
You must specify the "REASON parameter" and "DATE parameter" when you specify ADD, ADDREPLACE, or REMOVE,POLICY.
We recommend that you use the ADD | ADDREPLACE POLICY statements in the HZSPRMxx parmlib member rather than in the MODIFY command, because:- It is easy to exceed the number of characters allowed for a command with the POLICY statements.
- Changes made in the parmlib member will be applied at each restart of IBM Health Checker for z/OS.
- ADD
- Add the new policy statement that follows.
- ADDREPLACE
- Specifies that the system either add or replace the following policy statement, as appropriate. If the policy statement is new, the system will add it. If the policy statement exists already, the system will replace it with the one specified.
- POLICY=policyname
- The 1-16 character name of the policy in which you are adding or replacing policy statements.
The policy name can be up to 16 characters long.
If you do not specify a policy name, the system assigns a default name of DEFAULT for your policy. Use the DISPLAY POLICY command to find the name of a policy.
- STATEMENTNAME|STATEMENT|STMT =stmtname
- STATEMENTNAME specifies the name of the policy statement. The statement name can be up to 16
characters long.
If you do not specify the STATEMENTNAME parameter, the system creates a decimal number name for your statement. For example, the system might create a statement name such as 1 or 2 for a statement. The number can be more than one digit.
- UPDATE
- Create a policy statement that will update the specified check or checks. You must specify the REASON and DATE parameters. See the UPDATE parameter.
- DELETE
- Create a policy statement that will delete the specified check or checks. You must specify the REASON and DATE parameters.
- filters
- You must specify filter CHECK=(check_owner,check_name) with ADD | ADDREPLACE POLICY. Other filters are optional. See filters.
- REASON=reason
- See the "REASON parameter".
- DATE={date|(date,NOCHECK)}
- DATE specifies when the policy statement was created. The date is specified in the format
yyyymmdd. If the date specified on the policy statement is earlier than the date
for the check, the system does not process the values specified on the policy statement because the
policy statement may no longer be appropriate for the updated check.
- NOCHECK
- By default, IBM Health Checker for z/OS verifies the date for the policy statement, making sure that it is equal to or newer than the date for the check that the statement applies to. Use NOCHECK to bypass date verification so that you do not have to update the policy statement date for minor changes to a check.
- REMOVE ,POLICY
Remove a policy statement. The check values on the policy statements are applied whenever a check is added or refreshed. The check values on a new or replaced policy or policy statement are applied when that policy statement is added or replaced.REMOVE,POLICY[=policyname],STATEMENT=name
- REMOVE
- Remove the named policy statement.
- POLICY=policyname
- Specifies the 1-16 character name of the policy for which you are removing a policy statement.
The policy name can be up to 16 characters long.
If you do not specify a policy name, the system assigns a default name of DEFAULT for your policy. Use the DISPLAY POLICY command to find the name of a policy.
- STATEMENTNAME|STATEMENT|STMT =stmtname
- STATEMENTNAME specifies the name of the policy statement. The statement name can be up to 16 characters long.
- POLICY=*,STMT=01 would remove all 01 statements from all policies.
- POLICY=POL1,STMT=S* would remove from policy POL1 all statements with names beginning with S.
- POLICY=*,STMT=S* would remove all policy statements starting with S from all policies.
- WHEN (whenexpr[[,]whenexpr...[,]whenexpr])
Conditionally apply HZSPRMxx statements in a parmlib member. The following example shows a WHEN statement containing a policy statement specifying that CHECK1 be deactivated for system SYS3:WHEN (whenexpr [[,]whenexpr ... [,]whenexpr]) [DO] stmts [END]
The system evaluates the WHEN conditions (whenexpr) when it reads the HZSPRMxx parmlib member. Then, if the conditions specified in the WHEN statement are met, the stmts are applied as appropriate for the type of statement (see Using WHEN to apply statements conditionally).WHEN (SYSNAME=SYS3) DO ADD POLICY UPDATE CHECK(OWNER1,CHECK1) INACTIVE REASON(’Do not need check 1 on system SYS3’) DATE(20160104) END
If the conditions in the WHEN statement are NOT met, the system ignores the statements within the scope of the WHEN statement and skips to the end of this WHEN statement before processing further statements. Note that skipped statements are still syntax-checked, however.
Note that you can only specify a WHEN statement in an HZSPRMxx parmlib member - you can not specify a WHEN statement on a MODIFY hzsproc command.