Specifying parameters for the SMF data set dump program

Parameters for the SMF data set dump program (IFASMFDP)

INDD(ddname,OPTIONS(data))

Describes the input data set, where ddname is the data definition name (DDNAME) of the data set and data can be any one of the following:

ddname

Specifies the data definition name (DDNAME) of the input data set.

data

Specifies one of the following processing options:

DUMP

Indicates that the input data set is to be read or copied without being reset.

CLEAR

Indicates that the input data set is to be reset and preformatted. The information on the data set is not copied and therefore lost.

ALL

Indicates both the DUMP and CLEAR options.

If INDD is not specified, the default is: INDD(DUMPIN,OPTIONS(ALL))

If DUMP or ALL is specified, a summary activity report is written if at least one record was read or written. For more information, see Summary activity report.

OUTDD(ddname,TYPE(list))

OUTDD(ddname,NOTYPE(list))

Describes the output data set, where ddname is the data definition name (DDNAME) of the output data set. TYPE indicates that the record types and subtypes specified in list are to be included in the output data set. NOTYPE indicates that the record types and subtypes specified in list are to be excluded from the output data set. The list variable can be any record type and subtype or combination of records; the record types and subtypes can be specified individually or as a range. For example, TYPE(2,4:7,9,30(2,4:6)) indicates that record types 2, 4, 5, 6, 7, 9, and subtypes 2, 4, 5, and 6 of record type 30 record are to be included in the output data set. NOTYPE(30(1,3:5)) indicates that subtypes 1, 3, 4, and 5 of record type 30 are to be excluded from the output data set.

Note: IFASMFDP does not support subtype selection for type 90 records. See Record type 90 (X'5A') — System status for more information.

If OUTDD is not specified, the default is OUTDD(DUMPOUT,TYPE(000:255)), which specifies that all record types and subtypes are to be included in the output data set.

If both TYPE and NOTYPE are specified for the same data set, the first valid specification is used. If a syntax error occurs in the OUTDD option and any INDD option specified ALL, DUMP, or CLEAR, the job is terminated.

DATE({yyddd|yyyyddd},{yyddd|yyyyddd})

Specifies the start and end date for the period for which records are to be written, where yy is the last two digits of the year, yyyy is the year digits of the year, and ddd is the Julian date. If only the last two digits of the year are specified, the first two digits defaults to 19. For example, DATE(92001,92366) indicates only records from January 1, 1992 to December 31, 1992 are to be written. The value for ddd cannot exceed 366. If DATE is specified, both a start value and an end value must be specified.

If DATE is not specified, the default is: DATE(1900000,2099366)

START(hhmm)

Specifies that only those records that were recorded at and after the START time and before the END time are to be written, where hh is the hours and mm is the minutes (based on a 24-hour clock).

If START is not specified, the default is: START(0000)

END(hhmm)

Specifies that only those records that were recorded after the START time and before the END time are to be written, where hh is the hours and mm is the minutes (based on a 24-hour clock). If END is not specified, the default is: END(2400)

SID(xxxx)

Specifies that only records written by the operating system with the specified system identifier can be written to the output data set, where xxxx, which indicates the system identifier, can be any one to four alphameric characters. SID can be specified for each system the SMF data set dump program is expected to handle. If SID is not specified, records pertaining to any operating system are written.

ABEND(RETRY|NORETRY)

Specifies whether the SMF data set dump program attempts to recover from an abend (abnormal end of task). When specified, this option overrides the SMF parmlib option (DUMPABND).

If the RETRY parameter is issued, then the SMF data set dump program attempts to recover from the abend.

If the NORETRY parameter is issued, then the SMF data set dump program terminates after the abend has occurred. The SMF data set dump program overrides NORETRY when, while SMF dump is dumping and clearing the input data set, an ABEND occurs after the input data set has been cleared. In this case, the SMF data set dump program tries to recover from the ABEND to prevent the deletion of the output data set and the loss of SMF data when the SMF data set dump program abnormally ends.

USER1(name)

Specifies the name of a installation-written exit routine that is given control after each record is read and the counters incremented. This exit does not receive control for records that contain an extended header. See the Standard and extended SMF record headers section for more information on the types of SMF headers. The parameter list pointed to by register 1 contains the address of the 3-word user work area in word 1, the address of the SMF record in word 2, and the address of the INDD ddname in word 3.

The exit routine must set a return code in register 15 before passing control back to the SMF data set dump program. The return codes are as follows:

Code

Meaning

00

Normal processing should continue

04

The record should not be written to the output data set.

