Trace ICF (TRCICF)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Trace Intersystems Communications Functions (TRCICF) command is used to start and stop the tracing of language operations and Intersystem Communications Functions (ICF) issued by your program. TRCICF can be started from the command entry display or from a CL program.
As trace records are collected, they are stored in an internal trace storage area. When the trace is ended, the trace records can be directed to a spooled output file or a database physical file.
If the Start Service Job (STRSRVJOB) command is entered before the TRCICF command, the job that is traced is the one specified on the STRSRVJOB command. The trace output from the serviced job is returned to the servicing job after the trace is set off or after the serviced job has ended.
Restrictions:
- The record format of the database output file must match the record format of the IBM-supplied output file, QAIFTRCF.
- The user must have specific authority from the security officer to use this command.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| SET | Trace option setting | *ON, *OFF, *END | Optional, Positional 1 |
| MAXSTG | Maximum storage to use | 1-16000, 200 | Optional, Positional 2 |
| TRCFULL | Trace full | *WRAP, *STOPTRC | Optional, Positional 3 |
| DTALEN | User data length | 0-4096, 128 | Optional, Positional 4 |
| OUTPUT | Output | *PRINT, *OUTFILE | Optional |
| OUTFILE | Output file | Qualified object name | Optional |
| Qualifier 1: Output file | 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 | *REPLACE, *ADD |
| Top |
Trace option setting (SET)
Specifies whether an ICF trace is started, stopped, or ended.
- *ON
- Specifies that the trace ICF is started. If the trace storage area becomes full, the action specified on the TRCFULL parameter is taken.
- *OFF
- Specifies that the trace ICF is stopped. No further ICF activity is recorded and the trace records created are written to the job's spooled printer file or a database file.
- *END
- Specifies that the trace ICF is ended, and all existing trace information is deleted. No output is generated.
| Top |
Maximum storage to use (MAXSTG)
Specifies the maximum amount of storage (in kilobytes) to be used for generated trace records. This parameter is valid only if *ON is specified for the Trace option setting (SET) parameter.
- 200
- Specifies that a maximum of 200 kilobytes is used.
- 1-16000
- Specify the number of kilobytes of storage to use for created records.
| Top |
Trace full (TRCFULL)
Specifies whether new trace records replace old trace records with new records or to stop the trace function when all of the storage specified for the Maximum storage to use (MAXSTG) parameter has been used. This parameter is valid only if *ON is specified for the Trace option setting (SET) parameter.
- *WRAP
- When the trace table is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are generated.
- *STOPTRC
- Tracing is stopped when the trace table is full. You must still enter the TRCICF command and specify *OFF to get the trace output.
| Top |
User data length (DTALEN)
Specifies the maximum length (in bytes) of user data that is traced. This parameter is valid only if *ON is specified for the Trace option setting (SET) parameter.
- 128
- A maximum of 128 bytes of user data is traced.
- 0-4096
- Specify the maximum number of bytes of user data to be traced.
| Top |
Output (OUTPUT)
Specifies whether the output from the command is displayed at the requesting work station or printed with the job's spooled output.
- The output is printed with the job's spooled output.
- *OUTFILE
- The output is saved in a user-specified database file.
| Top |
Output file (OUTFILE)
Specifies the name and library of the physical file to which the trace ICF output is directed. If the database file specified already exists, its record format must match the record format of the IBM-supplied output file, QAIFTRCF.
Qualifier 1: Output file
- name
- Specify the name of the physical file to which the trace output is directed.
Qualifier 2: Library
- *LIBL
- The library list is used to locate the file.
- *CURLIB
- The current library for the job is used to locate the file. If no library is specified as the current library for the job, QGPL is used.
- name
- Specify the name of the library where the file is located.
| Top |
Output member options (OUTMBR)
Specifies the name of the member in the physical file that receives the trace output. If the file specified for the Output file (OUTFILE) parameter is created by the system, a member is created for the file with the name specified. If the OUTFILE exists but the OUTMBR does not, a member with the specified name will is added. This parameter is valid only if SET(*OFF) is specified.
Element 1: Member to receive output
- *FIRST
- The first member of the file specified for the OUTFILE parameter receives the trace output. If the file is created and *FIRST is specified, the name of the created member is the same as that of the created file.
- name
- Specify the name of the member, within the file specified for the OUTFILE parameter, that receives the trace output.
Element 2: Replace or add records
- *REPLACE
- The new data replaces existing data.
- *ADD
- The system adds the new records to the end of the existing records.
| Top |
Examples
Example 1: Starting Trace Operation
TRCICF MAXSTG(350) DTALEN(256)
This command traces the ICF input/output operations of the current job. The trace file contains 350K of storage and wraps to the beginning if that amount of storage is filled with trace records. In addition, this command traces up to 256 bytes of user data on each input/output operation.
Example 2: Stopping Trace Operation
TRCICF SET(*OFF) OUTPUT(*OUTFILE) OUTFILE(TRACELIB/ICFTRACE)
OUTMBR(TRACEMBR)
This command stops the trace and directs the output to the database file ICFTRACE in library TRACELIB. The output is directed to the member TRACEMBR.
| Top |
Error messages
*ESCAPE Messages
- CPF2C90
- Maximum storage specified too small.
- CPF2C93
- No trace records logged.
- CPF2C94
- Error occurred during OUTFILE processing. Trace stopped.
- CPF2C95
- Trace already active.
- CPF2C96
- Trace already off.
- CPF3B34
- Cannot deactivate trace, trace started from another job.
- CPF3205
- File not created.
- CPF3501
- Job is already being serviced, traced, or debugged.
- CPF3530
- Conflicting entries in index QSERVICE.
- CPF3548
- Serviced job completed running.
- CPF3925
- Cannot open file &1.
- CPF3936
- Job being serviced ended before trace started.
- CPF3950
- Error message &2 received for file &1. Request ended.
- CPF3951
- File &1 cannot be overridden by file name &2.
- CPF3969
- Error during close of file &1. Output may not be complete.
- CPF5004
- Printer overflow line detected for file &1.
- CPF9847
- Error occurred while closing file &1 in library &2.
- CPF9848
- Cannot open file &1 in library &2 member &3.
- CPF9849
- Error while processing file &1 in library &2 member &3.
| Top |