Dump Device (QTADMPDV) API

The Dump Device (QTADMPDV) API collects information for your IBM service representative. This API should be used immediately after a suspected device and/or tape management system failure. If the API is not used immediately, other device operations may cause the flight recorders to wrap, which could result in lost information. A problem identifier will be created and an APAR library will be generated similar to the Save APAR Data (SAVAPARDTA) command. To save the APAR library, use Work with Problem (WRKPRB) command. Choose the option to work with the problem and then the option to save the APAR library. If an existing problem identifier is passed to this API, then the spooled files generated will be logged against that problem identifier and no new problem identifier will be generated.

The Dump Device API currently supports the following device types:

• Tape (TAP) devices
• Tape media library (TAPMLB) devices
• Optical (OPT) devices
• Optical media library (OPTMLB) devices

Note: The information provided in and the number of spooled files may change at anytime. The information provided is intended for problem determination.

The Dump Device (QTADMPDV) API dumps the following information for tape or tape media library devices, into spooled files:

• Dump of the device description for the device specified in the parameter that is passed to the program.
• Device description details of the device.
• Device capabilities (QTARDCAP output).
• QTARDINF API output.
• Licensed Internal Code tape flight recorders.
• IOP trace for the device.
• QSYSOPR message queue.
• Message queue for the user/device doing the QTADMPDV call.
• Licensed Internal Code logs from the last 24 hours.
• Product Activity Logs from the last 24 hours.
• The PTF list.
• A Work with Configuration Status (WRKCFGSTS) listing.
• Media and Storage Extensions (MSE) flight recorder.
• The history log (QHST).
• QTAPARB job log and display job (DSPJOB) information.
• Job logs and display jobs (DSPJOB) of the active jobs that have used the device as indicated in the flight recorder data.
• The job log and display job (DSPJOB) of the job that is processing this API.
• The Media library inventory information and display file description (DSPFD).
• The Media library category information and display file description (DSPFD).
• The Media library filter information and display file description (DSPFD).
• The Display Hardware Resources output (DSPHDWRSC).
• QTAHRSRV flight recorders.
• The virtual tape information area.
• The problem log summary.
• Communication information that is associated with the media library device. This includes the line, controller, and device descriptions.

Note that this API will generate multiple spooled files that may get large depending upon the job logs that are being printed and the size of the other device information. Submitting the call to batch may be used if system performance is a concern. That is, if the API is called from the system console at high priority, it may degrade performance on other critical processing. Since many and potentially large spooled files may be generated, ensure that there is enough system storage available to handle the request.

Authorities and Locks

Device description: *USE

To dump the IOP trace you need use (*USE) authority to the Control Device API (QTACTLDV).
See the documentation for this API for additional authority requirements.

To dump the PTF details you need use (*USE) authority to the Display Program Temporary Fix (DSPPTF) command.
See the documentation for this command for additional authority requirements.

To dump the VLOGS you need use (*USE) authority to the Print Internal Data (PRTINTDTA) command and Service (*SERVICE) special authority.
See the documentation for this command for additional authority requirements.

To dump the Product Activity Logs (PALS) you need use (*USE) authority to the Print Error Log (PRTERRLOG) command.
See the documentation for this command for additional authority requirements.

To dump the QTAPARB job log and display job information, you need Job Control (*JOBCTL) and All Object (*ALLOBJ) special authorities.

To dump the Media Library Inventory file description, you need use (*USE) authority to the QATAMID and QLTAMID files in QUSRSYS.

To dump the Media Library Category file description, you need use (*USE) authority to the QATACGY and QLTACGY files in QUSRSYS.

To dump the Cartridge Filter file description, you need use (*USE) authority to the QATAFTR file in QUSRSYS.

To dump the QTAHRSRV flight recorders you need use (*USE) authority to the Dump System Object (DMPSYSOBJ) command.
See the documentation for this command for additional authority requirements.

Required Parameter

Device name

INPUT; CHAR(10)

The name of the device for which debugging information is being dumped.

Optional Parameter Group

Type of information

INPUT; CHAR(10)

The type of information to be dumped.
Valid values are:

*ALL	All information needed by IBM will be dumped to spooled files.
*MSE	Media and Storage Extension (MSE) flight recorder will be dumped. This is only valid for tape or tape media library devices.

Problem identifier

INPUT; CHAR(10)

The problem identifier of the problem being analyzed. Problems with different system origins can have the same identifier. The possible values are:

*NEW	A problem identifier will be created.
problem-identifier	The 10-character problem identifier of the problem being selected.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Examples

The following are examples of calls to the API from command entry:

• CALL QTADMPDV TAP01

  The dump device will dump information about TAP01 and assigns it to a created problem identifier.

• CALL QTADMPDV TAPMLB01

  The dump device will dump information about TAPMLB01 and assigns it to a created problem identifier.

• CALL QTADMPDV (TAP01 *ALL 9628851615 x'00000000')

  The dump device will dump information about TAP01 and assign it to an existing problem identifier.

Error Messages