Any other return code indicates that a problem was encountered and that the SMF data set dump program is not to invoke the exit again.

USER2(name)

Specifies the name of the installation-written exit routine that is given control only when the SMF data set dump program selects a record to be written. This exit does not receive control for records that contain an extended header. See Standard and extended SMF record headers for more information on the types of SMF headers. The parameter list pointed to by register 1 contains the address of the 3-word user work area in word 1, the address of the SMF record in word 2, and the address of the OUTDD ddname in word 3. This exit is always called by the SMF data set dump program before any records are written.

The return codes are the same as those for USER1.

USER3(name)

Specifies the name of the installation-written exit routine that is given control after the output data set is closed. This routine is invoked for each output data set. The parameter list pointed to by register 1 contains the address of the 3-word user work area in word 1, the address of the output DCB in word 2, and the address of the OUTDD ddname in word 3.

The exit routine must set a return code in register 15 before passing control back to the SMF data set dump program. The return codes for USER3 are as follows:

Code

Meaning

0

Normal processing should continue

Non-0

A problem was encountered and the SMF data set dump program is not to invoke the exit again.

USER4(name)

Specifies the name of an installation-written exit routine that is given control after each record is read and the counters incremented. This exit receives control for records that contain any standard or extended record header. The parameter list pointed to by register 1 contains the address of the 3-word user work area in word 1, the address of the SMF record in word 2, and the address of the INDD ddname in word 3. See Figure 1.

Note: The USER4 exit is called prior to calling the USER1 exit.

You can only specify USER4 on a separate input line as an IFASMFDP global parameter.

The exit routine must set a return code in register 15 before passing control back to the SMF data set dump program. The return codes are as follows:

Code

Meaning

00

Normal processing should continue

04

The record should not be written to the output data set.

Any other return code indicates that a problem was encountered and that the SMF data set dump program is not to invoke the exit again.

USER5(name)

Specifies the name of the installation-written exit routine that is given control when the SMF data set dump program selects a record to be written. This exit receives control for records that contain any standard or extended record header. The parameter list pointed to by register 1 contains the address of the 3-word user work area in word 1, the address of the SMF record in word 2, and the address of the OUTDD ddname in word 3. See Figure 1.

Note: The USER5 exit is called prior to calling the USER2 exit.

You can only specify USER5 on a separate input line as a IFASMFDP global parameter.

The return codes are the same as those for USER4.

FLDSTATS(xxxx)

Prints out a table with statistics related to record flooding. The output table includes statistics for the records that matched the output filters. Each line of the report is for a given record type. Statistics are gathered based on the xxxx value. This value indicates the number of records that make a single interval for the statistical calculations. See Figure 5.

REPORTOPTS(NOSUBTYPE|SUBTYPE)

Specifies whether the summary activity report is to list subtypes.

NOSUBTYPE

The default. Specifies that the summary activity report lists record types but not subtypes.

SUBTYPE

Specifies that the summary activity report lists record types and subtypes.

SIGSTRIP|NOSIGSTRIP

Specifies whether or not the SMF data set dump program includes the signature records in the dump data sets. If no signature records are present in the input data set, there will be no impact on processing.

SIGSTRIP

The default. Do not include the signature records in the dump data sets.

NOSIGSTRIP

Include the signature records in the dump data sets. You must specify NOSIGSTRIP in order to use the SIGVALIDATE parameter.

NOSIGVALIDATE|SIGVALIDATE(HASH(hashmethod),TOKENNAME(tokenname))

Specifies whether or not to validate the digital signature data in the signature records in the input data sets. If no signature records are present in the input data sets, IFASMFDP will fail with return code 8.

NOSIGVALIDATE

The default. Do not validate the digital signature data.

SIGVALIDATE(HASH(hashmethod),TOKENNAME(tokenname))

Allow the SMF data set dump program to validate the signature records in the input data sets. You must specify a cryptographic public key token name (tokenname) and hash method (hashmethod) that match the signature data to be verified.

Restrictions:

• If the INDD specifies a VSAM data set, no validation processing is done, IFASMFDP fails with return code 8, and message IFA745I is issued.
• If the data set being validated contains records from multiple systems and the SID parameter is unspecified or multiple SIDs are specified, IFASMFDP fails with return code 8 and the IFA747I message is issued.

HASH(hashmethod)

Specify the same hashmethod as was specified on the RECSIGN parameter in the SMFPRMxx parmlib member that was in use at the time the records were generated. See z/OS MVS Initialization and Tuning Reference for more information about the valid hash values.

