Print Trace Data (PRTTRC)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Print Trace (PRTTRC) command formats and writes the trace records to the selected output file. The trace records were written to a set of database files by the ENDTRC (End Trace) command and PRTTRC is used to format these trace records to a spooled output file or to a database output file. If the trace records are written to a spooled output file, printer file QPSRVTRCJ is used. The user data for the spooled file will be the same as the value specified for the DTAMBR (Data member) parameter.
Restrictions:
- To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service trace function of IBM i through System i Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.
- You must have authority to the library and the database files within that library where the trace data is stored.
- If DLTTRC(*YES) is specified, you must have authority to the DLTTRC (Delete Trace Data) command.
- The record format of the database output file must match the record format of the IBM-supplied output file QASCTJFL.
- The ENDTRC command that produced the trace data and the PRTTRC command that processes and formats the trace data must be run on the same release of Operating System.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| DTAMBR | Data member | Name | Optional, Positional 1 |
| DTALIB | Data library | Name, *CURLIB | Optional |
| SLTJOB | Select jobs | Single values: *ALLJOBS Other values (up to 10 repetitions): Qualified job name |
Optional |
| Qualifier 1: Select jobs | Generic name, name, *ALL | ||
| Qualifier 2: User | Generic name, name, *ALL | ||
| Qualifier 3: Number | 000001-999999, *ALL | ||
| DLTTRC | Delete trace | *YES, *NO | Optional |
| SORT | Sort by | *TIME, *THREAD | Optional |
| OUTPUT | Output | *PRINT, *OUTFILE | Optional |
| OUTFILE | File to receive output | Qualified object name | Optional |
| Qualifier 1: File to receive output | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| OUTMBR | Output member options | Element list | Optional |
| Element 1: Member to receive output | Name, *FIRST | ||
| Element 2: Replace or add records | *ADD, *REPLACE |
| Top |
Data member (DTAMBR)
Specifies the member name for the trace data that you want to print. The member name will be the same as the trace session identifier specified on the Start Trace (STRTRC) and End Trace (ENDTRC) commands. The member name is the same for each of the physical files that contain the trace data.
This is a required parameter.
- name
- Specify the name of the database file member that contains the trace data.
| Top |
Data library (DTALIB)
Specifies the library that contains the set of database files where the collected trace data is stored.
- *CURLIB
- The trace data is printed from files in the current library for the job. If no library is specified as the current library for the job, QGPL is used.
- name
- Specify the name of the library that contains the trace data files.
| Top |
Select jobs (SLTJOB)
Specifies which jobs to include in the trace listing. This allows the user to reduce the size of the trace listing by selecting only a subset of the jobs that were part of the trace. Up to ten qualified job names can be specified.
Single values
- *ALLJOBS
- All jobs that were part of the trace are included.
Qualifier 1: Select jobs
- *ALL
- All jobs that match the specified job user are included.
- generic-name
- Specify the generic name of the jobs to be included in the trace listing. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic job name specifies all jobs with job names that begin with the generic prefix.
- name
- Specify the name of the job to be included in the trace listing.
Qualifier 2: User
- *ALL
- All jobs that match the specified job name are included.
- generic-name
- Specify the generic user name of the jobs to be included.
- name
- Specify the name of the user of the job to be included.
Qualifier 3: Number
- *ALL
- All jobs that match the specified job name and user name are included.
- 000001-999999
- Specify the job number to further qualify the job name and user name.
| Top |
Delete trace (DLTTRC)
Specifies whether trace data is deleted after is has been printed.
- *YES
- The trace data in the database files is deleted after the print has completed.
- *NO
- The trace data in the database files is saved. The DLTTRC (Delete Trace) command can be used to delete the data when it is no longer needed.
| Top |
Sort by (SORT)
Specifies how the trace data for each job is sorted in the specified output file.
- *THREAD
- The trace data for each job is sorted by thread. If a job has multiple threads, the trace data for each thread is sorted by time.
- *TIME
- The trace data for each job is sorted by time. If a job has multiple threads, the trace data for all threads in the job is sorted by time. This can result in the trace output for multiple threads to be intermingled.
| Top |
Output (OUTPUT)
Specifies whether the output from the command is printed with the job's spooled output or sent to a database file.
- The output is printed with the job's spooled output.
- *OUTFILE
- The output is directed to the database file specified for the File to receive output (OUTFILE) parameter.
| Top |
File to receive output (OUTFILE)
Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.
Qualifier 1: File to receive output
- name
- Specify the name of the database file to which the command output is directed.
Qualifier 2: Library
- *LIBL
- The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
- *CURLIB
- The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.
- name
- Specify the name of the library to be searched.
Note: If this command creates the file, the text is "OUTFILE created by PRTTRC command" and the public authority is *EXCLUDE.
| Top |
Output member options (OUTMBR)
Specifies the name of the database file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.
Element 1: Member to receive output
- *FIRST
- The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified for the File to receive output (OUTFILE) parameter.
- name
- Specify the name of the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.
If the member exists, you can add records to the end of the existing member or clear the existing member and add the records.
Element 2: Replace or add records
- *REPLACE
- The existing records in the specified database file member are replaced by the new records.
- *ADD
- The new records are added to the existing information in the specified database file member.
| Top |
Examples
Example 1: Print and Delete Trace
PRTTRC DTAMBR(TRACE8) DTALIB(TRCLIB1) DLTTRC(*YES)
This command formats and prints the trace data contained in database file members named TRACE8 in library TRCLIB1. The trace data members are removed after the trace data spooled file has been written. All jobs which were part of the trace will be part of the trace listing.
Example 2: Print Subset Trace
PRTTRC DTAMBR(T123456789) DTALIB(QGPL)
SLTJOB(*ALL/QSYS/QCMN*) DLTTRC(*YES)
This command formats and prints the trace data contained in database file members named T123456789 in library QGPL. The trace data members are removed after the trace data spooled file has been written. Only those traced jobs that were started under user profile QSYS and had job names that started with "QCMN" will be part of the trace listing.
Example 3: Print Trace and Sort by Time
PRTTRC DTAMBR(MYTRACE) DTALIB(MYTRCLIB)
DLTTRC(*YES) SORT(*TIME)
This command formats and prints the trace data contained in database file members named MYTRACE in library MYTRCLIB. The trace data members are removed after the trace data spooled file has been written. The trace records are sorted by the time the record was collected. If the traced jobs were multithreaded, the trace output is sorted by job, with all threads in that job sorted by time. The resulting output may have trace information for multiple threads intermingled.
Example 4: Print Trace to an Output File
PRTTRC DTAMBR(BIGTRACE) DTALIB(TRACELIB) DLTTRC(*YES)
OUTPUT(*OUTFILE) OUTFILE(MYLIB/MYFILE)
This command stores the trace data contained in database file members named BIGTRACE in library TRACELIB into a database output file named MYFILE in library MYLIB. The trace data members named BIGTRACE are removed after the trace data has been written to the database output file.
| Top |
Error messages
*ESCAPE Messages
- CPF39CD
- Error occurred during processing of the PRTTRC command.
- CPF98A2
- Not authorized to &1 command or API.
| Top |