Starting, configuring, and stopping hardware event data collection

Use the MODIFY hisproc command to manage collection of hardware event data for System z10 or later machines. Use F hisproc,BEGIN to configure and start a run of data collection, and F hisproc,END to stop the run. You may start each run of hardware data collection either through explicit issuance of HIS commands, or through use of system automation.

During a run of hardware data collection, the system writes the data to z/OS UNIX System Services output files and to SMF record type 113. The system writes the raw data to SMF record type 113 at the start, the end, and defined intervals during the data collection run, and writes different types of data to the z/OS UNIX System Services output files at the end of the run. For more information about the different z/OS UNIX System Services output files, see Accessing the output from a hardware event data collection run.

If there is a significant state change within the system, such as a CPU capability change during a collection run, the STATECHANGE parameter from the MODIFY hisproc command will determine the appropriate action. When the action is SAVE (the default), there will be two SMF 113 records at every state change, one for the end of the previous state and one for the start of the new state. There will also be an additional set of z/OS UNIX output files for each detected state change. Each z/OS UNIX output file only represents an interval of time between the start and the end of the same system state. Each interval of a collection run has a unique set of z/OS UNIX output files, determined by the sequence number as part of the filename (the xxx section of the filename). If a .MAP file is to be generated for the collection run, one is not generated at a every state change. A .MAP file is only generated at the end of a collection run with a sequence number representing the last collection run interval. The group of files relating to the same run can be identified through the file prefix (SYSHISyyyymmdd.hhmmss).

Before you issue the F hisproc,BEGIN command to configure and start hardware event gathering on a system, you must do some set up steps. See Setting up hardware event data collection.

Note:

It is important to assign a sufficiently high dispatch priority to the instrumentation started task hisproc, so that the task can write the sampling data to the .SMP output files in a timely manner.
The sampling frequency is the number of samples per second regardless of processor model. The relative impact of sampling at the default rate is greater for slower processors. For slower sub-capacity models, a lower sampling frequency might be appropriate. For more information, see the SAMPFREQ parameter description.

See Accessing the output from a hardware event data collection run for information on the different files the HIS Profiler generates, depending on the F hisproc,BEGIN parameters you specify.

If you configure a new processor online in a system after you've already issued the F hisproc,BEGIN command to start a data collection run for that system, HIS might not collect data for that processor. To ensure that data is collected for all the processors on a system, bring the processors online before beginning a hardware data event collection run. The system does not collect data on a processor that is configured offline.

