TRSAVE

Authorization

Privilege Class: A, C

Purpose

Operands

ID traceid

indicates that this TRSAVE applies to data generated by traceid, which was defined by the TRSOURCE command.

CP ON

indicates that the recording of CP trace table data should begin.

CP OFF

stops CP system trace table data recording. Any remaining buffers of data are written to the output medium. Either a tape mark is written, or the DASD file is closed, depending on the output medium. Tapes are rewound and unloaded.

CP CANCEL

stops CP system trace table data recording. Any pending I/O is canceled. Any data collected, but not written, is lost. When tape is the output medium, a tape mark is written, and the tape is rewound and unloaded, regardless of the previous tape positioning option.

DEFERIO

indicates that no trace data is to be recorded on DASD or TAPE until the traceid is disabled or, for CP trace table recording, until TRSAVE CP OFF is issued. Until that time, when all in-storage buffers are filled tracing wraps to the oldest buffer. DEFERIO is not valid for TYPE GT BLOCK mode traces.

FRAMES nnnnn

specifies the number of real storage frames to be used for the in-storage-wrap buffers. The default is 512 frames. The minimum is 8 frames. The maximum is 99999 frames per trace, but may be further limited by the number of pageable pages in the system dynamic paging area that are eligible for DEFERIO traces. See usage note 17 for usage notes regarding DEFERIO and FRAMES.

DASD

indicates that trace data is to be recorded in system trace files. DASD is the default.

TO userid

*

The operand userid specifies the user ID to receive the system trace file containing the trace data.

The operand asterisk (*) specifies that the user who issues the command should receive the system trace file containing the trace data. The operand asterisk (*) is the default.

NAME fname

specifies the file name to be assigned to the system trace file. For CP system trace table data, CPTRACE is the default name. For trace data generated by traces defined by the TRSOURCE command, the trace ID is the default name.

SIZE nnnn

indicates the maximum size of the system trace files. The operand nnnn is a decimal number that specifies 4 KB pages of trace data. Once the file reaches the limit, it is closed and a new file is opened when the next trace record is received. The default is 256 pages. The minimum is eight pages. The maximum is 9999 pages.

KEEP n

specifies the total number of trace files to be kept on DASD for this recording function. The default is two files. The maximum is nine files.

TAPE

indicates that trace data is to be recorded on tape. This option is valid only for recording CP system trace tables.

rdev1 [rdev2]

indicates that the CP trace table data captured by this trace should be recorded on the tape drive at the specified device number. Either one or two tape drives can be specified on any tape option. These tape drives must be system drives and must not be attached to any users.

If two tape drives are specified, CP automatically switches to the alternate tape drive when it encounters an end-of-tape mark.

MODE mode

selects the recording format in which data will be written on the tape. On 3422 tape devices, you can specify the recording format (the MODE) only at the beginning of a tape volume. No changes in the format can be made after this initial designation. On 3480, 3490 (including 3490Es), and 3590 tape devices, you can change the recording format (the MODE) each time you choose to write to a tape volume. After you write to a volume, the MODE value returns to the default value for that particular tape device. If you wish to write to the tape in a different recording format next time, you must again specify the MODE value.

The table below specifies the valid and default mode option values for supported tape devices:

Device Type	Valid Device- Dependent (MODE mode) Option Values	Valid Device- Independent (MODE nnnn) Option Values	Device (MODE mode) Default Value
3422	1600, 6250	n/a	1600
3480	38K	n/a	38K
3480 w/IDRC	XF, 38K	COMP	38K
3490	3490C	COMP	3490C
3590	n/a	COMP	COMP

To determine which device to use, attach the tape device to your userid and issue the 'Q V TAPE' command. Then detach the tape device.

RUN

specifies that the tape is rewound and unloaded when it fills. This is the default.

REWind

specifies that the tape is rewound but not unloaded when it fills. Recording continues to either the other tape drive devoted to CP tracing or the tape drive on which the tape was just filled.

Usage Notes

1. The destinations for trace data are not saved across system hard abends. Therefore, the destination for the trace data should be saved in EXECs.
2. The parameter TAPE and tape options can only be used on TRSAVE FOR CP commands.
3. TRSAVE FOR ID traceid cannot be issued when traceid has been enabled using the TRSOURCE command.
4. The optional destination parameters, TO, NAME, SIZE, and KEEP for DASD, and MODE, RUN, REWIND for TAPE may be specified in any order.
5. For TRSAVE FOR ID traceid, the specified parameters remain in effect until the trace ID is dropped or they are changed on a subsequent TRSAVE command. For example, if you enter the command trsave id debug keep 5 size 9, and then enter trsave id debug size 20, the traceid DEBUG has TRSAVE options traceid recorded to system trace files with a file name of DEBUG, a size of 20 pages, a keep maximum of five files, and a receiver of your user ID.
6. The use of two tape drives is recommended to minimize loss of data. With one tape drive, data may be lost while you rewind and reset for the next tape. If two tape drives are used, both tape drives must support the specified MODE.
   The use of the REWIND option is also recommended. If the REWIND option is not used, a full tape is rewound and unloaded. If one tape drive is used without the REWIND option, data may be lost until the operator mounts another tape. Even if two tape drives are used, data may be lost on heavily loaded systems when the second tape drive becomes full if the operator has not yet:

   • Mounted another tape on the first tape drive
   • Completed the operation intervention on the first drive.
