IAM/PLEX Tracing
The IAM/PLEX Trace Facility enables BMC support personnel to request information about I/O requests and other processes that are occurring within the IAM/PLEX Address Space. Trace output will be to dynamically allocated SYSOUT spool data sets or to previously allocated output files. All trace requests are initiated via the z/OS console MODIFY (F) command. If additional parameters are required beyond what was initially specified, then the trace processor will request them via a WTOR. For trace start requests, the additional parameters can alternatively come from a sequential data set.
The general format of using the IAM/PLEX trace command is as follows:
The “iamplex” is replaced by the IAM/PLEX address space name. The subcommands are shown in the table below. The parameters will be as indicated for the subcommand. There are threeIAM trace subcommands for IAM/PLEX and all are entered via the z/OS MODIFY command. The subcommands are:
Subcommand | Description |
START | Request a new trace |
STOP | Stop an existing trace |
LIST | List all active trace requests |
Starting a Trace
To start a trace, issue the command:
The additional parameters can be included on the above command, provided via replies to the WTOR’s, or with the PARMS= parameter, through a sequential data set. The parameters for starting a trace are shown on the next page.
Trace Parameters
Parameters for TRACE START subcommand are:
Parameter | Description |
DSN= | Optional parameter that specifies the name of the IAM data set that you wish to trace requests against. Trace information will be generated by any request from any address space that is accessing the named file unless further limited by JOBNAME= and/or STEPNAME= parameters. |
END | Required parameter to signify that all of the desired parameters had been specified. |
ID= | Optional parameter that specifies a unique 1 to 8 alphanumeric character string used to identify this trace request. If one is not specified, IAM will generate a value. This ID is required for STOP and LIST requests. |
INTERNAL | Specifies that trace will be done to an internal wrapping table in 64-bit virtual storage. The table size will be 2 megabytes. This is primarily intended for gathering additional information as may be requested to diagnose a problem. |
JOBNAME= JOB= | Optional parameter that specifies tracing is to be performed for requests from specific job. If not specified, all jobs with IAM data sets that are accessed through the IAM/PLEX address space will be eligible for tracing. Use this parameter with DSN= and/or STEPNAME= to limit what is traced. |
OUTDSN= | Optional parameter that causes trace output to be sent to a file instead of a dynamically allocated SYSOUT file. If specified, it must be a pre allocated and cataloged sequential data set. IAM will set up the required DCB characteristics. |
PARMS= | Optional parameter that specifies the name of a sequential file that contains the actual trace request. If not specified, all of the necessary parameters must either be specified on the modify (F) command itself, or provided as replies to the WTOR messages that will be issued. |
STEPNAME= | Optional parameter that specifies to trace only requests to IAM/PLEX from the specific step name. When used without other limiting parameters, this will cause ALL requests from any job that has the specified STEPNAME to be traced. When not specified, all step names are eligible for tracing. Use with DSN= and/or JOBNAME= to limit what is traced. |
TRACEREQUEST= | Required parameter that specifies what type of trace records are to be produced. Any or all options may be specified on any trace request. The options are: IOS - Trace I/O Start requests IOE - Trace I/O End requests IOERR - Trace I/O requests that fail BFR - Trace IAM Buffer requests EXCP - Trace IAM EXCP requests XTND - Trace IAM extend requests PC - Trace IAM/PLEX PC calls |
Stopping a Trace
To terminate tracing, issue the following command:
The parameters for TRACE STOP requests are:
Parameter | Description |
ID= | Required parameter that specifies the ID of the TRACE request to be stopped. |
END | Required to signify that all parameters have been specified. |
Displaying Active Trace Requests
Use the TRACE,LIST command to display the currently active trace requests. You can request either all of the currently active trace requests, or a specific trace request.
The parameters for TRACE,LIST requests are:
Parameter | Description |
ID= | Optional parameter that specifies the trace ID from the TRACE,START request. If not specified, all active trace requests will be displayed on the z/OS console. |
END | Required parameter to indicate that all of the desired parameters have been specified. |
Examples of Trace Commands
The following demonstrate some examples of using the IAM/PLEX trace function. All examples assume an IAM/PLEX address space job name of IAM/RLS.
To trace all I/O Start and I/O End requests from all IAM files from CICS region CICSIDP1:
To trace all PC calls against data set MY.IAMFILE:
To list all active trace requests:
To stop a trace request with the ID of TRACE1: