IEFU29 - SMF Dataset Switch Exit
If you have SMF (System Management Facility) set up to collect statistical information about the tasks running on your MVS system, you will eventually see the message:
when the active dataset fills up. This message is also issued when MVS is shut down (with the Z EOD operator command) or when the SMF dataset is switched in response to the operator command: I SMF).
There is a user exit that may be installed - IEFU29 - that will intercept the IEE362A message and start a task to dump and clear the filled SMF dataset automatically. The tasks involved in setting up the exit are:
Even if you don't want to install the exit, creating the procedure can simplify responding to the message manually. The jobstreams to do all the work are contained in the archive - iefu29.tgz [MD5: 733BFA6C9C0C1658D6031DFAAEAC8B2D]:
Creating a SYS1.MANx Dump Procedure
By using a symbolic parameter, it is possible to create a single set of JCL to process either of the SMF datasets. When the procedure is started, whether by executing the procedure from a jobstream, or by starting the procedure with a command from the console operator or by the IEFU29 exit, a value is passed to the procedure which is substituted for the symbolic parameter, thus referring to either of the two SMF datasets. There is no need to maintain two sets of JCL. Here is the procedure:
There are actually two symbolic parameters, CLASS and ID, but CLASS has a default value and I largely included it to have some flexibility over the disposition of the SYSOUT during testing. The value passed to the JCL via the ID symbolic parameter will be appended to the end of the coded value for the DSN parameter on the DUMPIN DD statements, thereby yielding either SYS1.MANX or SYS1.MANY depending upon whether the value of ID passed is X or Y.
The IFASMFDP program, which is supplied with MVS to dump and clear the SMF datasets requires a parameter card via SYSIN. Because this is a catalogued procedure, the SYSIN data cannot be placed inline with the JCL, so I have placed the two parameter cards in the SYS2.CONTROL dataset. If you don't have a SYS2.CONTROL dataset, you can create one by using this job:
Notice that for documentation of the SMFDUMP procedure, I place the value of the respective parameter cards that are pointed to by the SYSIN DD statements as comments following the SYSIN DD statements in the procedure.
When this procedure runs, the first step will dump the contents of the SMF dataset to another dataset, then, if that step doesn't terminate abnormally, the second step of the procedure will clear the dataset.
You can see that if you really just wanted to have the IEFU29 exit automatically clear the filled SMF dataset, you could simply eliminate the first step of the procedure.
Retaining a Group of SMF Datasets
Notice that in the procedure, I have specified a Generation Data Group dataset name on the DUMPOUT DD statement to receive the contents of the filled SMF dataset. In order to do any meaningful analysis on SMF data, it is necessary to have available a collection of data that spans some period of time. Using a Generation Data Group is an easy way to let the system manage how much data I retain. If you prefer to use a static dataset, either on tape or disk, you can modify the first step of the procedure accordingly and forego running the supplied jobstream that defines the Generation Data Group and Model DSCB..
Manually Starting the Procedure
Once the procedure has been catalogued in SYS1.PROCLIB, you can manually start the procedure when ever the IEE362A message is issued, by using the START operator command:
depending upon which dataset needs dumping. If you don't care to install the IEFU29 exit, just setting up the catalogued procedure can save you some effort when the time comes to clear an SMF dataset.
Installing the Exit
Activating the exit requires an Assembler program that MVS will automatically invokes whenever an SMF dataset becomes filled and the IEE362A message is about to be displayed. The program runs in supervisor state and is passed the name of the dataset that needs dumping. The functions performed by the program are simple:
The IEFU29 exit is packaged as an SMP4 User Modification - JLM0001 - and is installed, assembled and link edited under the control of SMP4. Once installed, an IPL with the CLPA option needs to be performed to rebuild the load modules in the LPA which will activate the exit. When the SMP job is run to install the exit, the return codes to be expected are:
IEF142I IEFU29 CLEANUP - STEP WAS EXECUTED - COND CODE 0000 IEF142I IEFU29 ADD - STEP WAS EXECUTED - COND CODE 0000 IEF142I IEFU29 ASM ASM - STEP WAS EXECUTED - COND CODE 0000 IEF142I IEFU29 HMASMP RECAPP - STEP WAS EXECUTED - COND CODE 0012
The condition code 0012 on the final step is expected, because SMP first tries to delete any existing version of IEFU29 and there is not one to delete.
Expected Error at MVS Shutdown
When the IEFU29 exit is activated, at MVS shutdown (the Z EOD command is issued by the operator), the IEFU29 exit will issue the START command. However, since JES2 has already been stopped, an error message will be issued by MVS:
*IEE362A SMF ENTER DUMP FOR SYS1.MANX ON MVSRES START SMFDUMP,ID=X IEFU29 HAS ISSUED COMMAND 'START SMFDUMP,ID=X ' IEE360I SMF NOW RECORDING ON SYS1.MANY ON MVSRES TIME=22.29.25 IEE334I HALT EOD SUCCESSFUL IEC141I 013-C8,IGG0193K,MSTRJCL,JES2,STCINRDR IEF170I 1 MSTRJCL IEC141I 013-C8,IGG0193K,MSTRJCL,JES2,STCINRDR
At the next IPL, SMF will resume recording in the same dataset that was in use - SYS1.MANX in the case of the messages above - and no data will be lost.
Manually Switching the SMF Dataset
You can direct SMF to switch from the active dataset to the alternate by issuing the operator command:
If you have installed the SMFDUMP procedure and IEFU29 exit, the exit will issue the START command as described above to dump and clear the previously active SMF dataset.
Analyzing SMF Data
After you have transferred the collected SMF data into your own datasets, whether you have chosen to use a Generation Data Group managed dataset or a scheme of your own choosing, you may then wonder what to do with it. There are several SMF extraction and reporting programs on the CBT tape, notable among them are those found in files #94 (SMF Dataset Audit Facility) and #523 (General SMF Record Selection Program).
Determining the Active SMF Dataset
There is a useful program on CBT that may be run as either a TSO command or a started task that will display information about the SMF datasets allocated in the system, including noting which is currently active (receiving output from SMF). You can download the installation jobstream from my site at CBTWare/showsmf.
A post to the main Hercules discussion group pointed out that if you follow these instructions to set up the SMF datasets with a high level qualifier of SYS2 and have password protected your Master Catalog, you will be prompted for the Master Catalog password whenever the SMFDUMP procedure executes, either when invoked manually via the i smf console command or by the IEFU29 exit. When I initially set this up on my own system, I did not have the Master Catalog password protected and, even after I added password protection to my Master Catalog, I did not see this as much of an inconvenience. Never the less, it is probably a factor that you need to consider if you follow my instructions.
If you have not yet begun, you simply need to change the SYS2 high level qualifier in the smfgdg and smfproc jobstreams discussed above to one that is related to a user catalog on your own system. Remember that the model DSCB must reside on the same volume as the catalog into which the SMF dataset generations will be cataloged. The datasets themselves need not reside on that volume, but the catalog and model DSCB must be kept together.
If you have already followed the instructions above and wish to modify your system to move the SMF datasets into a user catalog, I have created a jobstream that will be useful to you in accomplishing that:
Step 1 of the jobstream uncatalogs existing SMF dataset generations. When I built the jobstream on my system, there were four generations, so you may need to modify the control statements following the SYSIN statement to match the conditions of your own system.
Step 2 of the jobstream removes the GDG base (SYS2.SMF.DATA) from the Master Catalog, removes the matching model DSCB from MVSRES, creates a new GDG base (SYSO.SMF.DATA) in the User Catalog UCMVSOPS, and a matching model DSCB on the WORK02 volume. On my system, I already had a User Catalog - UCMVSOPS - in which I catalog miscellaneous operations related datasets. The catalog resides on my WORK02 volume and is related to the high level qualifier SYSO. You will either need to create a User Catalog specifically for SMF or select an existing User Catalog on your system. Remember that the model DSCB must reside in the VTOC on the same volume where the User Catalog resides. So there are three items to keep in alignment as you tailor this jobstream for your system - placement of the model DSCB, location of the User Catalog, and high level qualifier of the SMF.DATA must be related to the selected User Catalog. Note that this step has a STEPCAT pointing to the target User Catalog.
Step 3 of the jobstream renames the existing SMF datasets changing the high level qualifier - SYS2 to SYSO. As you can see, the datasets remain on volume SMP001 on my system; only the catalog in which the datasets are cataloged and the location of the model DSCB are affected. Then the newly renamed datasets are cataloged in the user catalog. As with Step 1, I had four datasets to rename/recatalog on my system; you may have fewer or more, so change the control statements as required for your system as it exists at the time you submit the jobstream. Again note that this step must have a STEPCAT pointing to the target User Catalog.
Step 4 of the jobstream utilizes TSO execute in batch to edit the catalogued procedure in SYS1.PROCLIB to alter the high level qualifier of the SMF datasets.
The jobstream only needs to be run once and it should go without saying that you should back up your system before submitting the job. You will be required to enter the Master Catalog password for steps one and two of the jobstream as alterations are being made to entries in the Master Catalog. Once this jobstream is run, you will no longer be required to enter the Master Catalog password when the SMFDUMP procedure executes.
I hope that you have found my instructions useful. If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:
This page was last updated on April 22, 2008 .