7. Table 1 shows the default file names for system trace files and their file types. The file names may be changed with the NAME fname option.

   Table 1. Default File Names and File Types for System Trace Files

   Source of Trace	File Name	File Type
   CP system trace data	CPTRACE	CP
   TRSOURCE ID traceid TYPE DATA	traceid	DATA
   TRSOURCE ID traceid TYPE IO	traceid	IO
   TRSOURCE ID traceid TYPE GT FOR USER	traceid	VM
   TRSOURCE ID traceid TYPE GT FOR VMGROUP	traceid	VMG

8. When a trace is active, the files associated with it have a class of W. After tracing is complete, the associated files have a class of A.
9. On stressed systems, the trace table may wrap before all entries are saved. In this case, a special trace entry is made to denote data loss.
10. TRSAVE CANCEL immediately terminates the TRSAVE function. Any I/O that is pending is canceled, and any information that has been merged and not written is lost. To ensure that all information collected has been written, use the OFF option on the TRSAVE command.
11. TRSAVE ON is valid only when TRSAVE is not currently active. Likewise, TRSAVE OFF is valid only when TRSAVE is currently active. You may use TRSAVE CANCEL while TRSAVE OFF is in process (for example, when the tape is in a state that requires intervention), but it terminates any I/O that is currently pending.
12. The system attempts to write a tape mark at the end of the data on tape when OFF and CANCEL processing is completed. This attempt may fail because of irrecoverable I/O errors on the tape, but you may still process the tape using the TRACERED utility.
13. KEEP and SIZE may be used together to manage the system spool space. They limit the total amount of space available to record trace data for this trace request. CP limits the amount of data in each file, according to the SIZE specified. By designating a number of files to be kept, TRSAVE allows CP to purge the oldest trace file, keeping the most recent data and continuing to trace when the allowable space limit is reached.
14. Each time a trace becomes active, the trace data is recorded in another file or set of files. For example, if you enter the following commands, you can generate up to six files:

    trsave for cp dasd keep 3
    trsave off
    trsave for cp dasd keep 3
    trsave off

15. For 3490 tape devices, models A01, A02, B02, B04, D31, and D32 should be treated as type 3480 devices. All other 3490 device models should be treated as type 3490 devices. For a complete breakdown of 3480 and 3490 device types by model number, see Defining I/O Devices in z/VM: CP Planning and Administration.
16. If an external security manager is installed on your system, you may not be authorized to enter the TRSAVE command with the TO operand. For additional information, contact your security administrator.
17. Usage notes regarding DEFERIO
    1. The frames are allocated from the system's dynamic paging area when the traceid is enabled or, for CP trace table data, when TRSAVE CP ON DEFERIO FRAMES nnnnn is issued. System performance could be impacted because of the frames not being available for system dynamic paging.
    2. A certain amount of the pageable (non-fixed) pages in the system dynamic paging area are eligible to be allocated for DEFERIO traces. That amount is a percentage (75%) of the total amount of pageable pages in the system dynamic paging area.

       A disabled DEFERIO traceid could have the entire amount of eligible pages in the system dynamic paging area specified regardless of the amount of frames specified for other DEFERIO traces. In order to enable the traceid however, no more than the entire amount of eligible pageable pages in the system dynamic paging area can be allocated for the sum of all active DEFERIO traces.

       If an attempt is made to enable a DEFERIO traceid that could result in more than the eligible amount of pageable pages in the system dynamic paging area being allocated to active DEFERIO traces, then that TRSOURCE ENABLE command would fail.

       Use QUERY TRSAVE FRAMES command to determine how many frames have been allocated from the system dynamic paging area for active DEFERIO traces and to determine how many pageable pages in the system dynamic paging area remain eligible to be used for DEFERIO traces.

       Keep in mind that the number of pageable pages in the system dynamic paging area is affected by the locking and unlocking of pages for various reasons, so the amount of pages eligible to be allocated to DEFERIO traces is a fluctuating amount. You should avoid specifying a FRAMES value that is borderline to the total amount of eligible pages. If the total amount of eligible pages were to decrease after the TRSAVE command has accepted the frames value and before you enable the traceid, then the TRSOURCE ENABLE command could fail because of the inability to allocate the frames at that time.

    3. For every 990 frames, or up to 990 frames allocated for a DEFERIO trace, CP locks an additional frame in the dynamic paging area for its use.
    4. If a large number of frames are specified, then it may take some time to steal those frames. The TRSOURCE ENABLE command will not complete (and CP trace table recording will not be turned on) until the specified amount of frames is allocated. When the number of FRAMES specified on the TRSAVE command for a DEFERIO traceid trace is greater than 512, informational messages will be issued to document the progress of obtaining the frames.

       If a large number of frames are specified, then it may take some time for the TRSOURCE DISABLE command to complete (and for CP trace table recording data to be written) because at that time all of the frames must be written to DASD or to TAPE. When the number of frames to be written out for a DEFERIO traceid trace is greater than 3, informational messages will be issued to document the progress of writing the frames.

       Because the issuing virtual machine will be in 'command wait' until the command completes, you should not enter the TRSOURCE ENABLE or TRSOURCE DISABLE commands from a virtual machine that may be adversely affected by command wait, such as a server virtual machine, a secondary virtual machine, or a PROP virtual machine.

    5. When a DEFERIO trace is eventually recorded on DASD, the SIZE and KEEP operands affect the size and number of trace files that are kept. You should specify a combination of SIZE and KEEP that is equivalent to the number specified for FRAMES. That is, SIZE * KEEP = FRAMES.
    6. If the system terminates with a DEFERIO trace active, then no data is recorded on DASD or TAPE for that trace. However, the trace data can be extracted from a CP dump.

