Start Communications Trace (STRCMNTRC)
Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Start Communications Trace (STRCMNTRC) command initiates a communications trace for a specified line, a network interface or a network server description.
A communications trace continues until:
- The End Communications Trace (ENDCMNTRC) command is run.
- The Communications Trace function of the Start System Service Tools (STRSST) command is used to end the trace.
- A physical line problem causes the trace to end.
- TRCFULL(*STOPTRC) is specified and the buffer becomes full.
- Automatically by the watch for trace event functionality.
Restrictions:
- The user must have *USE authority to the line, network interface, or network server to be traced.
- 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.
- The following user profiles have authority to this command:
- QSECOFR
- QSRV
- When the Watched job (WCHJOB) parameter is specified, the issuer of the command must be running under a user profile which is the same as the job user identity of the job being watched, or the issuer of the command must be running under a user profile which has job control (*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required if a generic user name is specified for the WCHJOB parameter.
- If you specify a generic user name in the WCHJOB parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch any job function of IBM i through System i Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to start and end watch operations.
- You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the user exit program if specified in Trace program (TRCPGM) parameter, and execute (*EXECUTE) authority to the library where the program is located.
- You must have use (*USE) authority to the message queues specified in Watched message queue (WCHMSGQ) parameter, and use (*USE) authority to the library where the message queue is located.
Top |
Parameters
Keyword | Description | Choices | Notes |
---|---|---|---|
CFGOBJ | Configuration object | Name | Required, Positional 1 |
CFGTYPE | Type | *LIN, *NWI, *NWS | Required, Positional 2 |
MAXSTG | Buffer size | Integer, *MIN, *MAX, 128K, 256K, 2M, 4M, 6M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G, 2G, 4G | Optional |
DTADIR | Data direction | *SND, *RCV, *BOTH | Optional |
TRCFULL | Trace full | *WRAP, *STOPTRC | Optional |
USRDTA | Number of user bytes to trace | Single values: *CALC, *MAX Other values: Element list |
Optional |
Element 1: Beginning bytes | Decimal number | ||
Element 2: Ending bytes | Decimal number, *CALC | ||
CMNTRCOPTS | Communications trace options | *ALLDTA, *RMTCTL, *RMTMAC, *RMTSAP, *LCLSAP, *IPPCLNUM, *RMTIPADR, *VRTLANID | Optional |
DDITRCOPTS | DDI trace options | *ALLDTA, *RMTCTL, *RMTMAC, *RMTSAP, *LCLSAP, *IPPCLNUM, *RMTIPADR | Optional |
RMTCTL | Remote controller | Name | Optional |
RMTMAC | Remote MAC address | Hexadecimal value | Optional |
RMTSAP | Remote SAP | Hexadecimal value | Optional |
LCLSAP | Local SAP | Hexadecimal value | Optional |
IPPCLNUM | IP protocol number | 0-255, *ICMP, *IGMP, *TCP, *EGP, *IGP, *UDP, *ICMPV6 | Optional |
RMTIPADR | Remote IP address | Character value | Optional |
VRTLANID | Virtual LAN identifier | 1-4094, *NONE | Optional |
LMITRCOPTS | LMI trace options | *ALLDTA, *NOLMI, *LMIONLY | Optional |
NWSTRCOPTS | NWS trace options | *NETBIOS, *INTERNAL, *TCPIP | Optional |
WCHMSG | Watch for message | Single values: *NONE Other values (up to 5 repetitions): Element list |
Optional |
Element 1: Message to watch | Generic name, name, *ALL, *IMMED | ||
Element 2: Comparison data | Character value, *NONE | ||
Element 3: Compare against | *MSGDTA, *FROMPGM, *TOPGM | ||
Element 4: Message type | *ALL, *COMP, *DIAG, *ESCAPE, *INFO, *INQ, *NOTIFY, *SCOPE, *STATUS | ||
Element 5: Relational operator | *GE, *EQ, *GT, *LT, *LE | ||
Element 6: Severity code | 0-99, 00 | ||
WCHMSGQ | Watched message queue | Values (up to 3 repetitions): Element list | Optional |
Element 1: Message queue |
Single values: *SYSOPR, *JOBLOG, *HSTLOG Other values: Qualified object name |
||
Qualifier 1: Message queue | Name | ||
Qualifier 2: Library | Name, *LIBL | ||
WCHJOB | Watched job | Single values: * Other values (up to 5 repetitions): Element list |
Optional |
Element 1: Job name | Qualified job name | ||
Qualifier 1: Job name | Generic name, name | ||
Qualifier 2: User | Generic name, name | ||
Qualifier 3: Number | 000001-999999, *ALL | ||
WCHLICLOG | Watch for LIC log entry | Single values: *NONE Other values (up to 5 repetitions): Element list |
Optional |
Element 1: Major code | Character value, *ALL | ||
Element 2: Minor code | Character value, *ALL | ||
Element 3: Comparison data | Character value, *NONE | ||
Element 4: Compare against | *ALL, *TDENBR, *TASKNAME, *SVRTYPE, *JOBNAME, *JOBUSR, *JOBNBR, *THDID, *EXCPID, *MODNAME, *MODRUNAME, *MODEPNAME, *MODOFFSET, *MODTSP | ||
WCHPAL | Watch for PAL entry | Single values: *NONE Other values (up to 5 repetitions): Element list |
Optional |
Element 1: System reference code | Character value, *ALL | ||
Element 2: Comparison data | Character value, *NONE | ||
Element 3: Compare against | *RSCNAME, *RSCTYPE, *RSCMODEL | ||
WCHTIMO | Length of time to watch | 1-43200, *NOMAX | Optional |
TRCPGM | Trace program | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Trace program | Name | ||
Qualifier 2: Library | Name, *LIBL | ||
TRCPGMITV | Time interval | 1-9999, *NONE | Optional |
RUNPTY | Run priority | 1-99, 25 | Optional |
TEXT | Trace description | Character value, *BLANK | Optional |
Top |
Configuration object (CFGOBJ)
Specifies the configuration object to be traced. The object is either a line description, a network interface description, or a network server description.
- name
- Specify the name of the configuration object to be traced.
Top |
Type (CFGTYPE)
Specifies the type of configuration description to trace.
- *LIN
- The configuration object is a line description.
- *NWI
- The configuration object is a network interface description.
- *NWS
- The configuration object is a network server description.
Top |
Buffer size (MAXSTG)
Specifies the trace buffer size.
- 128K
- A trace buffer of 128 kilobytes is used.
- *MIN
- The minimum trace buffer size is used.
- *MAX
- The maximum trace buffer size is used.
- buffer-size
- Specify the trace buffer size. Valid buffer sizes may be specified either as number of kilobytes, or as one of the following special values which has a one-letter suffix of 'K' for kilobytes, 'M' for megabytes, or 'G' for gigabytes: 128K, 256K, 2M, 4M, 6M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G, 2G, 4G. The minimum trace buffer size is 128 kilobytes.
Top |
Data direction (DTADIR)
Specifies the communication data to trace.
Note: For network server description traces, this parameter is ignored and *BOTH is used.
- *BOTH
- Data sent and received by the system is traced.
- *SND
- Data sent by the system is traced.
- *RCV
- Data received by the system is traced.
Top |
Trace full (TRCFULL)
Specifies the action the system takes when the trace buffer is full of data.
- *WRAP
- The trace continues and overwrites the data in the buffer.
- *STOPTRC
- The trace stops.
Top |
Number of user bytes to trace (USRDTA)
Specifies the amount of beginning and ending user data to trace.
Note: For network server description traces and binary synchronous lines, this parameter is ignored and *CALC is used.
Single values
- *CALC
- The system determines the number of beginning and ending bytes to be traced. For LAN lines, this is the first 100 bytes. For other line types, the whole frame is traced.
- *MAX
- Trace as much of frames as possible. For non-LAN, *MAX will be the equivalent of *CALC.
Element 1: Beginning bytes
- decimal-number
- Specify the number of bytes of beginning user data to be traced.
Element 2: Ending bytes
- *CALC
- The system determines the number of ending bytes to be traced.
- decimal-number
- Specify the number of bytes of ending user data to be traced.
Top |
Communications trace options (CMNTRCOPTS)
Specifies the type of data to be traced.
- *ALLDTA
- All data is traced. No filtering is specified.
- *RMTCTL
- The data traveling to and from a remote controller is traced.
- *RMTMAC
- The data traveling to and from a remote medium access control (MAC) address is traced.
- *RMTSAP
- The data traveling to and from a remote service access point (SAP) is traced.
- *LCLSAP
- The data traveling to and from a local service access point (SAP) is traced.
- *IPPCLNUM
- The data within an Internet Protocol (IP) number is traced.
- *RMTIPADR
- The data traveling to and from a remote IP address is traced.
- *VRTLANID
- The data traveling on a virtual LAN is traced.
Top |
DDI trace options (DDITRCOPTS)
The DDITRCOPTS parameter is supported for upward compatibility of CL programs which contain the STRCMNTRC command. The CMNTRCOPTS parameter provides all of the same function as DDITRCOPTS and should be used instead of DDITRCOPTS.
- *ALLDTA
- All data is traced. No filtering is specified.
- *RMTCTL
- The data traveling to and from a remote controller is traced.
- *RMTMAC
- The data traveling to and from a remote medium access control (MAC) address is traced.
- *RMTSAP
- The data traveling to and from a remote service access point (SAP) is traced.
- *LCLSAP
- The data traveling to and from a local service access point (SAP) is traced.
- *IPPCLNUM
- The data within an Internet Protocol (IP) number is traced.
- *RMTIPADR
- The data traveling to and from a remote IP address is traced.
Top |
Remote controller (RMTCTL)
Specifies the remote controller receiving and sending the data to be traced.
- name
- Specify the name of the remote controller.
Top |
Remote MAC address (RMTMAC)
Specifies the remote medium access control address receiving and sending the data to be traced.
- hexadecimal-value
- Specify the remote medium access control address.
Top |
Remote SAP (RMTSAP)
Specifies the remote service access point receiving and sending the data to be traced.
- hexadecimal-value
- Specify the remote service access point.
Top |
Local SAP (LCLSAP)
Specifies the local service access point receiving and sending the data to be traced.
- hexadecimal-value
- Specify the local service access point.
Top |
IP protocol number (IPPCLNUM)
Specifies the Internet Protocol (IP) number to be traced.
- *ICMP
- The Internet control message group is traced.
- *IGMP
- The Internet group management protocol group is traced.
- *TCP
- The transmission control group is traced.
- *EGP
- The exterior gateway protocol group is traced.
- *IGP
- A private interior gateway group is traced.
- *UDP
- The user datagram group is traced.
- *ICMPv6
- The Internet control message protocol for IPv6 is traced.
- 0-255
- Specify the Internet Protocol (IP) number to trace.
Top |
Remote IP address (RMTIPADR)
Specifies the remote Internet Protocol (IP) address to be traced. Internet Protocol version 4 (IPv4), Internet Protocol version 6 (IPv6) and IPv4-mapped IPv6 addresses are supported.
When IPv6 or IPv4-mapped IPv6 addresses are specified, Dump Communications Trace (DMPCMNTRC) command must be used to copy the collected data to a stream file, followed by Print Communications Trace (PRTCMNTRC) command.
- character-value
- Specify the remote IP address to be traced.
Top |
Virtual LAN identifier (VRTLANID)
Specifies the virtual LAN identifier to be traced.
- 1-4094
- Specify the virtual LAN identifier to be traced.
- *NONE
- Only frames containing no virtual LAN identifier will be traced.
Top |
LMI trace options (LMITRCOPTS)
Specifies the type of data to be placed in the trace buffer.
- *ALLDTA
- All data, including the local management interface (LMI), is placed in the trace buffer.
- *NOLMI
- All data, except LMI data, is placed in the trace buffer.
- *LMIONLY
- Only LMI data is placed in the trace buffer.
Top |
NWS trace options (NWSTRCOPTS)
Specifies the type of data to be placed in the trace buffer.
- *NETBIOS
- All NetBIOS data is placed in the trace buffer.
- *INTERNAL
- The communications processor operating system data is placed in the trace buffer.
- *TCPIP
- All TCP/IP data for network server description applications is placed in the trace buffer.
Top |
Watch for message (WCHMSG)
Specifies up to five messages which are to be watched. If a value other than *NONE is specified, you must specify where to watch for the message on the WCHMSGQ parameter. When the watched for message is added to the specified message queue or log, the trace exit program is called; if no trace exit program is defined, the trace stops.
Note: Moved and resent messages will not be watched. Only the original instance of the message can be watched.
Note: Watching for message id CPF1124 or CPF1164 will be ignored in job QSCWCHPS (which handles watch processing). A user exit program will not be triggered when CPF1124 or CPF1164 is issued in job QSCWCHPS.
Single values
- *NONE
- No messages will be watched.
Element 1: Message to watch
- *ALL
- All messages are to be watched. This includes stored messages and immediate messages. Be aware that watching for all messages might cause performance degradation on your system. Use it cautiously.
- *IMMED
- All immediate or impromptu messages will be watched.
- generic-name
- Specify the generic message identifier to be watched. 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 message name specifies all messages with message identifiers that begin with the generic prefix.
- name
- Specify the 7-character message identifier to be watched.
Element 2: Comparison data
Specify comparison data to be used if a message matching the specified message is added to the specified message queue or log. If the message data, the "From program" or the "To program" includes the specified text, the watched for condition is true. If the message data, the "From program" or the "To program" does not contain the specified text, the trace function continues.
- *NONE
- No comparison data is specified. If a message matching the specified message is added to the specified message queue or log, the watched for condition is true.
- character-value
- Specify the text string used to compare against the message data, the "From program" or the "To program" of the watched for message. This text is case sensitive and can be quoted in order to specify imbedded or trailing blanks.
Element 3: Compare against
Specify which part of the message the comparison data specified for element 2 is to be compared against.
- *MSGDATA
- The comparison data will be compared against the message replacement data.
- *FROMPGM
- The comparison data will be compared against the name of the program sending the message, or the name of the ILE program that contains the procedure sending the message.
- *TOPGM
- The comparison data will be compared against the name of the program the message was sent to, or the name of the ILE program that contains the procedure the message was sent to.
Element 4: Message type
Specify the message type assigned to the message to be watched.
- *ALL
- All the message types are to be watched. This includes completion, command, diagnostic, escape, informational, inquiry, notify, reply, request, sender's copy, scope and status message types.
- *COMP
- A completion message is to be watched.
- *DIAG
- A diagnostic message is to be watched.
- *ESCAPE
- An escape message is to be watched.
- *INFO
- An informational message is to be watched.
- *INQ
- An inquiry message is to be watched.
- *NOTIFY
- A notify message is to be watched.
- *SCOPE
- A scope message is to be watched.
- *STATUS
- A status message is to be watched.
Element 5: Relational operator
Specify one relational operator against which the message severity code is compared.
- *GE
- Greater than or equal.
- *EQ
- Equal.
- *GT
- Greater than.
- *LT
- Less than.
- *LE
- Less than or equal.
Element 6: Severity code
Specifies the severity code of the message to be watched.
- 00
- The severity code assigned to the message to be watched for is 00.
- Severity-code
- Specify a value, ranging from 00 through 99, as the severity level associated with the message to be watched.
Top |
Watched message queue (WCHMSGQ)
Specifies where to watch for the messages specified on the WCHMSG parameter. You can specify to watch the message being added to the system operator message queue, the history log, other message queues, and job logs. Up to three message queues or special values can be specified.
Element 1: Message queue
Single values
- *SYSOPR
- Watch messages added to the system operator message queue (QSYSOPR message queue in library QSYS).
- *JOBLOG
- Watch messages added to the job logs of the jobs specified for the Watched job (WCHJOB) parameter.
- *HSTLOG
- Watch messages added to the history log (QHST message queue in library QSYS).
Qualifier 1: Message queue
- name
- Specify the name of the message queue to watch.
Qualifier 2: Library
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- name
- Specify the name of the library where the message queue is located.
Top |
Watched job (WCHJOB)
Specifies the job whose job log is watched for the messages specified on the WCHMSG parameter. The specified job will only be watched if *JOBLOG is specified on the WCHMSGQ parameter. Up to five job names may be specified.
Single values
- *
- Only the job log of the job that issued this trace command is watched.
Element 1: Job name
Qualifier 1: Job name
- generic-name
- Specify the generic name of the job to be watched. 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 watched.
Qualifier 2: User
- generic-name
- Specify the generic name of the user name of the job to be watched. 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 user name specifies all jobs with the specified job name and with user names that begin with the generic prefix.
- name
- Specify the user name of the job to be watched.
Qualifier 3: Number
- *ALL
- All jobs with the specified job name and user name are watched.
- 000001-999999
- Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name or a generic user name qualifier is specified.
Top |
Watch for LIC log entry (WCHLICLOG)
Specifies up to five licensed internal code (LIC) log entry identifiers which are to be watched for. Each LIC log entry contains a major and a minor code. The watched for condition will be met if a LIC log entry is added that matches the specified major and minor codes and any comparison data specified. When the watched for log entry is added to the LIC log, the trace exit program is called, even when the comparison data specified does not match; if no trace exit program is defined, the trace stops.
Single values
- *NONE
- No LIC log entries will be watched for.
Element 1: Major code
- *ALL
- Any LIC log entry major code will be considered to be a match. If *ALL is specified for the major code, you cannot specify *ALL for the LIC log entry minor code.
- character-value
- Specify the LIC log major code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
Element 2: Minor code
- *ALL
- Any LIC log entry minor code will be considered to be a match. If *ALL is specified for the minor code, you cannot specify *ALL for the LIC log entry major code.
- character-value
- Specify the LIC log minor code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
Element 3: Comparison data
Specify comparison data to be used if a log entry matching the specified major and minor codes is added to the licensed internal code (LIC) log. If this text is found in the LIC log entry data fields of the watched for log entry, the watched for condition is true. If this text is not found in the LIC log entry data fields of the watched for log entry and no exit program is specified on the TRCPGM parameter, the trace function continues. If the log entry matches the specified major and minor codes and an exit program is specified on the TRCPGM parameter, but the entry data does not contain the specified text, the exit program is called to determine if the trace should continue or stop.
- *NONE
- No comparison data is specified. If a LIC log entry matching the specified major and minor codes is added to the LIC log, the watched for condition is true.
- character-value
- Specify the text string used to compare against the entry data of the watched for log entry. If this text is found in the LIC log entry data field specified for element 4, the watch condition is considered to be true. This text is case sensitive. If *ALL is specified in the LIC log compare against field, the LIC log fields which will be compared are TDE number, task name, server type, job name, user ID, job number, thread ID, exception ID, LIC module compile timestamp, LIC module offset, LIC module RU name, LIC module name, LIC module entry point name. The comparison data cannot be used to match across two fields, and can match an entire field or a substring of any field.
When watching for an exception ID, all four hexadecimal digits of the exception ID must be specified. Also, the prefix MCH may be specified if you want to compare only against the exception ID field and avoid possible substring matches with the other fields.
Element 4: Compare against
Specify which part of the LIC log the comparison data specified for element 3 is to be compared against.
- *ALL
- The LIC log comparison data will be compared against all the fields described below.
- *TDENBR
- The LIC log comparison data will be compared against the number of the task dispatching element (TDE) which requested the LIC log entry.
- *TASKNAME
- The LIC log comparison data will be compared against the name of the task which requested the LIC log entry. Task name is blank (hex 40s) if the LIC log entry is not requested by a task.
- *SVRTYPE
- The LIC log comparison data will be compared against the type of server that requested the LIC log entry. Server type is blank (hex 40s) if the LIC log entry is not requested by a server.
- *JOBNAME
- The LIC log comparison data will be compared against the name of the job which requested the LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry is not requested by a job.
- *JOBUSR
- The LIC log comparison data will be compared against the user name of the job which requested the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry is not requested by a job.
- *JOBNBR
- The LIC log comparison data will be compared against the job number (000001-999999) to further qualify the job name and user name of the job which requested the LIC log entry. LIC job number is blank (hex 40s) if the LIC log entry is not requested by a job.
- *THDID
- The LIC log comparison data will be compared against the thread which requested the LIC log entry. Thread identifier is binary zeros if the LIC log entry is not requested by a thread.
- *EXCPID
- The LIC log comparison data will be compared against the exception that caused the LIC log entry to be requested. This is a 2-byte hexadecimal field formed by concatenating to the high-order 1-byte exception group number a low-order 1-byte exception subtype number. Exception identifier is binary zeros if the LIC log entry is not requested as a result of an exception.
- *MODNAME
- The LIC log comparison data will be compared against the LIC module name which requested the LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated to 64 characters.
- *MODRUNAME
- The LIC log comparison data will be compared against the LIC module replacement unit name. LIC module RU name is always in upper case EBCDIC.
- *MODEPNAME
- The LIC log comparison data will be compared against the name of the entry point which requested the LIC log entry. If the entry point name is greater than 128 characters, the LIC module entry point name is truncated to 128 characters.
- *MODOFFSET
- The LIC log comparison data will be compared against the byte offset into the LIC module text which requested the LIC log entry.
- *MODTSP
- The LIC log comparison data will be compared against the timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format.
Top |
Watch for PAL entry (WCHPAL)
Specifies up to five Product Activity Log (PAL) entries which are to be watched for. When the watched for PAL occurs, the trace exit program is called; if no trace exit program is defined, the trace stops.
Single values
- *NONE
- No PAL entries will be watched for.
Other values (up to 5 repetitions)
Element 1: System reference code
- *ALL
- Any system reference code will be considered to be a match.
- character-value
- Specify the system reference code (SRC) to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the eight-digit code. A question mark is a wildcard character that will match any digit in that position. Up to seven wildcard characters can be specified. You can also specify a generic SRC that 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 SRC specifies all PAL entries with system reference codes that begin with the generic prefix.
Element 2: Comparison data
Specify comparison data to be used if a PAL entry matching the specified system reference code occurs. If the field specified in element 3 matches the specified text, the watched for condition is true. If the field specified in element 3 does not match the specified text, the watch function just continues.
- *NONE
- No comparison data is specified. If a PAL entry matching the specified system reference code occurs, the watched for condition is true.
- character-value
- Specify the text string used to compare against the field specified in element 3 of the watched for PAL entry. This text is case sensitive.
You can specify question mark (?) and asterisk (*) wildcard characters in the text string. A question mark is a single-character wildcard and will match any character in the same position. For example, '??123' will match any value that is five characters long and ends with '123'. Multiple question mark wildcard characters can be specified for the comparison data value.
An asterisk is a multiple-character wildcard character. You can specify a single asterisk wildcard character at the end of the comparison data value. For example, 'ABC*' will match any value that begins with the letters 'ABC'.
Element 3: Compare against
Specify which part of the PAL entry the comparison data specified for element 2 is to be compared against.
- *RSCNAME
- The comparison data will be compared against the name of the physical device that has the entry in the log. A resource name is assigned at first by the system, but may have been changed to a new value by a user.
- *RSCTYPE
- The comparison data will be compared against the number or word used to identify a product.
- *RSCMODEL
- The comparison data will be compared against the numbers or letters used to identify the feature level of a product with a given type.
Top |
Length of time to watch (WCHTIMO)
Specifies the time limit, in minutes, for watching for a message or a licensed internal code (LIC) log entry or a Product Activity Log (PAL) entry. When the specified amount of time has elapsed, the trace exit program is called (if one was specified on the TRCPGM parameter), the trace is ended, and message CPI3999 is sent to the history log.
- *NOMAX
- There is no time limit for watching for a particular message or LIC log entry or PAL entry.
- 1-43200
- Specify the number of minutes that the trace will remain active while none of the watched for conditions have been met.
Top |
Trace program (TRCPGM)
Specifies the program to be called for user-defined trace commands and procedures.
The trace program will be called:
- Before the application trace starts.
- After a match of a message specified for the WCHMSG parameter, or a match of a Licensed Internal Code (LIC) log entry specified for the WCHLICLOG parameter, or a match of a Product Activity Log (PAL) entry specified for the WCHPAL parameter occurs.
- When the time interval specified on the TRCPGMITV parameter is reached.
- When the length of time to watch specified on WCHTIMO parameter is reached.
There are three input parameters and one output parameter associated with the trace program. The four parameters are required:
1 Trace option setting Input Char(10) 2 Reserved Input Char(10) 3 Error detected Output Char(10) 4 Comparison data Input Char(*)
Allowed values for the "Trace option setting" parameter are:
- *ON
- The watch for trace facility is starting when the collection of trace information is started.
- *MSGID
- A match on a message specified on WCHMSG parameter occurred.
- *LICLOG
- A match on a LIC log specified on the WCHLICLOG parameter occurred.
- *CMPDATA
- The major and minor code of a LIC log matched, but the comparison data did not.
- *INTVAL
- The time interval specified on TRCPGMITV parameter is elapsed.
- *WCHTIMO
- The length of time to watch specified on WCHTIMO parameter is elapsed.
- *PAL
- A match on a PAL and any associated comparison data specified on the WCHPAL parameter occurred.
The "Reserved" parameter must be set to blanks.
Allowed values for the "Error detected" parameter are:
- *CONTINUE
- The trace and the watch for trace event facility will continue running.
- *STOP
- The trace and the watch for trace event facility will be ended.
- *ERROR
- Error detected by customer trace program.
Allowed values for the "Comparison data" parameter when *MSGID is specified for the "Trace option setting" parameter will be the following structure:
OFFSET TYPE FIELD Dec Hex 0 0 BINARY(4) Length of trace information 4 4 CHAR(7) Message watched 11 B CHAR(9) Reserved 20 14 BINARY(4) Offset to comparison data 24 18 BINARY(4) Length of comparison data * * CHAR(*) Message comparison data
Allowed values for the "Comparison data" parameter when *LICLOG or *CMPDATA is specified for the "Trace option setting" parameter will be the following structure:
OFFSET TYPE FIELD Dec Hex 0 0 BINARY(4) Length of trace information 4 4 CHAR(4) LIC Log major code 8 8 CHAR(4) LIC Log minor code 12 C CHAR(8) LIC Log id (keyword DMPID on PRTINTDTA) 20 14 BINARY(4) Offset to comparison data 24 18 BINARY(4) Length of comparison data * * CHAR(*) LIC log comparison data
Allowed values for the "Comparison data" parameter when *ON, *INTVAL or *WCHTIMO is specified for the "Trace option setting" parameter will be the following structure:
OFFSET TYPE FIELD Dec Hex 0 0 BINARY(4) Length of trace information (always 4).
Allowed values for the "Comparison data" parameter when *PAL is specified for the "Trace option setting" parameter will be the following structure:
OFFSET TYPE FIELD Dec Hex 0 0 BINARY(4) Length of watch information 4 4 CHAR(8) System reference code 12 C CHAR(10) Device name 22 16 CHAR(4) Device type 26 1A CHAR(4) Model 30 1E CHAR(15) Serial number 45 2D CHAR(10) Resource name 55 37 CHAR(8) Error Log id (keyword ERRLOGID on PRTERRLOG) 63 3F CHAR(8) PAL timestamp 71 47 CHAR(4) Reference code 75 4B CHAR(8) Secondary code 83 53 CHAR(8) Table identifier 91 5B CHAR(1) Reserved 92 5C BINARY(4) Sequence 96 60 BINARY(4) Offset to comparison data 100 64 BINARY(4) Length of comparison data 104 68 CHAR(10) PAL compare against * * CHAR(*) PAL comparison data
For more information on the trace exit program interface, refer to the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/
Single values
- *NONE
- No trace exit program is defined. If a watched for message or licensed internal code (LIC) log entry or Product Activity Log (PAL) entry is added, or if the specified watch time limit is exceeded, the trace function ends.
Qualifier 1: Trace program
- name
- Specify the name of the trace exit program.
Qualifier 2: Library
- *LIBL
- All libraries in the job's library list are searched until the first match is found.
- name
- Specify the name of the library where the user exit program is located.
Top |
Time interval (TRCPGMITV)
Specifies how often the trace exit program will be called.
- *NONE
- No time interval is specified. The trace exit program will not be called because a time interval has elapsed.
- 1-9999
- Specify the interval of time, in seconds, of how often the trace exit program will be called. This must be less than the amount of time specified for the Length of time to watch (WCHTIMO) parameter.
Top |
Run priority (RUNPTY)
Specifies the priority of the job where the watch session work will be run.
- 25
- A job priority of 25 will be used.
- 1-99
- Specify the run priority of the job. For more information on job run priority, refer to the Work management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/
Top |
Trace description (TEXT)
Specifies the text that briefly describes the object.
- *BLANK
- Text is not specified.
- character-value
- Specify up to 20 characters of text.
Top |
Examples
Example 1: Start a Communications Trace for a Line Description
STRCMNTRC CFGOBJ(*QESLINE) CFGTYPE(*LIN)
This command starts a communications trace of line description QESLINE.
Example 2: Start a Trace and Watch for a Message to End the Trace
STRCMNTRC CFGOBJ(LINE001) CFGTYPE(*LIN) WCHMSG((MCH2804)) WCHMSGQ((*SYSOPR) (*JOBLOG)) WCHJOB((*ALL/MYUSER/MYJOBNAME)) TRCPGM(MYLIB/TRCEXTPGM)
This command starts a communications trace of line description LINE001. The trace will be ended when MCH2804 message is found on the System Operator message queue or within the *ALL/MYUSER/MYJOBNAME job log. Also, MYLIB/TRCEXTPGM is specified as a trace exit program.
Example 3: Start a Trace and Watch for a LIC Log Entry to End the Trace
STRCMNTRC CFGOBJ(LINE001) CFGTYPE(*LIN) WCHLICLOG(('99??' 9932 MYJOBNAME)) WCHTIMO(*NOMAX)
This command starts a communications trace of line description LINE001. The trace will be ended when a Licensed Internal Code (LIC) log entry that has a major code starting with 99 and a minor code of 9932 is generated on the system. Also, the LIC log information should contain the text "MYJOBNAME". *NOMAX on WCHTIMO parameter indicates that the trace will be active until the event occurs or ENDCMNTRC command is issued manually.
Top |
Error messages
*ESCAPE Messages
- CPF2601
- Line description &1 not found.
- CPF2634
- Not authorized to object &1.
- CPF39AA
- Trace &1 type &2 already exists
- CPF39AB
- Beginning or ending bytes exceeds maximum value
- CPF39AC
- Total of beginning and ending bytes exceeds maximum value
- CPF39AD
- &1 type &2 cannot be traced
- CPF39A6
- Storage could not be allocated
- CPF39A7
- Trace storage not available in communications processor
- CPF39A8
- Not authorized to communications trace service tool
- CPF39A9
- Error occurred during communications trace function
- CPF39BD
- Network interface description &1 not found
- CPF39BF
- Remote IP address not valid.
- CPF39B6
- Communications trace function cannot be performed
- CPF39C0
- Controller description &1 not found.
- CPF39C1
- Controller description &1 not valid.
- CPF39C2
- Number of user bytes to trace must be *CALC.
- CPF39F1
- Trace buffer size too large.
- CPF39F2
- Cannot allocate library &1
- CPF98A2
- Not authorized to &1 command or API.
Top |