STRWCH - Watch Exit Programs Explained with CL Example

The STRWCH command allows for the specification of a watch program, which can be used by customers and service for notification and debugging of problems across the system. You can be notified when a particular message ID occurs in a single or all jobs, LIC LOG entry, or PAL LOG entry. This document explains how it works and provides a CL example of a watch program that handles a message ID event.



Once the program is called, it can execute any command, APIs, and so on or any function accessible to a *USER state/*USER domain program. The program can adopt owner authority if *ALLOBJ/*SECADM function is desired, by simply specifying USRPRF(*OWNER).

The watch program is passed four parameters to communicate the watch event (MSGID, LICLOG, PALLOG), session identifier, error detection (output), and event specific data, which, for length, is not documented here, but available using InfoCenter (see below).

Pay attention to parameter 3, which is for error detection. If the program does not set this parameter to blanks (10 blanks), a CPI3999 error, reason code 4, will be will be sent indicating that the watch session was terminated. This indicates that there was a problem with the user exit (watch) program. If the program does not specify all four parameters, you will see an MCH0802 error for OPM (old program model) compiled programs, indicating a mismatch in parameters.




ILE programs do not parameter check, so the program will still be called and executed. If the storage associated with the third parameter is blank, the watch will keep running; however, unpredictable results will occur.

When a watch event occurs, a QSCWCHPS prestart job or batch immediate job (BCI) will be used to call the watch program. If you suspect a problem either calling the watch program or with the watch program itself, you should try checking the joblog for the QSCWCHPS job.

WRKJOB QSCWCHPS will show all active and jobs in OUTQ status. If you are having trouble isolating the job, you can recommend the following to help debug:

o Issue the CHGJOB LOG(4 00 *SECLVL) LOGCLPGM(*YES) command to make sure that messages and CL commands are logged in the joblog.

o If the watch is a CL program, use the DMPCLPGM command to do a dump of the CL program including variables and error messages.

o DLYJOB - Issue the WRKACTJOB SBS(QUSRWRK) command and look for the QSCWCHPS job in DLYW.

o Issue a reply message to put the job in MSGW.

If you are using a single watch program for more than one watch, be mindful if you access shared storage in your watch program, that it could create contention. If your program is accessing objects like *DTAQ, *USRSPC, and so on, you should make sure locks get released so that jobs do not queue up.

A link to the complete watch event exit program documentation can be found in the IBM Knowledge Center here  

Watch for Event Exit Program

Required Parameter Group

1	Watch option setting	Input	Char(10)
2	Session ID	Input	Char(10)
3	Error detected	Output	Char(10)
4	Event data	Input	Char(*)

QSYSINC/H member name: ESCWCHT

The Watch for event functionality is started by the STRWCH command or the Start Watch (QSCSWCH) API, and has the capability to notify the user by calling a user exit program when the specified event occurs. An event can be a message being sent to a message queue, job log, LIC log, or a PAL entry. PAL stands for Product Activity Log which shows errors that have occurred (such as in disk and tape units, communications, and work stations). The user-written program will be called in the circumstances specified in the Watch option setting parameter.

Required Parameter Group

Watch option setting
INPUT; CHAR(10)
The reason indicating why the user-written program was called. The possible values are:
 

*MSGID	A match on a message ID and any associated comparison data specified on watch for message parameter occurred.
*LICLOG	A match on a LIC log and any associated comparison data specified on the watch for LIC Log entry parameter occurred.
*PAL	A match on a PAL and any associated comparison data specified on the watch for PAL entry parameter occurred.
*STRWCH	The watch program is being called before starting watching for any event.
*ENDWCH	The watch program is being called because the watch session is ending. Possible reasons might be: o End Watch (ENDWCH) command or End Watch (QSCEWCH) API was issued. o 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.

Session ID
INPUT; CHAR(10)
The name of the session that is calling the exit program.

Error detected
OUTPUT; CHAR(10)
Indicates if an error on the user-written program was found.
The possible values are:
 

*ERROR	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, LIC log entries, or PAL entries, all of them will no longer be watched.
<blanks>	No error detected by watch exit program.

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, LIC log entries, or PAL entries, all of them will no longer be watched.

Event data

INPUT; CHAR(*)
The format of the watch information depends on the Watch option setting causing the exit program to be called.
The format of the Event data is as follows if the Watch option setting is *MSGID:
 

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)	Job 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
452	1C4	CHAR(10)	Sending user profile
462	1CE	CHAR(10)	Target job name
472	1D8	CHAR(10)	Target job user name
482	1E2	CHAR(6)	Target job number
*	*	CHAR(*)	Sending procedure name
*	*	CHAR(*)	Receiving procedure name
*	*	CHAR(*)	Message comparison data
*	*	CHAR(*)	Message replacement data

Example CL program to process an *MSGID event

PGM        PARM(&WCHOPTSET &SESSIONID &ERRDETECT +
                          &EVENTDATA)

             /* PARAMETERS PASSED TO WATCH EXIT PROGRAM */

             DCL        VAR(&WCHOPTSET) TYPE(*CHAR) LEN(10)
             DCL        VAR(&SESSIONID) TYPE(*CHAR) LEN(10)
             DCL        VAR(&ERRDETECT) TYPE(*CHAR) LEN(10)
             DCL        VAR(&EVENTDATA) TYPE(*CHAR) LEN(1024)

             /* LOCAL VARIABLES */

             DCL        VAR(&JOBNAME) TYPE(*CHAR) LEN(10)
             DCL        VAR(&JOBUSER) TYPE(*CHAR) LEN(10)
             DCL        VAR(&JOBNUM) TYPE(*CHAR) LEN(6)
             DCL        VAR(&PROGRAM) TYPE(*CHAR) LEN(7)
             DCL          VAR(&RPLDTAOCH) TYPE(*CHAR) LEN(4)
               DCL          VAR(&RPLDTAOFF) TYPE(*INT) LEN(4)
               DCL          VAR(&RPLDTALCH) TYPE(*CHAR) LEN(4)
               DCL          VAR(&RPLDTALEN) TYPE(*INT) LEN(4)
               DCL          VAR(&MSGDATA) TYPE(*CHAR) LEN(64)
 
             CHGVAR     VAR(&ERRDETECT) VALUE('          ')

             /* OBTAIN JOB/PGM INFORMATION */

             CHGVAR     VAR(&PROGRAM) VALUE(%SST(&EVENTDATA 63 7))
             CHGVAR     VAR(&JOBNAME) VALUE(%SST(&EVENTDATA 33 10))
             CHGVAR     VAR(&JOBUSER) VALUE(%SST(&EVENTDATA 43 10))
             CHGVAR     VAR(&JOBNUM) VALUE(%SST(&EVENTDATA 53 6))
             CHGVAR     VAR(&RPLDTAOCH) VALUE(%SST(&EVENTDATA 441 4))                
             CHGVAR     VAR(&RPLDTALCH) VALUE(%SST(&EVENTDATA 445 4))                
             CHGVAR     VAR(&RPLDTAOFF) VALUE(%BIN(&RPLDTAOCH 1 4))    
             CHGVAR     VAR(&RPLDTALEN) VALUE(%BIN(&RPLDTALCH 1 4))    
             CHGVAR     VAR(&RPLDTAOFF) VALUE(&RPLDTAOFF + 1)          
             CHGVAR     VAR(&MSGDATA) VALUE(%SST(&EVENTDATA &RPLDTAOFF &RPLDTALEN))                  

             /* DSPJOB and JOBLOG FOR OFFENDING JOB */

             DSPJOB     JOB(&JOBNUM/&JOBUSER/&JOBNAME) +
                        OUTPUT(*PRINT) OPTION(*ALL)
             MONMSG     MSGID(CPF0000)
             DSPJOBLOG  JOB(&JOBNUM/&JOBUSER/&JOBNAME) +
                        OUTPUT(*PRINT)
             MONMSG     MSGID(CPF0000)

             CHGVAR     VAR(&ERRDETECT) VALUE('          ')


             ENDPGM

Note: If you re-create/recompile the watch program while the watch is still active, the replaced version of the watch will continue to be used. If you update the program, you should end the watch and restart to pick up your changes.