TRCICF (Trace ICF)

TRCICF Command syntax diagram

 

Purpose

The Trace Intersystems Communications Functions (TRCICF) command controls tracing of all ICF I/O functions that occur in the job in which the command is entered. The command sets a trace on or off, and traces (1) ICF operations and functions issued by a program and (2) data that is sent and received.

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

1. The record format of the database output file must match the record format of the IBM-supplied output file, QAIFTRCF.
2. The user must have specific authority from the security officer to use this command.

 

Optional Parameters

SET

Specifies whether an ICF trace is started or ended.

*ON: The trace is started. If the trace storage area becomes full, the action specified on the TRCFULL parameter is taken.

*OFF: The trace is ended. No other trace information is recorded, and the current information is written to the spooled output file or a database file.

*END: The trace ends. All trace information is deleted. No output is generated.

MAXSTG

Specifies the maximum amount of storage (in kilobytes) used for the created trace records.

200: Up to 200KB of storage is used for trace records.

number-of-kilobytes: Specify the number of kilobytes of storage to use for trace records. Valid values range from 1 through 16000.

TRCFULL

Specifies the action taken when the maximum storage specified is full.

*WRAP: When the trace storage area is full, new trace information is written over old information, starting at the beginning of the storage area.

*STOPTRC: When the trace storage area is full, no new trace information is saved.

DTALEN

Specifies the maximum length (in bytes) of user data that can be saved for each trace entry in the storage area. If the value specified is greater than the length of data received or sent across the communications line, only the actual data is traced. If the value specified is less than the data length received or sent, only the data length specified on this parameter is traced.

128: The maximum length of user data saved is 128 bytes.

number-of-bytes: Specify the maximum length of user data saved. Valid values range from 0 through 4096.

OUTPUT

Specifies whether the output from the command is printed with the job's spooled output or is directed to a database file. More information on this parameter is in Commonly used parameters.

*PRINT: The output is printed with the job's spooled output.

*OUTFILE: The output is directed to the database file specified on the OUTFILE parameter.

OUTFILE

Specifies the qualified name of the physical file to which the trace output is directed. If the file already exists, the system uses it. If the file does not exist, the system creates it. If the file is created, the text is "OUTFILE created by TRCICF command." *EXCLUDE authority is assigned to users with no specific authority.

The name of the database file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the physical file to which the trace output is directed.

OUTMBR

Specifies the name of the database file member to which the output is directed. If a member already exists, the system uses the second element of this parameter to determine whether the member is cleared before the new records are added. If the member does not exist and a member name is not specified, the system creates a member with the name of the output file specified on the OUTFILE parameter. If an output file member name is specified, but the member does not exist, the system creates it.

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 on the OUTFILE parameter.

member-name: Specify the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.

Element 2: Operation to Perform on Member

*REPLACE: The system clears the existing member and adds the new records.

*ADD: The system adds the new records to the end of the existing records.

Examples for TRCICF

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.

Error messages for TRCICF

*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.