COPYTRC subcommand — copy trace entries or records

Use the COPYTRC subcommand to copy GTF trace records to an output data set from trace data sets or trace buffers in dump data sets. You can also use COPYTRC to copy component trace entries to an output data set from trace data sets or trace buffers in dump data sets. You can use COPYTRC to:

Combine trace data sets, or trace entries or records in dump data sets, or both, into a single data set.
Extract trace entries or records from buffers in SVC and stand-alone dumps.
Combine trace entries or records from multiple systems. When COPYTRC combines trace entries or records from several systems into a single data set, it marks the system of origin for each trace entry or record in the output data set.
Extract trace entries or records for a specified list of systems from combined trace entries or records.

You can run COPYTRC by entering the subcommand or using the panels on option 5.3 of the IPCS dialog.

The main function of the COPYTRC subcommand is to aid in processing multiple trace sources. Suppose you have multiple GTF data sets from a run on a single system. Before using GTFTRACE to process all of the trace data, you must combine all GTF trace records into a single data set using COPYTRC.

Note:

To process multiple GTF data sets from multiple systems, you can either:
- Combine the trace records into a single data set with COPYTRC
- Keep the trace data sets separate and use the MERGE subcommand to format the traces
COPYTRC cannot process GTF trace records and component trace entries at the same time. So, for COPYTRC input sources, specify all GTF trace sources, or all component trace sources, but not a mix of both traces. To see GTF trace records and component trace entries chronologically in a single report, use the MERGE subcommand.

COPYTRC does not have a default input or output data set name or ddname.

After the entries or records are copied, COPYTRC closes both the input and output data sets and displays a summary of the trace entries or records that were copied.

Related subcommands
- CTRACE
- GTFTRACE
- MERGE

Syntax

  COPYTRC [ TYPE(GTF|CTRACE) ]
          { INDATASET(dslist)|INDSNAME(dslist)|IDS(dslist) }
          { INFILE(ddlist)|INDDNAME(ddlist)                }
          { OUTDATASET(dsname)|OUTDSNAME(dsname)|ODS(dsname) }
          { OUTFILE(ddname)|OUTDDNAME(ddname)                }
          [ SPACE(pppp[,ssss]|50,50) ]

-------- Data Selection Parameters -------------------------

          [ OPTIONS((ALL|filters)) ]
          [ START(mm/dd/yy,hh.mm.ss.dddddd) ]
          [ STOP(mm/dd/yy,hh.mm.ss.dddddd) ]
          [ SYSNAME(sysname[,sysname]...) ]

-------- SETDEF-Defined Parameters -------------------------
Note: You can override the following SETDEF parameters.
See SETDEF subcommand — set defaults.

          [ FLAG(severity) ]
          [ PRINT | NOPRINT ]
          [ TERMINAL | NOTERMINAL ]
          [ TEST | NOTEST ]

Parameters
TYPE(GTF | CTRACE)

Specifies the type of trace data to be copied. COPYTRC will copy trace data generated by either GTF or component traces. These two types of traces may not be combined. If the TYPE parameter is omitted, COPYTRC tries to copy GTF trace records.

INDATASET(dslist) or INDSNAME(dslist) or IDS(dslist)

INFILE(ddlist) or INDDNAME(ddlist)
Specifies the data sets containing the traces to be copied. Use these parameters in any combination. All data sets should contain the same type of trace. To specify multiple input data sets, use any combination of the following data sets:
- Trace data sets created by GTF or CTRACE
- Trace data sets created by COPYTRC
- SVC, stand-alone dump, and SYSMDUMP dump data sets
An example of a combination of parameters follows:
```
COMMAND ===> COPYTRC INFILE(GTFDINDD) INDATASET(MY.GTFDATA1,MY.GTFDATA2) ...
```
INDATASET, INDSNAME, or IDS specifies the input data set or sets. When specifying more than one data set name, separate the names with commas or blanks. IPCS dynamically allocates each input data set. If a data set is not open, COPYTRC opens the data set after it is dynamically allocated.

Each designated data set must exist and must be cataloged to allow the system to locate it. If a data set resides on a volume that is not mounted as RESIDENT, MVS™ MOUNT authorization is required.

After copying, IPCS closes and deallocates each data set. When the SETDEF-defined default source is specified as an input data set, IPCS does not close or deallocate the data set.

INFILE or INDDNAME specifies the ddname of the input data set or sets. Before using INFILE or INDDNAME, you must allocate each data set using JCL or the TSO/E ALLOCATE command. IPCS opens the data sets.

When specifying more than one ddname, separate the names with commas or blanks.

When IPCS finishes copying, it closes the data set, but does not directly deallocate it. You can use the JCL FREE=CLOSE to release each data set. When the SETDEF-defined default source is specified as an input data set, IPCS does not close or deallocate it.
OUTDATASET(dsname) or OUTDSNAME(dsname) or ODS(dsname)

OUTFILE(ddname) or OUTDDNAME(ddname) or OFILE(ddname)

