WATCH_DETAIL table function

The WATCH_DETAIL table function returns the details for watched messages, LIC logs, and PALs for a specific session identifier.

The values returned for the columns in the table function are closely related to the values returned by the WRKWCH (Work with Watches) CL command and by the Retrieve Watch Information (QSCRWCHI) API.

Authorization: The caller must have:

*USE authority to the QSYS/QSCRWCHI program, and
- *SERVICE special authority, or
- Authorization to the QIBM_SERVICE_WATCH and QIBM_SERVICE_TRACE function usage identifiers.

The schema is QSYS2.

session-id: A character or graphic string expression that contains the session identifier that the watch details are returned for.

The result of the function is a table containing rows with the format shown in the following table. All columns are nullable.

Table 1. WATCH_DETAIL table function
Column Name	Data Type	Description
DETAIL_TYPE	VARCHAR(7)	The type of detail information returned by this row. LICLOG This row is for a watched LIC log. MESSAGE This row is for a watched message. PAL This row is for a watched PAL.
COMPARISON_DATA_CCSID	INTEGER	The CCSID that pertains to each of the xxx_COMPARISON_DATA columns. Contains the null value if this row has no comparison data.
The following columns apply when DETAIL_TYPE is MESSAGE. They will contain the null value when DETAIL_TYPE is LICLOG or PAL.
MESSAGE_ID	VARCHAR(7)	The message to be watched. message-id The 7-character message identifier of the message to be watched. generic-name The generic name of the message 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 identifiers that begin with the generic prefix. ALL All messages are to be watched. This includes stored messages and immediate messages. IMMED All immediate or impromptu messages will be watched.
MESSAGE_TYPE	VARCHAR(6)	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.
MESSAGE_QUEUE_LIBRARY	VARCHAR(10)	The name of the library where the message queue is located. Contains the null value if MESSAGE_QUEUE is *JOBLOG.
MESSAGE_QUEUE	VARCHAR(10)	The name of the message queue to watch. Can contain the following special value: *JOBLOG Watch messages added to the job logs of the jobs specified for the watched job field.
MESSAGE_JOB_NAME	VARCHAR(10)	The job name of the job to be watched. Can contain the following special values: generic-name 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. ALL All jobs with the specified job user name are watched. Contains the null value if MESSAGE_QUEUE is not JOBLOG.
MESSAGE_JOB_USER	VARCHAR(10)	The user name of the job to be watched. Can contain the following special values: generic-name 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. ALL All jobs with the specified job name are watched. Contains the null value if MESSAGE_QUEUE is not JOBLOG.
MESSAGE_JOB_NUMBER	VARCHAR(6)	The job number to further qualify the job name and user name. Can contain the following special value: ALL All jobs with the specified job name and user name are watched. Contains the null value if a generic job name or a generic user name qualifier is specified, or if MESSAGE_QUEUE is not JOBLOG.
MESSAGE_SEVERITY	INTEGER	The severity code, ranging from 0 through 99, of the message to be watched.
MESSAGE_RELATIONAL_OPERATOR	CHAR(3)	The relational operator against which the message severity code is compared. EQ Equal GE Greater than or equal GT Greater than LE Less than or equal *LT Less than
MESSAGE_COMPARISON_DATA	VARCHAR(72) CCSID 65535	The 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. Contains the null value if no message comparison data was specified.
MESSAGE_COMPARE_AGAINST	VARCHAR(8)	The part of the message the data specified in MESSAGE_COMPARISON_DATA is to be compared against. FROMPGM The message 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. MSGDTA The message comparison data will be compared against the message replacement data. *TOPGM The message 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. Contains the null value if no message comparison data was specified.
The following columns apply when DETAIL_TYPE is LICLOG. They will contain the null value when DETAIL_TYPE is MESSAGE or PAL.
LIC_MAJOR_CODE	CHAR(4)	The LIC log major code to be watched. A hexadecimal digit or a question mark can be specified 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. Can contain the following special value: *ALL Any LIC log entry major code will be considered to be a match.
LIC_MINOR_CODE	CHAR(4)	The LIC log minor code to be watched. A hexadecimal digit or a question mark can be specified 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. Can contain the following special value: *ALL Any LIC log entry minor code will be considered to be a match.
LIC_COMPARISON_DATA	VARCHAR(72) CCSID 65535	The 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 field specified by the LIC log compare against field, the watched for condition is 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 binary timestamp, 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. The prefix MCH may be specified to compare only against the exception ID field and avoid possible substring matches with the other fields. Contains the null value if no LIC log comparison data was specified.
LIC_COMPARE_AGAINST	VARCHAR(10)	The part of the LIC log the data specified in LIC_COMPARISON_DATA is to be compared against. ALL The LIC log comparison data will be compared against all the fields described below. 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. 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. 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. 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. 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. 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. MODOFFSET The LIC log comparison data will be compared against the byte offset into the LIC module text which requested the LIC log entry. 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. 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 timestamp format. 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. 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. TDENBR The LIC log comparison data will be compared against the number of the task dispatching element (TDE) which requested the LIC log entry. 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 Contains the null value if no LIC log comparison data was specified.
The following columns apply when DETAIL_TYPE is PAL. They will contain the null value when DETAIL_TYPE is MESSAGE or LICLOG.
PAL_SYSTEM_REFERENCE_CODE	VARCHAR(8)	The system reference code to be watched. A hexadecimal digit or a question mark can be specified 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. A generic name that is a character string of one or more characters followed by an asterisk () can also be specified; for example, ABC. The asterisk substitutes for any valid characters. A generic name specifies all PALs with system reference codes that begin with the generic prefix. Can contain the following special value: *ALL Any PAL system reference code will be considered to be a match.
PAL_COMPARISON_DATA	VARCHAR(10) CCSID 65535	The comparison data to be used if a PAL entry matching the specified system reference code was created. If the data specified by PAL compare against field matches the specified text, the watched for condition is true. This text is case sensitive. Question marks (?) and asterisk () wildcard characters can be specified in the text string. A question mark is a single-character wildcard character 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. A single asterisk wildcard character can be specified at the end of the comparison data value. For example, 'ABC' will match any value that begins with the letters 'ABC'. Contains the null value if no PAL comparison data was specified.
PAL_COMPARE_AGAINST	VARCHAR(9)	The part of the PAL the data specified in PAL_COMPARISON_DATA is to be compared against. RSCMODEL The PAL comparison data will be compared against the resource model. RSCNAME The PAL comparison data will be compared against the resource name. *RSCTYPE The PAL comparison data will be compared against the resource type. Contains the null value if no PAL comparison data was specified.

Example

List all the watches that my user profile started with the STRWCH command including the detailed information.

SELECT *
  FROM QSYS2.WATCH_INFO W, TABLE(QSYS2.WATCH_DETAIL(W.SESSION_ID)) D
  WHERE W.WATCH_SESSION_TYPE = '*STRWCH' AND
        W.USER_ID = USER;