TOKENNAME(tokenname)

Specify the same token name to be used with the specified hashing technique as was specified on the RECSIGN parameter in the SMFPRMxx parmlib member that was in use at the time the records were generated. See z/OS MVS Initialization and Tuning Reference for more information about the token name value.

The SIGVALIDATE parameter also causes the SMF data set dump program to generate a record validation report. For more information, see IFASMFDP record validation report.

If the IFASMFDP program is run in a non-authorized environment, the user ID under which the program runs must have access to both the PKCS #11 callable services (CSFSERV class) and the public key (appropriate User.xxxxxxx resource in the CRYPTOZ class). Errors related to ICSF authorization will be written to the JOBLOG.

SIGVALIDATE must be specified when ASIGVALIDATE is also specified.

NOASIGVALIDATE|ASIGVALIDATE(HASH(hashmethod),TOKENNAME(tokenname))

Specifies whether or not to validate the alternate digital signature data in the signature records in the input data sets. If no signature records are present in the input data sets, or signature records are present but do not include alternate signature data, IFASMFDP will fail with return code 8.

NOASIGVALIDATE

The default. Do not validate the alternate digital signature data.

ASIGVALIDATE(HASH(hashmethod),TOKENNAME(tokenname))

Allow the SMF data set dump program to validate the alternate signature records in the input data sets. You must specify a cryptographic public key token name (tokenname) and hash method (hashmethod) that match the signature data to be verified.

Restrictions:

• When ASIGVALIDATE is specified, SIGVALIDATE must also be specified. If SIGVALIDATE is not specified with ASIGVALIDATE, IFASMFDP fails with return code 8, and message IFA851I is issued.
• If the INDD specifies a VSAM data set, no validation processing is done, IFASMFDP fails with return code 8, and the IFA745I message is issued.
• If the data set being validated contains records from multiple systems and the SID parameter is unspecified or multiple SIDs are specified, IFASMFDP fails with return code 8 and the IFA747I message is issued.

HASH(hashmethod)

Specify the same hashmethod as was specified on the ARECSIGN parameter in the SMFPRMxx parmlib member that was in use at the time the records were generated. See z/OS MVS Initialization and Tuning Reference for more information about the valid hash values.

TOKENNAME(tokenname)

Specify the same token name tokenname to be used with the specified hashing technique as was specified on the ARECSIGN parameter in the SMFPRMxx parmlib member that was in use at the time the records were generated. See z/OS MVS Initialization and Tuning Reference for more information about the token name value.

The ASIGVALIDATE parameter also causes the SMF data set dump program to generate a record validation report. For more information, see IFASMFDP record validation report.

If the IFASMFDP program is run in a non-authorized environment, the user ID under which the program runs must have access to both the PKCS #11 callable services (CSFSERV class) and the public key (appropriate User.xxxxxxx resource in the CRYPTOZ class). Errors related to ICSF authorization will be written to the JOBLOG.

SIGVALIDATE must be specified when ASIGVALIDATE is also specified.

Notes on the IFASMFDP parameters

1. If a syntax error occurs in the processing of a parameter, SMF does not process the parameter and sends a message to the SYSPRINT data set. If a parameter is not specified, the default is used. The valid dump parameters specified or used by default are listed in the SYSPRINT data set on completion of the SMF data set dump program.
2. START and END parameters: If the start time is less than the end time, the records selected for any particular day are those records produced after the start time and before the end time. For example, if you specify START(0800),END(2000), SMF selects records during the period indicated by the shaded area shown in Figure 1.

   

   If the start time is greater than the end time, all records produced between the start time and the end time on the following day are selected. For example, if you specify START(2000),END(0800), SMF selects records during the time period indicated by the shaded area shown in Figure 2.

   

   Note that SMF does not select the records produced between 0800 hours and 2000 hours in any day.

3. User records must include a standard record header; the SMF data set dump program might not flag an error in a record that does not have a standard header.
4. USERx parameters: The name field in USER1, USER2, USER3, USER4, or USER5 specifies the name of a load module that the SMF data set dump program loads and calls at the indicated times. You can either link-edit each exit into an APF-authorized library in LINKLIST (but do not use the AC=1 attribute) or use a //STEPLIB DD card. All exits specified must be defined to the system in the SMFPRMxx member with the SMFDPEXIT parameter if the program is being executed in an authorized environment. When IFASMFDP is run in an unauthorized environment, the exits specified with USER1, USER2, USER3, USER4, and USER5 are not verified against what is in the SMFPRMxx member.