Note that z/OS® IRD processor management can configure processors offline or online automatically. A processor is online at the start of the instrumentation run, but it might be configured offline (and sometimes online again) during the run. The system does not collect data on the offline processor.

 
F hisproc,{BEGIN|B}
                    [,{TITLE|TT}='textdata']
                    [,PATH='pathname']
                    [,{DDNAME|DD}=ddname]
                    [,{DURATION|DUR}=duration_value]
                    [,{STATECHANGE|SC}={SAVE|STOP|IGNORE}]
                    [,{DATALOSS|DL}={IGNORE|STOP}]
 
                    [,SMP={YES|NO}]
                           [,{SAMPTYPE|ST}=samptype|PERSIST|NONE]
                           [,{BUFCNT|BUF}={bufcnt|PERSIST]
                           [,{SAMPFREQ|SF}=freq|PERSIST]
 
                    [,CNT={YES|NO}]
                           [,{CNTSET|CTRSET|CTR}={COMPLETE
                                                  |SOFTWARE
                                                  |HARDWARE
                                                  |(ctr1,ctr2,…ctrn)}]
                           [,{CNTINTVAL|CI|SMFINTVAL|SI}={SYNC|intv}]
                           [,CNTFILE={YES|NO}]
 
                    [,MAP={YES|NO}]
                           [,{MAPASID|MAS}={ALL|(asid1,asid2,…asidn)}]
                           [,{MAPJOB|MJOB}=(job1,job2,…jobn)]
                           [,{MAPVERBOSE|MAPV}]
 
                    [,{CNTONLY|CTRONLY|MAPONLY}]
 
           {END|E}
 
           {SERVICE|S}
                    [[,{DDNAME|DD}=ddname]
                     [,{BUFCNT|BUF}={bufcnt|PERSIST]
                     [,{SAMPFREQ|SF}=freq|PERSIST]
                     [,{SAMPTYPE|ST}=samptype|PERSIST|NONE]]
                    [,{REFRESH|REFR}]

The parameters are:

hisproc

The name of the hardware instrumentation services (HIS) catalogued startup procedure.

{BEGIN|B} or {END|E} or {SERVICE|S}

You must specify either BEGIN or END or SERVICE on the F hisproc command to begin or end a run of hardware event data collection, or update the service parameters, for a system:

BEGIN|B

Specifies that the system begin a HIS Profiler collection run. Note that you must first start the HIS address space with the START hisproc command before you can start the HIS Profiler. Note that any service parameters specified will be accepted and will be used as the new service parameter values.

END|E

Specifies that the system end a HIS Profiler collection run. As part of the end processing, the system writes the hardware data to your z/OS UNIX System Services output files and writes the last SMF record type 113 to the SMF data set.

Note that while both F hisproc,END and STOP hisproc end the data collection run, the two commands are different:

Using F hisproc,END ends the HIS Profiler collection. You must issue F hisproc,BEGIN command to restart a HIS Profiler collection.
Using STOP hisproc both ends the HIS Profiler collection and stops the HIS address space, which also disables the HISSERV service. You must reissue the START hisproc command before starting the HIS Profiler with the F hisproc,BEGIN command, as well as any HISSERV exploiter.

SERVICE|S

Specifies that the system should update the service parameters for all exploiters of the HISSERV service. If the HIS Profiler run is currently collecting instrumentation data, it will be notified of the change and a state change event will occur.

TITLE|TT='textdata'

Optional parameter specifying up to 32 characters of text data meaningful to the user. This data will be displayed in the z/OS UNIX System Services .CNT output file. For example, you might use this field to create an eye catcher to identify the reason for a hardware data collection run. The text data must be enclosed in single quotation marks.

PATH='pathname'

Specifies the z/OS UNIX System Services path (in a local file system) where you want the system to write the collected hardware event data for one run. The system creates all the output files (the .MAP. .CNT and .SMP files) and writes the collected data to the output files at the end of a run. This parameter is required, unless you have already set up the file path using the HOME keyword in the OMVS segment of an

ADDUSER
hisproc

or ALTUSER hisproc command. See Setting up hardware event data collection for more information.

The pathname must be enclosed in single quotation marks and can be up to 64 characters. For example, you could specify the following for pathname:

PATH='.', which means to use the current working directory.
PATH='/u/john', which means to use the absolute directory /u/john.
PATH='user/mary', which means to use the relative directory user/mary, which is relative to the current working directory.

If instrumentation is to be run concurrently on multiple LPARs with a shared file system, a unique path that is specified by the PATH parameter must be created for each LPAR sharing the file system.

See Accessing the output from a hardware event data collection run for information on the files the HIS Profiler generates at the z/OS UNIX System Services path.

{DDNAME|DD}=ddname

Optional parameter specifying the 1- to 8-character name identifying the job control language (JCL) data definition (DD) statement that defines a command file for HIS MODIFY hisproc parameters. The command file referenced contains parameters for HIS Profiler collection runs or for a service update (depending on whether it is a BEGIN or SERVICE request) which are set up the same way they would appear in the MODIFY command - the same rules and formatting apply to the command file that you would use in the console command. The command file gives you an alternative to specifying data collection options in a MODIFY hisproc command, which can be useful if you have difficulty fitting all the desired parameters on the command.

Note that duplicate parameters on the MODIFY hisproc command and in the command file are not allowed and will be flagged as errors.

When the system processes the DDNAME parameter, the system takes the character string on each line and concatenates them into one command string for parsing. It then merges the command file contents with the parameters specified on the MODIFY hisproc command used to process the command. Thus, you can specify some of your data collection options in the command file, and some in the MODIFY hisproc command. For example, you can put all the constant parameters in the command file and dynamic parameters on the command line. For example, TITLE can be used to document the reason for the run on the command line.

The statements in the command file are normal MODIFY hisproc parameters, without the MODIFY hisproc,BEGIN or MODIFY hisproc,SERVICE heading.

The following shows an example of valid command file contents assuming a MODIFY hisproc,BEGIN,DDNAME=ddname1 heading:

   PATH='/user/john',CTRSET=(BASIC,PROB),
   BUFCNT=PERSIST,   SAMPTYPE=BASIC,  
   SAMPFREQ=850000,DATALOSS=IGNORE, 
   MAPASID=(7,0E,E1D),
   MAPJOB=(PROG*,DB*,GRS,JE??)

These commands would be valid in a command file for a MODIFY hisproc,SERVICE,DDNAME=ddname2 heading :

   
   SAMPTYPE=BASIC,  
   SAMPFREQ=130000

Use the following syntax rules for the command file:

The parameters specified can reside on multiple lines of the command file.
You must separate keywords with commas.
The system treats a blank character between any two non-blank characters on the same line (unless the blank is quoted within quotation marks) as the end of the command.
You can use columns 1-72 of each line.
A quoted string (a title or path name, for example) can not span more than one line.
Parameters and values in the command file must be in UPPER case, unless the parameter value is a quoted string.

In order to use a command file for MODIFY hisproc, you must specify the ddname in the HIS started catalogued start up procedure hisproc. The following example shows how to use a command file named CMDFILE for the MODIFY hisproc command. In the example, DDNAME1 specifies a command file CMDFILE, which is a member of SAMPLING.PROCLIB and contains some or all of the parameters for the MODIFY hisproc command. Likewise, DDNAME2 specifies command file CMDFILE2 which would contain a different set of parameters.

//HISPROC  PROC                                             
//HISPROC  EXEC PGM=HISINIT,REGION=0K,TIME=NOLIMIT          
//DDNAME1  DD DSN=SAMPLING.PROCLIB(CMDFILE),DISP=SHR         
//DDNAME2  DD DSN=SAMPLING.PROCLIB(CMDFILE2),DISP=SHR   
//SYSPRINT DD SYSOUT=*

The command file must have a RECFM format of LRECL=80 fixed length record.

Note that the same syntax rules apply to the parameters in the command file as to a MODIFY hisproc command. The system flags duplicate parameters or mutually exclusive parameters entered in the MODIFY hisproc command and the command file as errors and you will receive an error message.

There is no default for the DDNAME.

{DURATION|DUR}=duration_value

Optional parameter specifying the duration, in minutes, that you want the hardware event data collection run to last. At the end of this period, data collection stops automatically.

The default DURATION for instruction address sampling is 10 minutes. If request is for event counters only (CTRONLY), the default DURATION is unlimited. To stop an unlimited data collection run, you must explicitly specify one of the following commands:

F hisproc,END
STOP hisproc

Value range: 1–1440 (minutes)

{STATECHANGE|SC}={SAVE|STOP|IGNORE}

Optional parameter specifying the action you want the system to take when a significant change to the system is detected. An example of a significant state change would be if the capability of a CPU has changed. You can specify the following for STATECHANGE:

SAVE, the current run of hardware event data collection will save all data collected as if the duration of the run has expired. It will then resume collecting hardware event data in the new state for the remaining duration of the current collection run.
STOP, the current run of hardware event data collection for a system is ended as if the duration of the run has expired.
IGNORE, the current run of hardware event data collection continues as if no state change had been detected.

Default: SAVE

{DATALOSS|DL}={IGNORE|STOP}

Optional keyword specifying the action you want the system to take if data loss occurs during the instrumentation run. Data loss can occur from any of the following events:

Sampling buffer overflow condition
Loss of Sample Data Measurement Alert (raised by hardware)
Loss of Counter Data Measurement Alert (raised by hardware)

You can specify the following values for the DATALOSS parameter:

IGNORE |I: The system continues with the instrumentation run if data loss occurs.
STOP |S: The system stops the instrumentation run if data loss occurs.

You can reduce the chances of losing data in the event of a buffer overflow by either allocating more buffers for data collection or increasing the priority of the HIS started task.

A Loss of Sample Data Measurement Alert and a Loss of Counter Data Measurement Alert are determined by the hardware and cannot be predicted nor prevented.

Default: IGNORE

SMP={YES|NO}

Specifies that you want to collect sample data. The default is YES.

{SAMPTYPE|ST}={samptype|PERSIST|NONE}

Optional parameter that specifies the sampling functions to be performed. This parameter is only valid when SMP=YES is in effect.

Whether this option is specified or omitted under the MODIFY hisproc,BEGIN or the MODIFY hisproc,SERVICE heading, the change is global to all HISSERV exploiters.

samptype

The sampling functions (samptype) supported include:

BASIC or B: for basic sampling functions.
DIAG or D: for basic and diagnostic sampling. Diagnostic sampling provides additional information over what is available in basic sampling. When diagnostic sampling is requested, basic sampling is also automatically selected. To use the diagnostic sampling function, you must first authorize to the diagnostic sampling facilities on the SE console. Unless instructed by IBM, use ST=Basic.
For information about how to set up the authorization of the sampling facilities through the support element (SE) console, see Support Element Operations Guide for System z10 machine on the Resource Link home page.

PERSIST

The sampling functions to be performed are not changed from its prior value.

NONE

No sampling functions will be performed, and no HISSERV exploiters will be authorized to collect sampling data.

Example: SAMPTYPE=DIAG

Default: Basic. If you do not specify SAMPTYPE, the default is used.

{BUFCNT|BUF}={bufcnt|PERSIST}

Optional parameter that specifies the number of sampling buffers. This parameter is only valid when SMP=YES is in effect.

Whether this option is specified or omitted under the MODIFY hisproc,BEGIN or the MODIFY hisproc,SERVICE heading, the change is global to all HISSERV exploiters.

bufcnt

The number of sampling buffers (in 4K pages) per processor for the system. A range of values between 4 - 1024 (pages) is supported.

The total number of sampling buffers the system uses is calculated from the BUFCNT specified, as follows:

 (BUFCNT * Number of active processors in the configuration)

If you specify too small a value for BUFCNT and the system runs out of buffer space, you might lose some sample data. If you specify a high sampling frequency on the SAMPFREQ parameter, HIS will consume more sampling buffer space and you might need a higher value for BUFCNT to prevent loss of samples.

PERSIST

The number of sampling buffers is not changed from its prior value.

Default: If you do not specify BUFCNT, the system calculates the number of buffers needed using the number of processors in the configuration and the sampling frequency in effect (SAMPFREQ).

{SAMPFREQ|SF}=freq|PERSIST}

Optional parameter that specifies the frequency for the sampling functions. This parameter is only valid when SMP=YES is in effect.

Whether this option is specified or omitted under the MODIFY hisproc,BEGIN or the MODIFY hisproc,SERVICE heading, the change is global to all HISSERV exploiters.

freq: is the total number of samples to be taken in a minute on all active processors in the configuration. For example, a freq value of 500000 specifies a sampling frequency of 500,000 samples per minute.
Note that the effective sampling rate is usually smaller than the specified SAMPFREQ for LPARs that share the processors. Samples are captured only on logical processors that are actively in use. (A waiting shared logical processor does not produce samples.)
PERSIST: The sampling frequency is not changed from its prior value.

Default: 800000, which is equivalent to 8 million samples in 10 minutes. This default may be aggressive for slower sub-capacity models. A less aggressive value of 130 000 should be used if there is an unacceptable performance degradation when the default value is used. The DURATION can be extended as needed if more samples are required. For example, to achieve 8 million samples with a sample frequency of 130 000, the duration of the sampling run would be 60 minutes.

If you do not specify SAMPFREQ, the default is used.

CNT={YES|NO}

Specifies that you want to collect event counter set data. The default is YES.

{CNTSET|CTRSET|CTR}={COMPLETE|SOFTWARE|HARDWARE|(ctr1,ctr2,…ctrn)}

Optional parameter specifying the set of counters you want to collect. CTRSET and CTR are aliases of CNTSET. This parameter is only valid when CNT=YES is in effect.

COMPLETE

When you specify COMPLETE the system collects event counters for all available counter sets. For example, if you have installed and authorized only the basic and problem-state counter sets on your system, a specification of CNTSET=COMPLETE, results in basic and problem-state counter set events being collected. Be aware that specifying CNTSET=COMPLETE also means collecting event counters that are not currently defined, but may be defined in the future. It is possible that event counter sets in the future may have unforeseen performance impacts on the system. Note that COMPLETE, is not enclosed in parentheses.

SOFTWARE

When you specify SOFTWARE, the system collects all software related event counter sets. Any future counter set defined as a software counter set may have unforeseen performance impact on the system. Note that SOFTWARE is not enclosed in parentheses. CNTSET=SOFTWARE is currently equivalent to CNTSET=(Z).

HARDWARE

When you specify HARDWARE, the system collects all hardware related event counter sets. Any future counter set defined as a hardware counter set will have little unforeseen performance impact on the system. Note that HARDWARE is not enclosed in parentheses. CNTSET=ALL is an alias to CNTSET=HARDWARE. CNTSET=HARDWARE is currently equivalent to CNTSET=(B,P,C,E).

(ctr1,ctr2,…ctrn)

You can also specify a list of counter sets to collect. This comma separated list can be one or more of the following counter sets:

B or BASIC for basic: This is a hardware CPUcounter set and includes architected system activities, such as cycle count, instruction count, level 1 cache misses, for example, for a CPU in either the problem or supervisor state.
P or PROB for problem state: This is a CPU hardware counter set and includes the architected system activities only when the CPU is in the problem state.
C or Crypto for crypto: This is a hardware CPU counter set and includes the architected crypto activities, such as function count, cycle count, blocked function count, and blocked cycle count for each of the PRNG, SHA, DEA, and AES functions.
E or EXT for extended: This is a hardware CPUcounter set and includes model dependent counters described in model dependent system library publications. For more information about the extended counters for the supported counter version number for each model, see the extended counter definition in The CPU-Measurement Facility available on the Resource Link home page.
Z or ZOS for z/OS: This is a software CPUcounter set and includes counters for z/OS related activities. Enabling the z/OS counter set incurs a slightly higher performance overhead than the hardware counter sets. The z/OS counter set uses the Enhanced Monitor Facility. Note the z/OS counters are not defined and are primarily used for IBM diagnostic purposes.
MTD or MTDIAG for MT-diagnostic: This is a hardware core counter set and includes model dependent counters described in model dependent system library publications. For more information about the MT-diagnostic counters for the supported counter version number for each model, see the MT-diagnostic counter definition in The CPU-Measurement Facility available on the Resource Link home page.

Default: If you do not specify CNTSET, HIS uses the B (basic) and P (problem state) counter sets. For example, use CNTSET=(B,P,E) to specify three counter sets (Basic, Problem state, and extended), and use CNTSET=(BASIC,E) to specify two counter sets (BASIC and extended).

{CNTINTVAL|CI|SMFINTVAL|SI}={SYNC|intv}

Optional parameter that specifies the interval at which SMF record type 113 records are recorded. CI, SMFINTVAL, and SI are aliases of CNTINTVAL. This parameter is only valid when CNT=YES is in effect. The following values are accepted:

SYNC: Specifies that the SMF record type 113 should be recorded in sync with the SMF global recording interval. The global recording interval is set by parameters INTVAL and SYNCVAL in parmlib member SMFPRMxx. Note that if SMF is not active, global recording interval processing is disabled or there is some other error that prevents HIS to sync with the SMF global recording interval, no interval SMF record type 113 will be recorded. Receiving messages IEE500I or IEE068A is an example of when no SMF record type 113 will be recorded. For more information on the SMF global recording interval, see INTVAL and SYNCVAL - Performing interval accounting in z/OS MVS System Management Facilities (SMF).
intv: An interval, in minutes, that you want to record interval SMF record type 113 records. The acceptable value range is 1 - 60.

If CNTINTVAL is not specified, the default is 15.

CNTFILE={YES|NO}

Optional parameter that specifies whether event counter set data is to be written to z/OS UNIX System Services .CNT output files. This parameter is only valid when CNT=YES is in effect.

Default: YES

MAP={YES|NO}

Specifies that you want to collect load module mapping information. The default value is NO.

{MAPASID|MAS}={ALL|(asid1,asid2,…asidn)}

Optional parameter that specifies a list of address space IDs (ASIDs), in hexadecimal, to identify the address spaces for which you want to collect private load module map data. HIS will collect the virtual storage addresses of modules loaded into private virtual storage for the specified ASIDs that are not terminating, swapping, swapped, or inactive. This parameter is only valid when you specify MAP=YES.

Acceptable hexadecimal values are between X'1' and X'7FFF'.

You can specify up to 32 ASIDs on the MAPASID parameter.

If you need to collect data from more than 32 address spaces, you can use the MAPJOB parameter in place of or in addition to the MAPASID parameter.
The system supports a total of up to 128 address spaces, including those specified in both the MAPASID and MAPJOB parameters. If you need load module map data for more than 128 address spaces, specify MAPASID=ALL. When you specify MAPASID=ALL, the load module map data for all active ASIDs can be returned. When collecting data for IBM, specify MAPASID=ALL, unless directed otherwise.
If you specify MAPASID with any value, you will always map the nucleus and LPA areas as well.
You may want to enable tracking of directed load modules with the SETPROG TRACKDIRLOAD command so that your results are complete. See Tracking directed load modules

Examples:

MAPASID=(7,8,32)
MAPASID=ALL

Default: None.

{MAPJOB|MJOB}=(job1,job2,…jobn)

Optional parameter specifying a list of job names for which HIS will collect the virtual storage addresses of modules loaded into private virtual storage. HIS collects the virtual storage addresses for jobs that are not terminating, swapping, swapped, or inactive. The system ignores duplicate, invalid, or inactive job names specified. This parameter is only valid when you specify MAP=YES.

Specify job names with 1-8 characters, following the rules for a valid job name. You can use wildcard characters * and ? for pattern matching of job names. See Using wildcards in commands for more information.

You can specify up to 32 job names, including all the pattern matches from wildcard characters. Note that using wildcard characters can result in requesting more than 32 physical jobs.

When you specify job names on MAPJOB, the system converts each active job name into one or more ASIDs. If the job is not active when the system does the load module mapping, the system will not produce load module information for that job. The system supports a total of up to 128 address spaces, including those specified on both the MAPASID and MAPJOB parameters. If you specify more than 128 address spaces, the system produces load module mapping data for the first 128 address spaces and ignores the rest. For example, MAPJOB=(*) might produce load module mapping information for 128 active address spaces, starting with ASID 1. If you need load module map data for more than 128 address spaces, specify MAPASID=ALL. When you specify MAPASID=ALL, the load module map data for all active ASIDs can be returned. If you specify MAPJOB with any value, you will always map the nucleus and LPA areas as well.

You may want to enable tracking of directed load modules with the SETPROG TRACKDIRLOAD command so that your results are complete. See Tracking directed load modules.

Examples:

MAPJOB=(task1,grs,omvs,db*,task2)
MAPJOB=(o*s)
MAPJOB=(JOB1??,JE*)

Default: None.

{MAPVERBOSE|MAPV}

Optional keyword specifying that you want the system to produce additional diagnostic information about any errors encountered during the load module mapping phase of data collection. MAPVERBOSE specifies that the system issues system messages to the job log if it encounters multiple errors during load module mapping. This parameter is only valid when you specify MAP=YES.

You can only specify MAPVERBOSE if you also activate the load module mapping with the MAPONLY, MAPASID, or MAPJOB parameters. If you specify MAPVERBOSE without specifying one of these load module mapping parameters, the system ignores the MAPVERBOSE parameter.

Default: None; no load module mapping diagnostic information is collected.

{CNTONLY|CTRONLY|MAPONLY}

These optional keywords allow you to limit collection, as follows:

CNTONLY|CTRONLY

Specifies that you want to collect only event counter set data. Data collection for instruction address sampling is not activated. The system generates only a .CNT z/OS UNIX System Services output file. (The system does not generate .SMP and .MAP output files if you specify CNTONLY.) CTRONLY is an alias of CNTONLY.

When this keyword is specified, you cannot specify keywords associated with instruction sampling, such as SAMPTYPE and SAMPFREQ.

Keywords allowed with CNTONLY include TITLE, PATH, DURATION, CNTSET.

The CNTONLY parameter is equivalent to CNT=YES,SMP=NO,MAP=NO.

MAPONLY

Specifies that you want to collect only load module mapping information. Data collection event counter sets and instruction address sampling is not activated. The system generates only a .MAP z/OS UNIX System Services output file. (The system does not generate .SMP and .CNT output files if you specify MAPONLY.)

When you specify MAPONLY, you must also specify MAPASID or MAPJOB (or both) to identify the address spaces for which you want private load module map data. You cannot specify keywords associated with sampling and counter sets, such as SAMPTYPE, SAMPFREQ, or CNTSET.

Keywords allowed with MAPONLY include TITLE, PATH, MAPASID, MAPJOB.

The MAPONLY parameter is equivalent to CNT=NO,SMP=NO,MAP=YES.

{REFRESH|REFR}

Optional parameter instructing the system to refresh the HISSERV service. A refresh of the service will allow the service to begin using any counter set or sample type recently authorized through the Hardware Management Console. REFRESH is mutually exclusive with all other service parameters.

Example 1: Start the HIS Profiler data collection using defaults, including SMF data, and create .CNT and SMP.cpu#. files. By default, the following instrumentation data are captured besides SMF data:

Data from the basic and problem state counter sets
Basic sampling data

Because no service parameters were explicitly specified with the PERSIST option, all service parameters will be changed to the defaults.

MODIFY hisproc,BEGIN

Example 2: Start the HIS Profiler for data collection that runs for 12 minutes, collects load module mapping information for jobs PGMA and PGMB. collects SMF data and creates .MAP, .CNT and SMP.cpu#. files. Because all service parameters are explicitly specified with the PERSIST option, they will remain at their prior values.

MODIFY hisproc,BEGIN,DURATION=12,MAPJOB=(PGMA,PGMB),BUFCNT=PERSIST,
SAMPTYPE=PERSIST,SAMPFREQ=PERSIST

Example 3: End the HIS Profiler for data collection:

MODIFY hisproc,END

Example 4: Refresh HISSERV to begin using the counter sets and sample types that were recently authorized through the Hardware Management Console, and then increase the buffer count to allow for additional data. SAMPREQ and SAMPTYPE will be implicitly changed to their default values.

MODIFY hisproc,SERVICE,REFRESH
MODIFY hisproc,SERVICE,BUFCNT=100

Example 5: Direct HISSERV to stop generating sampling data for profilers requesting it. These changes are global and will affect all exploiters. BUFCNT and SAMPFREQ are specified as PERSIST to maintain their values.

MODIFY hisproc,SERVICE,SAMPTYPE=NONE,BUFCNT=PERSIST,SAMPFREQ=PERSIST

Example 6: Direct HISSERV to generate basic sampling data, the default, at a frequency of 100,000 samples per minute, and use the default buffer count. These changes are global and will affect all exploiters.

MODIFY hisproc,SERVICE,SAMPFREQ=100000

Example 7: Direct the HIS Profiler to begin collecting just counter data for problem diagnosis for IBM. These specific options may be the most commonly requested by IBM. All HIS exploiters are affected. This particular command labels the measurement 'Counters Only', requests data for basic and extended counter sets, sends the output to the .CNT file in the /HIS OMVS directory, (no .MAP or .SMP files are produced). Data collection for instruction address sampling is not activated, and the SAMPTYPE, SAMPFREQ,,and BUFCNT values have been preserved with the PERSIST option. SMF record type 113 will be recorded in sync with the SMF global recording interval, and this current run will save all data collected as if the duration of the run has expired. It will then resume collecting hardware event data in the new state until a MODIFY hisproc,END command is issued.

MODIFY hisproc,BEGIN,TT='Counters Only',PATH='/HIS',CNTONLY,CNTSET=(B,E),SI=SYNC,
SC=SAVE,SAMPTYPE=PERSIST,SAMPFREQ=PERSIST,
BUFCNT=PERSIST

Example 8: Direct the HIS Profiler to begin collecting extensive data for problem diagnosis for IBM. These specific options may be the most commonly requested by IBM. All HIS exploiters are affected by the MODIFY hisproc,BEGIN command. This command labels the measurement 'FOR IBM', sends the output to the /HIS OMVS directory, requests data for basic, problem, cryptographic, and extended counter sets, requests a map of all swapped in address spaces, and uses a buffer count of 1024 4K buffers. The recommended buffer count value is 1024 for minimal overhead at the expense of more storage (1024 4K blocks per processor.) The sampling data is basic, with the frequency of 800,000 samplings per minute and will run for 10 minutes.

MODIFY hisproc,BEGIN,TT='FOR IBM',path=/HIS,CNTSET=(B,P,C,E),MAS=ALL,BUF=1024,ST=B,
SF=800000,DUR=10