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.
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.
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:
End Watch (ENDWCH) command or End Watch (QSCEWCH) API was issued.
One or more of the watch for event jobs ended abnormally or ended by user action
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).
, 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.