Responses

Response 1:

                { started  }
TRSAVE function { completed}[: nnnn files purged]
                { canceled }[: nnnn files purged]

nnnn

is the number of trace files that have been purged during the time the trace service tool function was active because of the wrapping of the keep limit. When the keep limit is reached, the oldest file is purged. If the response states that 9999 files were purged, it is possible that more than 9999 files were purged.

You receive this when you enter trsave for cp and the TRSAVE command is started, completed, or canceled. If you are not logged on, the completed and canceled responses are sent to the system operator.

No response is issued when TRSAVE FOR ID traceid commands complete because, while TRSAVE defines the destination of traces defined by TRSOURCE, recording of those traces is started and stopped by the ENABLE and DISABLE parameter of the TRSOURCE command.

With both the TRSAVE function completed and the TRSAVE function canceled responses, the trace service tool function is turned off. The second of these responses is issued only when DASD was specified on the TRSAVE ON command. (It is not issued for CP traces to tape.)

Messages

• HCP002E Invalid operand - operand
• HCP003E Invalid option - {option|command contains extra option(s) starting with option}
• HCP006E Invalid device type - {rdev|vdev|ldev}
• HCP013E Conflicting option - option
• HCP020E Userid missing or invalid
• HCP021E A real device number was not supplied or it is invalid.
• HCP026E Operand missing or invalid
• HCP040E Device {rdev|vdev|ldev} does not exist
• HCP046E type rdev offline
• HCP053E [XAUTOLOG failed for userid:] userid|value not in CP directory
• HCP140E type {rdev|ldev} attached to userid
• HCP143E type rdev in use by system
• HCP410E CP ENTERED; PAGING ERROR
• HCP422E The same option was specified twice.
• HCP423E The function requested is incompatible with a previously specified operand.
• HCP475I Fatal I/O error trying to read directory from volid [for user userid]
• HCP479E Traceid traceid currently enabled
• HCP1001E An operand is missing for option.
• HCP1013E An invalid operand was supplied for option - operand.
• HCP1105E Tape rdev not attached; tape assigned elsewhere.
• HCP1107E command failed; I/O error on tape rdev
• HCP1917E Tape device(s) {rdev[-rdev]|vdev[-vdev]} attached MULTIUSER.
• HCP6076E TRSAVE is not active.
• HCP6077E TRSAVE is already active.
• HCP6079E Tape drive rdev does not support mode mode.
• HCP6085E The TRSAVE command cannot be processed because the function is in a transition state.
• HCP6087E DEFERIO FRAMES specified exceeds the amount of frames eligible for DEFERIO traces.
• HCP6089E DEFERIO FRAMES specified causes total DEFERIO frames to exceed the amount of frames eligible for all DEFERIO traces.
• HCP6091I The amount of frames used for DEFERIO trace exceeds the amount of pages that will be saved on DASD.
• HCP6099E DEFERIO trace is invalid for a TYPE GT BLOCK mode trace.
• HCP6525E External Security Manager is unavailable.