646 lines
27 KiB
HTML
646 lines
27 KiB
HTML
|
|
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>Start Watch (STRWCH)</title>
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<a name="STRWCH.Top_Of_Page"></a>
|
|
<h2>Start Watch (STRWCH)</h2>
|
|
<table width="100%">
|
|
<tr>
|
|
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
|
|
<b>Threadsafe: </b>No
|
|
</td>
|
|
<td valign="top" align="right">
|
|
<a href="#STRWCH.PARAMETERS.TABLE">Parameters</a><br>
|
|
<a href="#STRWCH.COMMAND.EXAMPLES">Examples</a><br>
|
|
<a href="#STRWCH.ERROR.MESSAGES">Error messages</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<div> <a name="STRWCH"></a>
|
|
<p>The Start Watch (STRWCH) command starts the watch for event function, which notifies the user by calling a user specified program when the specified event (a message or LIC log) occurs. Up to 10000 watch sessions can be active at a time but active watch session identifiers must be unique across the system.
|
|
</p>
|
|
<p>The watch session continues until ended with the End Watch (ENDWCH) command or with the End Watch (QSCEWCH) API. A watch session can be ended from the same job or a different job.
|
|
</p>
|
|
<p><b>Restrictions:</b>
|
|
</p>
|
|
<ul>
|
|
<li>To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service watch function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_WATCH, can also be used to change the list of users that are allowed to start and end watch operations.
|
|
</li>
|
|
<li>When the <b>Watched job (WCHJOB)</b> 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.
|
|
</li>
|
|
<li>If you specify *ALL for the watched job name, or a generic user name, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch Any Job function of Operating System through iSeries 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.
|
|
</li>
|
|
<li>You must have operatinal (*OBJOPR) and execute (*EXECUTE) authorities to the watch program to be called, and execute (*EXECUTE) authority to the library where the program is located.
|
|
</li>
|
|
<li>You must have use (*USE) authority to the message queues specified in <b>Watched message queue (WCHMSGQ)</b> parameter, and use (*USE) authority to the library where the message queue is located.
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
|
|
<div>
|
|
<h3><a name="STRWCH.PARAMETERS.TABLE">Parameters</a></h3>
|
|
<table border="1" cellpadding="4" cellspacing="0">
|
|
<!-- col1="10" col2="15" col3="30" col4="10" -->
|
|
<tr>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#STRWCH.SSNID"><b>SSNID</b></a></td>
|
|
<td valign="top">Session ID</td>
|
|
<td valign="top"><i>Name</i>, *GEN</td>
|
|
<td valign="top">Required, Positional 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" rowspan="3"><a href="#STRWCH.WCHPGM"><b>WCHPGM</b></a></td>
|
|
<td valign="top">Watch program</td>
|
|
<td valign="top"><i>Qualified object name</i></td>
|
|
<td valign="top" rowspan="3">Required, Positional 2</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Qualifier 1: Watch program</td>
|
|
<td valign="top"><i>Name</i></td>
|
|
</tr><tr>
|
|
<td valign="top">Qualifier 2: Library</td>
|
|
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
|
|
</tr><tr>
|
|
<td valign="top" rowspan="4"><a href="#STRWCH.WCHMSG"><b>WCHMSG</b></a></td>
|
|
<td valign="top">Watch for message</td>
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
|
<td valign="top" rowspan="4">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 1: Message identifier</td>
|
|
<td valign="top">
|
|
<i>Name</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 2: Comparison data</td>
|
|
<td valign="top">
|
|
<i>Character value</i>, <b><u>*NONE</u></b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 3: Compare against</td>
|
|
<td valign="top">
|
|
<b><u>*MSGDTA</u></b>, *FROMPGM, *TOPGM</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" rowspan="4"><a href="#STRWCH.WCHMSGQ"><b>WCHMSGQ</b></a></td>
|
|
<td valign="top">Watched message queue</td>
|
|
<td valign="top">Values (up to 3 repetitions): <i>Element list</i></td>
|
|
<td valign="top" rowspan="4">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 1: Message queue</td>
|
|
<td valign="top">
|
|
Single values: <b><u>*SYSOPR</u></b>, *JOBLOG, *HSTLOG<br>Other values: <i>Qualified object name</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" style="padding-left:10pt">Qualifier 1: Message queue</td>
|
|
<td valign="top"><i>Name</i></td>
|
|
</tr><tr>
|
|
<td valign="top" style="padding-left:10pt">Qualifier 2: Library</td>
|
|
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b></td>
|
|
</tr><tr>
|
|
<td valign="top" rowspan="5"><a href="#STRWCH.WCHJOB"><b>WCHJOB</b></a></td>
|
|
<td valign="top">Watched job</td>
|
|
<td valign="top">Single values: <b><u>*</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
|
<td valign="top" rowspan="5">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 1: Job name</td>
|
|
<td valign="top">
|
|
<i>Qualified job name</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" style="padding-left:10pt">Qualifier 1: Job name</td>
|
|
<td valign="top"><i>Generic name, name</i>, *ALL</td>
|
|
</tr><tr>
|
|
<td valign="top" style="padding-left:10pt">Qualifier 2: User</td>
|
|
<td valign="top"><i>Generic name, name</i>, *ALL</td>
|
|
</tr><tr>
|
|
<td valign="top" style="padding-left:10pt">Qualifier 3: Number</td>
|
|
<td valign="top">000001-999999, <b><u>*ALL</u></b></td>
|
|
</tr><tr>
|
|
<td valign="top" rowspan="4"><a href="#STRWCH.WCHLICLOG"><b>WCHLICLOG</b></a></td>
|
|
<td valign="top">Watch for LIC log entry</td>
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
|
<td valign="top" rowspan="4">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 1: Major code</td>
|
|
<td valign="top">
|
|
<i>Character value</i>, *ALL</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 2: Minor code</td>
|
|
<td valign="top">
|
|
<i>Character value</i>, *ALL</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Element 3: Comparison data</td>
|
|
<td valign="top">
|
|
<i>Character value</i>, <b><u>*NONE</u></b></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
</div>
|
|
<div> <a name="STRWCH.SSNID"></a>
|
|
<h3>Session ID (SSNID)</h3>
|
|
<p>Specifies a session identifier for this watch. This identifier must be unique across all active watches on the system.
|
|
</p>
|
|
<p>This is a required parameter.
|
|
</p>
|
|
<dl>
|
|
<dt><b>*GEN</b></dt>
|
|
<dd>The system will generate a unique session identifier for this watch.
|
|
</dd>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the session identifier for this watch. You cannot specify a session identifier that starts with "QSC".
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="STRWCH.WCHPGM"></a>
|
|
<h3>Watch program (WCHPGM)</h3>
|
|
<p>Specifies the user exit program to be called to notify that a specified watch event occurred. The exit program will be called once for each message id and LIC log entry specified on this command. That is, if a message is watched on a message queue and in a job log, and the message is sent to both locations, the exit program will be called twice.
|
|
</p>
|
|
<p>This is a required parameter.
|
|
</p>
|
|
<p>The watch program will be called:
|
|
</p>
|
|
<ul>
|
|
<li>After a match of a message identifier and any associated comparison data specified for the WCHMSG parameter, or a match of a Licensed Internal Code (LIC) log entry and any associated comparison data specified for the WCHLICLOG parameter occurs.
|
|
</li>
|
|
</ul>
|
|
<p>There are three input parameters and one output parameter associated with the watch program. The four parameters are required:
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
1 Watch option setting Input Char(10)
|
|
2 Session Id Input Char(10)
|
|
3 Error detected Output Char(10)
|
|
4 Event data Input Char(*)
|
|
</pre>
|
|
</p>
|
|
<p>Allowed values for the "Watch option setting" parameter are:
|
|
</p>
|
|
<dl>
|
|
<dt><b>*MSGID</b></dt>
|
|
<dd>A match on a message id and any associated comparison data specified on WCHMSG parameter occurred.
|
|
</dd>
|
|
<dt><b>*LICLOG</b></dt>
|
|
<dd>A match on a LIC log and any associated comparison data specified on the WCHLICLOG parameter occurred.
|
|
</dd>
|
|
</dl>
|
|
<p>The "Session ID" parameter contains the name of the watch session that is calling the user exit program.
|
|
</p>
|
|
<p>Allowed values for the "Error detected" parameter are:
|
|
</p>
|
|
<dl>
|
|
<dt><b>*ERROR</b></dt>
|
|
<dd>Error detected by watch exit program. The watch session that was passed in Session ID parameter will be ended. If the watch session to be ended originally specified multiple message ids or LIC log entries, all of them will no longer be watched. CPI3999 message will be sent to the job log and message queue QSYSOPR to indicate an error in the exit program caused the watch session to be ended.
|
|
</dd>
|
|
<dt><b><blanks></b></dt>
|
|
<dd>No error detected by watch exit program.
|
|
</dd>
|
|
</dl>
|
|
<p>Note: Any value other than "*ERROR" or <blanks> will be considered an error and the watch session that was passed in Session ID parameter will be ended. If the watch session to be ended originally specified multiple message ids or LIC log entries, all of them will no longer be watched. CPI3999 message will be sent to the job log and message queue QSYSOPR to indicate an error in the exit program caused the watch session to be ended.
|
|
</p>
|
|
<p>Allowed values for the "Event data" parameter when *MSGID is specified for the "Watch option setting" parameter will be the following structure:
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
OFFSET TYPE FIELD
|
|
Dec Hex
|
|
0 0 BINARY(4) Length of watch information
|
|
4 4 CHAR(7) Message ID
|
|
11 B CHAR(1) Reserved
|
|
12 C CHAR(10) Message queue name
|
|
22 16 CHAR(10) Message queue library
|
|
32 20 CHAR(10) Job name
|
|
42 2A CHAR(10) User name
|
|
52 34 CHAR(6) Job number
|
|
58 3A CHAR(4) Reserved
|
|
62 3E CHAR(256) Sending program name
|
|
318 13E CHAR(10) Sending module name
|
|
328 148 BINARY(4) Offset to sending procedure name
|
|
332 14C BINARY(4) Length of sending procedure name
|
|
336 150 CHAR(10) Receiving program name
|
|
346 15A CHAR(10) Receiving module name
|
|
356 164 BINARY(4) Offset to receiving procedure name
|
|
360 168 BINARY(4) Length of receiving procedure name
|
|
364 16C BINARY(4) Message severity
|
|
368 170 CHAR(10) Message type
|
|
378 17A CHAR(8) Message timestamp
|
|
386 182 CHAR(4) Message key
|
|
390 186 CHAR(10) Message file name
|
|
400 190 CHAR(10) Message file library
|
|
410 19A CHAR(2) Reserved
|
|
412 19C BINARY(4) Offset to comparison data
|
|
416 1A0 BINARY(4) Length of comparison data
|
|
420 1A4 CHAR(10) Compare against
|
|
430 1AE CHAR(2) Reserved
|
|
432 1B0 BINARY(4) Comparison data CCSID
|
|
436 1B4 BINARY(4) Offset where comparison data was found
|
|
440 1B8 BINARY(4) Offset to replacement data
|
|
444 1BC BINARY(4) Length of replacement data
|
|
448 1C0 BINARY(4) Replacement data CCSID
|
|
* * CHAR(*) Sending procedure name
|
|
* * CHAR(*) Receiving procedure name
|
|
* * CHAR(*) Message comparison data
|
|
* * CHAR(*) Message replacement data
|
|
</pre>
|
|
</p>
|
|
<p>Allowed values for the "Event data" parameter when *LICLOG is specified for the "Watch option setting" parameter will be the following structure:
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
OFFSET TYPE FIELD
|
|
Dec Hex
|
|
0 0 BINARY(4) Length of watch information
|
|
4 4 CHAR(4) LIC Log major code
|
|
8 8 CHAR(4) LIC Log minor code
|
|
12 C CHAR(8) LIC Log identifier
|
|
20 14 CHAR(8) LIC Log timestamp
|
|
28 1C CHAR(8) TDE number
|
|
36 24 CHAR(16) Task name
|
|
52 34 CHAR(30) Server type
|
|
82 52 CHAR(2) Exception ID
|
|
84 54 CHAR(10) LIC job name
|
|
94 5E CHAR(10) LIC user name
|
|
104 68 CHAR(6) LIC job number
|
|
110 6E CHAR(4) Reserved
|
|
114 72 CHAR(8) Thread ID
|
|
122 7A CHAR(8) LIC module compile timestamp
|
|
130 82 CHAR(8) LIC module offset
|
|
138 8A CHAR(8) LIC module RU name
|
|
146 92 CHAR(48) LIC module name
|
|
194 DA CHAR(128) LIC module entry point name
|
|
322 142 CHAR(2) Reserved
|
|
324 144 BINARY(4) Offset to comparison data
|
|
328 148 BINARY(4) Length of comparison data
|
|
* * CHAR(*) LIC log comparison data
|
|
</pre>
|
|
</p>
|
|
<p>For more information on the watch exit program interface, refer to the System API Reference information in the iSeries Information Center at http://www.iseries.ibm.com/infocenter .
|
|
</p>
|
|
<p><b>Qualifier 1: Watch program</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the name of the watch exit program.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Qualifier 2: Library</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*LIBL</u></b></dt>
|
|
<dd>All libraries in the job's library list are searched until the first match is found.
|
|
</dd>
|
|
<dt><b><u>*CURLIB</u></b></dt>
|
|
<dd>The current library for the job is used to locate the program. If no library is specified as the current library for the job, the QGPL library is used.
|
|
</dd>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the name of the library where the user exit program is located.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="STRWCH.WCHMSG"></a>
|
|
<h3>Watch for message (WCHMSG)</h3>
|
|
<p>Specifies up to five message identifiers which are to be watched for. If a value other than *NONE is specified, you must specify where to watch for the message on the <b>Watched message queue (WCHMSGQ)</b> parameter. When the watched for message is added to the specified message queue or log, the watch exit program is called.
|
|
</p>
|
|
<p><b>Single values</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*NONE</u></b></dt>
|
|
<dd>No messages will be watched for.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 1: Message identifier</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the 7-character message identifier to be watched for.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 2: Comparison data</b>
|
|
</p>
|
|
<p>Specify comparison data to be used if a message matching the specified message ID 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 watch function just continues.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*NONE</u></b></dt>
|
|
<dd>No comparison data is specified. If a message matching the specified message ID is added to the specified message queue or log, the watched for condition is true.
|
|
</dd>
|
|
<dt><b><i>character-value</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 3: Compare against</b>
|
|
</p>
|
|
<p>Specify which part of the message the comparison data specified for element 2 is to be compared against.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*MSGDATA</u></b></dt>
|
|
<dd>The comparison data will be compared against the message replacement data.
|
|
</dd>
|
|
<dt><b>*FROMPGM</b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b>*TOPGM</b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="STRWCH.WCHMSGQ"></a>
|
|
<h3>Watched message queue (WCHMSGQ)</h3>
|
|
<p>Specifies where to watch for the message identifiers 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.
|
|
</p>
|
|
<p><b>Element 1: Message queue</b>
|
|
</p>
|
|
<p><b>Single values</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*SYSOPR</u></b></dt>
|
|
<dd>Watch messages added to the system operator message queue (QSYSOPR message queue in library QSYS).
|
|
</dd>
|
|
<dt><b>*JOBLOG</b></dt>
|
|
<dd>Watch messages added to the job logs of the jobs specified for the <b>Watched job (WCHJOB)</b> parameter.
|
|
</dd>
|
|
<dt><b>*HSTLOG</b></dt>
|
|
<dd>Watch messages added to the history log (QHST message queue in library QSYS).
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><b></b></dt>
|
|
<dd>
|
|
<p><b>Qualifier 1: Message queue</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the name of the message queue to watch.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><b></b></dt>
|
|
<dd>
|
|
<p><b>Qualifier 2: Library</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*LIBL</u></b></dt>
|
|
<dd>All libraries in the library list for the current thread are searched until the first match is found.
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the name of the library where the message queue is located.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="STRWCH.WCHJOB"></a>
|
|
<h3>Watched job (WCHJOB)</h3>
|
|
<p>Specifies the job whose job log is watched for the messages specified on the <b>Watch for message (WCHMSG)</b> parameter. The specified job will only be watched if *JOBLOG is specified on the <b>Watched message queue (WCHMSGQ)</b> parameter. Up to five job names may be specified.
|
|
</p>
|
|
<p><b>Single values</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*</u></b></dt>
|
|
<dd>Only the job log of the job that issued this watch command is watched.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 1: Job name</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b></b></dt>
|
|
<dd>
|
|
<p><b>Qualifier 1: Job name</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><i>generic-name</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b><i>*ALL</i></b></dt>
|
|
<dd>All jobs with the specified job user name are watched. *ALL for the job name is considered to be a generic job specification because it will watch all jobs that meet the job user name qualifier that you specified.
|
|
</dd>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the name of the job to be watched.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><b></b></dt>
|
|
<dd>
|
|
<p><b>Qualifier 2: User</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><i>generic-name</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b><i>*ALL</i></b></dt>
|
|
<dd>All jobs with the specified job name are watched. *ALL for the job user name is considered to be a generic job specification because it will watch all jobs that meet the job name qualifier that you specified.
|
|
</dd>
|
|
<dt><b><i>name</i></b></dt>
|
|
<dd>Specify the user name of the job to be watched.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><b></b></dt>
|
|
<dd>
|
|
<p><b>Qualifier 3: Number</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*ALL</u></b></dt>
|
|
<dd>All jobs with the specified job name and user name are watched. *ALL for the job number is considered to be a generic job specification because it will watch all jobs that meet the job name and job user name qualifiers that you specified.
|
|
</dd>
|
|
<dt><b><i>000001-999999</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="STRWCH.WCHLICLOG"></a>
|
|
<h3>Watch for LIC log entry (WCHLICLOG)</h3>
|
|
<p>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.
|
|
</p>
|
|
<p><b>Single values </b>
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*NONE</u></b></dt>
|
|
<dd>No LIC log entries will be watched for.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 1: Major code</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b>*ALL</b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b><i>character-value</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 2: Minor code</b>
|
|
</p>
|
|
<dl>
|
|
<dt><b>*ALL</b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b><i>character-value</i></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
</dl>
|
|
<p><b>Element 3: Comparison data</b>
|
|
</p>
|
|
<p>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.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*NONE</u></b></dt>
|
|
<dd>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.
|
|
</dd>
|
|
<dt><b><i>character-value</i></b></dt>
|
|
<dd>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 fields compared of a watched for log entry, the watch condition is considered to be true. This text is case sensitive. The LIC log fields which can 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.
|
|
<p>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.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
<div><h3><a name="STRWCH.COMMAND.EXAMPLES">Examples</a> </h3>
|
|
<p><b>Example 1: Start a Watch on Your Job</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
STRWCH SSNID(OWN_JOB) WCHPGM(MYLIB/MYPGM)
|
|
WCHMSG((CPF0001)) WCHMSGQ((*JOBLOG))
|
|
</pre>
|
|
</p>
|
|
<p>This command starts the watch session named "OWN_JOB" to start watching for CPF0001 message to occur on the job that called the STRWCH command. When CPF0001 message is sent to the current job log, MYPGM program in MYLIB library will be called to be notified of the event.
|
|
</p>
|
|
<p><b>Example 2: Start a Watch for a Message</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
STRWCH SSNID(*GEN) WCHPGM(MYLIB/EXTPGM)
|
|
WCHMSG((CPF1804))
|
|
WCHMSGQ((*SYSOPR) (*JOBLOG))
|
|
WCHJOB((*ALL/MYUSER/MYJOBNAME))
|
|
</pre>
|
|
</p>
|
|
<p>This command starts a watch session to call MYLIB/EXTPGM user exit program when CPF1804 message is found on the System Operator message queue or within the *ALL/MYUSER/MYJOBNAME job log. A unique watch session identifier will be generated. The session identifier will be returned in the message data of CPC3901 completion message sent after the watch session starts successfully.
|
|
</p>
|
|
<p><b>Example 3: Start a Watch for a Message Specifying Comparison Data</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
STRWCH SSNID(FRMPGM) WCHPGM(MYLIB/EXTPGM)
|
|
WCHMSG((CPC3922 QSCSWCH *FROMPGM))
|
|
WCHMSGQ((*HSTLOG))
|
|
</pre>
|
|
</p>
|
|
<p>This command starts a watch session to call MYLIB/EXTPGM user exit program when CPC3922 message is sent to message queue QHST in library QSYS by QSCSWCH program.
|
|
</p>
|
|
<p><b>Example 4: Start a Watch for a LIC Log Entry</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
STRWCH SSNID(LICLOGSSN) WCHPGM(*LIBL/EXTPGM)
|
|
WCHLICLOG(('99??' 9932 MYJOBNAME))
|
|
</pre>
|
|
</p>
|
|
<p>This command starts LICLOGSSN to watch for a Licensed Internal Code (LIC) log entry that has a major code starting with 99 and a minor code of 9932 generated on the system. Also, the LIC log information should contain the text "MYJOBNAME". The first match of EXTPGM program found in the library list will be called notifying that the event occurred.
|
|
</p>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
<div><h3><a name="STRWCH.ERROR.MESSAGES">Error messages</a> </h3>
|
|
<p><b><u>*ESCAPE Messages</u></b>
|
|
</p>
|
|
<dl>
|
|
<dt><b>CPF0006</b></dt>
|
|
<dd>Errors occurred in command.
|
|
</dd>
|
|
<dt><b>CPF2401</b></dt>
|
|
<dd>Not authorized to library &1.
|
|
</dd>
|
|
<dt><b>CPF2403</b></dt>
|
|
<dd>Message queue &1 in &2 not found.
|
|
</dd>
|
|
<dt><b>CPF2408</b></dt>
|
|
<dd>Not authorized to message queue &1.
|
|
</dd>
|
|
<dt><b>CPF39E3</b></dt>
|
|
<dd>Session ID &1 already exists.
|
|
</dd>
|
|
<dt><b>CPF39E5</b></dt>
|
|
<dd>No active jobs found, watch session not started.
|
|
</dd>
|
|
<dt><b>CPF39E6</b></dt>
|
|
<dd>The user does not have the required authority.
|
|
</dd>
|
|
<dt><b>CPF39E7</b></dt>
|
|
<dd>Invalid session identifier.
|
|
</dd>
|
|
<dt><b>CPF39E8</b></dt>
|
|
<dd>Not enough authority to watch operations.
|
|
</dd>
|
|
<dt><b>CPF39E9</b></dt>
|
|
<dd>*JOBCTL special authority required.
|
|
</dd>
|
|
<dt><b>CPF3958</b></dt>
|
|
<dd>Not authorized to use program &1 in library &2.
|
|
</dd>
|
|
<dt><b>CPF39D0</b></dt>
|
|
<dd>Watch for event function cannot start. Reason code &1.
|
|
</dd>
|
|
<dt><b>CPF39D1</b></dt>
|
|
<dd>Limit exceeded for jobs watching for events.
|
|
</dd>
|
|
<dt><b>CPF3C20</b></dt>
|
|
<dd>Error found by program &1.
|
|
</dd>
|
|
<dt><b>CPF9811</b></dt>
|
|
<dd>Program &1 in library &2 not found.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#STRWCH.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
</body>
|
|
</html>
|