IAM/RLS Tracing
IAM/RLS Trace Facility
The IAM/RLS Trace Facility enables BMC support personnel to request information about I/O requests and other processes that are occurring within the IAM/RLS 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 MVS 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/RLS trace command is as follows:
F IAMRLS, TRACE, subcommand, parameters
The “IAM/RLS” is replaced by the IAM/RLS address space name. The “subcommand” are one of the subcommands shown below. The parameters will be as indicated for the subcommand. There are three IAM trace subcommands for IAM/RLS and all are entered via the MVS MODIFY command. The subcommands are as follows:
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:
F IAMRLS,TRACE,START
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. 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/RLS 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 an MVS 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/RLS 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: ALLIO - Trace IOS, IOE, BFR, EXCP, and XTND requests 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/RLS PC calls |
Stopping a Trace
To terminate tracing, issue the following command:
F IAMRLS,TRACE,STOP,ID=traceid,END
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:
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 MVS 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/RLS trace function. All examples assume an IAM/RLS 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 CICDIDP1:
F IAMRLS,TRACE,START,ID=IAM1,JOBNAME=CICSIDP1,TRACEREQ=(IOS,IOE),END
To trace all PC calls against data set MY.IAMFILE:
F IAMRLS,TRACE,START,ID=PCTRACE,DSN=MY.IAMFILE,TRACEREQ=PC,END
To list all active trace requests:
F IAMRLS,TRACE,LIST,END
To stop a trace request with the ID of TRACE1:
F IAMRLS,TRACE,STOP,ID=TRACE1,END