Specifies the output data set into which the traces are to be copied. The COPYTRC subcommand must specify an output data set.
OUTDATASET, OUTDSNAME, or ODS specifies the output data set. If the designated data set exists, it is dynamically allocated and used by COPYTRC. The data set must be cataloged. If the data set resides on a volume that is not mounted as RESIDENT or RESERVED, MVS MOUNT authorization is required.

If the designated data set does not exist, the system allocates a new data set with the specified name. Use the SPACE parameter to indicate the amount of space to be allocated. If the SPACE parameter is omitted, COPYTRC uses default amounts.

After the copying, IPCS closes and deallocates the data set.

OUTFILE or OUTDDNAME specifies the ddname of the output data set. Before using COPYTRC, you must allocate this data set using JCL or the TSO/E ALLOCATE command.

After the copying, IPCS closes the data set but does not directly deallocate it.

COPYTRC processing might open and close the output data set more than once. Do not use options on the DD statement, such as RLSE or FREE=CLOSE that conflict with the multiple open and close operations.

IBM® recommends to use the same BLOCKSIZE for the output data set as for the input data set. Using different BLOCKSIZE may cause some data not to be captured when START or STOP times are specified.

SPACE(pppp[,ssss] | 50,50)

Specifies the number of tracks for the primary space allocation, pppp, and the secondary space allocation, ssss for a new data set. The system releases excess space at the completion of COPYTRC processing. If you omit this parameter, both the primary allocation and the secondary allocation defaults are 50 tracks. If only the primary allocation is specified, the secondary allocation defaults to the primary allocation.
Data Selection Parameters
All data selection parameters are optional. If specified, COPYTRC copies only trace entries or records that meet the specified data selection requirement.
OPTIONS((ALL | filters))
Specifies filtering options for a particular component trace. ALL indicates that COPYTRC is to copy all component traces. filters lists the trace names to be used as filters; filters has the following syntax:
```
COMP(name) [SUB(name[.name]...)][,...]
```
You may specify complete trace names or partial trace names. Separate each partial or complete trace name by a comma. If you specify a partial trace name, COPYTRC copies each trace that matches the partial trace name.
For example, if you specify OPTIONS((COMP(COMP1) SUB(ASID(200)))), the following traces match this partial trace name:
- COMP1.ASID(0200).FUNC2.SVC3
- COMP1.ASID(0200).FUNC1.SVC3
Note: You must specify TYPE(CTRACE) to use the OPTIONS parameter.
START(mm/dd/yy,hh.mm.ss.dddddd)
Specifies the beginning date and time for the trace entries or records to be copied. When you do not specify START, IPCS starts at the beginning of the trace entries or records. Specify the date and time in mm/dd/yy,hh.mm.ss.dddddd format.
mm

represents months

dd

represents days

yy

represents years

hh

represents hours

mm

represents minutes

ss

represents seconds

dddddd

represents decimal fractions of seconds
These rules apply to the date and time specifications:
- You must specify a date and time on the START parameter.
- The month and day can be specified in either single or double digits.
- Separate the date from the time with a comma.
- The time must be Greenwich mean time (GMT).
- Hours, minutes, and seconds can be specified in single or double digits.
- The time can be truncated anywhere on the right.
- The time can be left off completely, in which case, it will default to 00:00:00.000000 (midnight).
Table 1 shows examples of valid date and time formats.
Table 1. Examples of valid date and time formats
Valid date formats Valid time formats

m/dd/yy mm/d/yy m/d/yy mm/dd/yy

hh.mm.ss.dddddd hh.mm.ss.dd hh.mm.ss h.m.s hh.mm hh
STOP(mm/dd/yy,hh.mm.ss.ddddddd)

Specifies the ending date and time for the trace entries or records to be copied. When you do not specify STOP, IPCS stops copying after the last trace entry or record. For guidelines on how to specify the date and time, see the START parameter.

SYSNAME(sysname[,sysname]...)

Requests that the trace entries or records should be copied only if the trace's system name matches one of the system names in the list. SYSNAME accepts up to 16 system names in the list.

Table 1. Examples of valid date and time formats
Valid date formats	Valid time formats
`m/dd/yy mm/d/yy m/d/yy mm/dd/yy`	`hh.mm.ss.dddddd hh.mm.ss.dd hh.mm.ss h.m.s hh.mm hh`

Return codes

Code	Explanation
00	End of file reached. The input data set has been closed and all trace entries or records have been copied to the output data set.
04	No valid trace entries or records meeting the selection criteria were found. No trace data was copied to the output data set.
08	A processing error occurred. Some, but not all trace entries or records were copied to the output data set.
12	An error occurred in COPYTRC processing. No trace entries or records were copied to the output data set.
16	Dynamic allocation of the output data set failed. No trace entries or records were copied to the output data set.
20	The COPYTRC subcommand has a syntax error.
24	The COPYTRC subcommand has a semantic error.