Start Watch (QSCSWCH) API
Required Parameter Group:
| 1 | Session ID | Input | Char(10) |
| 2 | Started session ID | Output | Char(10) |
| 3 | Watch program | Input | Char(20) |
| 4 | Watch for message | Input | Char(*) |
| 5 | Watch for LIC log entry | Input | Char(*) |
| 6 | Error Code | I/O | Char(*) |
Optional Parameter Group 1:
| 7 | Watch session attributes | Input | Char(*) |
Optional Parameter Group 2:
| 8 | Watch for PAL entry | Input | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Start Watch (QSCSWCH) API starts the watch for event function, which notifies the user by calling a user specified program when the specified event (a message, a LIC log or a PAL) occurs. PAL stands for Product Activity Log which shows errors that have occurred (such as in disk and tape units, communications, and work stations).
Up to 10000 watch sessions can be active at a time. The watch session continues until ended with the End Watch (QSCEWCH) API or with the End Watch (ENDWCH) command.
Note: A watch session can be ended from the same job or a different job.
Authorities and Locks
- Authority to use the API
- To use this API, you must have service (*SERVICE) special authority or
must be authorized to the Service watch function of the IBM i through System i™ 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.
- Authority to watch program
- You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to
the watch program to be called, and execute (*EXECUTE) authority to the library
where the program is located.
- Authority to message queue
- You must have use (*USE) authority to the message queue specified in
watched message queue name field, and use (*USE) authority to the library where
the message queue is located.
- Authority to watched job
- When a message is being watched within a job, the issuer of the API 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 API 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 in the watched job user name field.
If you specify *ALL for the watched job name, or a generic user name, you must have all object (*ALLOBJ) special authority or must be authorized to the Watch Any Job function of the 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.
Required Parameter Group
- Session ID
- INPUT; CHAR(10)
The session identifier for this watch. This watch session identifier must be unique across all active watch sessions on the system. You cannot specify a session identifier that starts with "QSC". You can use this special value for this parameter:
*GEN The system will generate a unique session identifier for this watch that will be returned as output in Started session ID parameter.
- Started session ID
- OUTPUT; CHAR(10)
The identifier of the watch session just started.
- Watch program
- INPUT; CHAR(20)
The program to be called to notify that a specified watch event occurred. The watch program will be called after a match of a message, type, severity and any associated comparison data specified for the watch for message parameter, or a match of a Licensed Internal Code (LIC) log entry and any associated comparison data specified for the watch for LIC log entry parameter occurs, or a match of a Product Activity Log (PAL) entry and any associated comparison data specified for the watch for PAL entry parameter occurs. The watch program will also be called at the times specified in the call watch program options field in watch session attributes parameter.
The exit program will be called once for each message and LIC log entry and PAL entry specified on this API. 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.
The information must be in the following format:
- Watch program name
- CHAR(10)
The name of the user-written program to call.
- Watch program library
- CHAR(10)
The library where the user-written program is located. You can use one of these special values for this field:
*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 used to locate the program. If no library is specified as the current library for the job, the QGPL library is used.
- Watch for message
- INPUT; CHAR(*)
The messages which are to be watched for and where to watch for them.
Note: Moved and resent messages will not be watched. Only the original instance of the message can be watched.
Note: If CPF1124 (Job started) or CPF1164 (Job ended) is specified as a message id to watch, they will not trigger the exit program when they occur in job QSCWCHPS. CPF1124 and CPF1164 will be ignored in job QSCWCHPS, to eliminate a never-ending loop when watching for an event that occurs in a watch processing job.
The information must be in the following format:
- Number of messages being watched
- BINARY(4)
The total number of all of the messages to watch for within this session. Up to 100 message specifications might be watched at the same time by a single session.
- Message information
- Each message being watched contains a message id or immediate/impromptu message, message type, message severity, where to watch for the message (message queue or job log) and it may specify a message comparison data. Refer to Format for message information for the format of this field.
- Watch for LIC log entry
- INPUT; CHAR(*)
The licensed internal code (LIC) log entry identifiers which are to be watched. 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. The information must be in the following format:
- Number of LIC logs being watched
- BINARY(4)
The total number of all of the LIC logs to watch for. Up to five LIC logs can be specified.
- LIC log information
- Each LIC log entry contains a major and a minor code and it may specify a LIC log comparison data. Refer to Format for LIC log information for the format of this field.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group 1
- Watch session attributes
- INPUT; CHAR(10)
The properties of the watch session to run. The information must be in the following format. For a detailed description of each field, see Field Descriptions.
Offset Type Field Dec Hex 0 0 BINARY(4) Length of attributes information 4 4 BINARY(4) Run priority 8 8 BINARY(4) Offset to call watch program options 12 C BINARY(4) Number of call watch program options * * Array of CHAR(10) Call watch program options
Optional Parameter Group 2
- Watch for PAL entry
- INPUT; CHAR(*)
The Product Activity Log (PAL) entries which are to be watched. The watched for condition will be met if a PAL entry is added that matches the specified system reference code and any comparison data specified. The information must be in the following format:
- Number of PALs being watched
- BINARY(4)
The total number of all of the PALs to watch. Up to five PALs can be specified.
- PAL information
- Each PAL entry contains a system reference code and it may specify a comparison data. Refer to Format for PAL information for the format of this field.
Format for message information
The following table shows the format for the messages to be watched. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of message information |
| 4 | 4 | CHAR(7) | Message to watch |
| 11 | B | CHAR(1) | Reserved |
| 12 | C | CHAR(10) | Watched message queue name |
| 22 | 16 | CHAR(10) | Watched message queue library |
| 32 | 20 | CHAR(10) | Watched job name |
| 42 | 2A | CHAR(10) | Watched job user name |
| 52 | 34 | CHAR(6) | Watched job number |
| 58 | 3A | CHAR(6) | Reserved |
| 64 | 40 | BINARY(4) | Offset to message comparison data |
| 68 | 44 | BINARY(4) | Length of message comparison data |
| 72 | 48 | CHAR(10) | Compare against |
| 82 | 52 | CHAR(10) | Message type |
| 92 | 5C | CHAR(3) | Relational operator |
| 95 | 5F | CHAR(1) | Reserved |
| 96 | 60 | BINARY(4) | Message severity code |
| * | * | CHAR(*) | Message comparison data |
| * | * | CHAR(*) | Reserved |
Format for LIC log information
The following table shows the format for the LIC logs to be watched. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of LIC log information |
| 4 | 4 | CHAR(4) | LIC log major code |
| 8 | 8 | CHAR(4) | LIC log minor code |
| 12 | C | BINARY(4) | Offset to LIC log comparison data |
| 16 | 10 | BINARY(4) | Length of LIC log comparison data |
| 20 | 14 | CHAR(10) | LIC log compare against |
| * | * | CHAR(*) | LIC log comparison data |
| * | * | CHAR(*) | Reserved |
Format for PAL information
The following table shows the format for the PALs to be watched. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of PAL information |
| 4 | 4 | CHAR(8) | System reference code |
| 12 | C | BINARY(4) | Offset to PAL comparison data |
| 16 | 10 | BINARY(4) | Length of PAL comparison data |
| 20 | 14 | CHAR(10) | PAL compare against |
| * | * | CHAR(*) | PAL comparison data |
| * | * | CHAR(*) | Reserved |
Field Descriptions
Call watch program options. The times at which the watch program will be called. The program will always be called when the watched for event occurs. You can specify additional times for the program to be called:
| *STRWCH | The watch program will also be called before starting watching for any event. |
| *ENDWCH | The watch program will also be called when the watch session is ending.
Possible reasons might be:
Note: A watch session might end because an error was detected on the watch exit program. In this case, the watch program will not be called at *ENDWCH time. |
Compare against. The part of the message the data specified in message comparison data field is to be compared against. You must specify blanks if zero was specified for the length of message comparison data field. You can specify the following special values for this field:
| *MSGDTA | The message comparison data will be compared against the message replacement data. |
| *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. |
| *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. |
Length of attributes information. The length of the fixed portion of the structure containing the watch session attributes information. The maximum length is 16.
Length of LIC log comparison data. The length of the text specified in LIC log comparison data field. Valid values are 0 through 72.
Length of LIC log information. The length of the structure containing the information of the LIC log to watch.The minimum value allowed is 20 ('14'X). It is suggested to align the structure on a 4-byte boundary for better performance.
Length of message comparison data. The length of the text specified in message comparison data field. Valid values are 0 through 72.
Length of message information. The length of the structure containing the information of the message to watch.The minimum value allowed is 82 ('52'X). It is suggested to align the structure on a 4-byte boundary for better performance.
Length of PAL comparison data. The length of the text specified in PAL comparison data field. Valid values are 0 through 10.
Length of PAL information. The length of the structure containing the information of the PAL to watch.The minimum value allowed is 30 ('1E'X). It is suggested to align the structure on a 4-byte boundary for better performance.
LIC log compare against. The part of the LIC log the data specified in LIC log comparison data field is to be compared against. You must specify hexadecimal zeros (x'00') if zero was specified for the length of LIC log comparison data field. If not specified, the default value is *ALL. You can specify the following special values for this field:
| *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. |
LIC log comparison data. 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, 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.
LIC log major code. The LIC log major code to be watched. 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. You can specify the following special value for this field:
| *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. |
LIC log minor code. The LIC log minor code to be watched. 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. You can specify the following special value for this field:
| *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. |
Message comparison data. 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. This text is case sensitive.
Message severity code The severity code, ranging from 0 through 99, of the message to be watched. A message severity code of 0 will be used if this field is not specified.
Message to watch. The message to be watched. You can specify the following special values for this field:
| 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. |
| *IMMED | All immediate or impromptu messages will be watched. |
| *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. |
Message type. The message type assigned to the message to be watched. A message type of *ALL will be used if this field is not specified. You can specify one of the following special values for this field:
| *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. |
Number of call watch program options. The number of values specified in the call watch program options field array. If zero is specified the watch program will be called only when the specified event occurs.
Offset to LIC log comparison data. The offset to the field that holds the LIC log comparison data.
Offset to message comparison data. The offset to the field that holds the message comparison data.
Offset to PAL comparison data. The offset to the field that holds the PAL comparison data.
Offset to call watch program options. The offset to the array that defines when the watch program is to be called. If this value is 0 then the watch program will be called only when the specified event occurs.
PAL compare against. The part of the PAL the data specified in PAL comparison data field is to be compared against. You must specify blanks if zero was specified for the length of PAL comparison data field. You can specify the following special values for this field:
| *RSCNAME | The PAL comparison data will be compared against the resource name. |
| *RSCTYPE | The message comparison data will be compared against the resource type. |
| *RSCMODEL | The PAL comparison data will be compared against the resource model. |
PAL comparison data. 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. You can specify question mark (?) and asterisk (*) wildcard characters 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. 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'.
Relational operator. The relational operator against which the message severity code is compared. A *GE value for relational operator will be used if this field is not specified. You can specify one of the following special values for this field:
| *EQ | Equal. |
| *GT | Greater than. |
| *LT | Less than. |
| *GE | Greater than or equal. |
| *LE | Less than or equal. |
Reserved. A reserved field. This field must be set to hexadecimal or binary zero.
Run priority. The priority for the job where the watch session work will be run. The default job run priority of 25 will be used if the watch session attributes parameter is not specified. The possible values are:
| 0 | The default job run priority of 25 will be used. |
| -1 | The run priority of the current job will be used. |
| priority | The range of values is 1 (highest priority) to 99 (lowest priority). |
See the Work management topic collection for more information about the run priority.
System reference code. The system reference code to be watched. 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 name 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 name specifies all PALs with system reference codes that begin with the generic prefix.
You can specify the following special value for this field:
| *ALL | Any PAL system reference code will be considered to be a match. |
Watched job name. The name of the job to be watched. You must specify blanks if something different from *JOBLOG is specified for watched message queue name field. You can specify the following special values for this field:
| 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. |
| * | Only the job log of the job that issued this API is watched. |
| *ALL | 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. |
Watched job number. The job number (000001-999999) to further qualify the job name and user name. You must specify blanks if a generic job name (including *ALL) or a generic user name (including *ALL) qualifier is specified, or if something different from *JOBLOG is specified for watched message queue name field. You can specify the following special value for this field:
| *ALL | All jobs with the specified job name and user name are watched. |
Watched job user name. The user name of the job to be watched. You must specify blanks if '*' is specified for the watched job name field or something different from *JOBLOG is specified for watched message queue name field. You must specify a value if a generic job name (including *ALL) was specified. You can specify the following special value for this field:
| 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. *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. |
Watched message queue library. The name of the library where the message queue is located. This field is ignored if *SYSOPR, *JOBLOG or *HSTLOG was specified in the message queue name. You can specify the following special value for this field:
| *LIBL | All libraries in the job's library list are searched until the first match is found. |
Watched message queue name. The name of the message queue to watch. You can specify the following special values for this field:
| *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 field. |
| *HSTLOG | Watch messages added to the history log (QHST message queue in library QSYS). |
Error Messages
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPF13A3 | Value &1 for run priority not valid. |
| CPF241D | Severity criteria specified is not valid. |
| CPF24B3 | Message type &1 not valid. |
| CPF24B4 | Severe error while addressing parameter list. |
| CPF2401 | Not authorized to library &1. |
| CPF2403 | Message queue &1 in &2 not found. |
| CPF2408 | Not authorized to message queue &1. |
| CPF3CF1 | Error code parameter not valid. |
| CPF3C1D | Length specified in parameter &1 not valid. |
| CPF3C20 | Error found by program &1. |
| CPF3C3A | Value for parameter &2 for API &1 not valid. |
| CPF39D0 | Watch for event function cannot start. |
| CPF39D1 | Limit exceeded for jobs watching for trace events. |
| CPF39EA | Value specified for watched job user name filed is not valid. |
| CPF39EB | Watched job name, watched job user name or watched job number field not valid. |
| CPF39ED | Relational operator &1 not valid. |
| CPF39E3 | Session ID &1 already exists. |
| CPF39E4 | Specify Watch for message, LIC log entry or PAL entry. |
| CPF39E5 | No active jobs found, watch session not started. |
| CPF39E6 | The user does not have the required authority. |
| CPF39E7 | Invalid session identifier. |
| CPF39E8 | Not enough authority to watch operations. |
| CPF39E9 | *JOBCTL special authority required. |
| CPF3958 | Not authorized to use program &1 in library &2. |
| CPF9811 | Program &1 in library &2 not found. |
| CPF9872 | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R4
[ Back to top | Problem Management APIs | APIs by category ]