IBM Support

STRWCH - Watch Exit Programs Explained with CL Example

Troubleshooting


Problem

Introduced in V5R4, 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 starting in V6R1, PAL LOG entry. This document explains how it works and provides a CL example of a watch program that handles a message ID event.

Resolving The Problem

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.

This is the STRWCH command.

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.

This is the joblog with the MCH0802 error.

This is the text of the MCH0802 mesage.
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 here: http://publib.boulder.ibm.com/infocenter/iseries/v6r1m0/index.jsp?topic=/apis/xwchevnt.htm

Watch for Event Exit Program

Required Parameter Group

1
Watch option settingInputChar(10)
2
Session IDInputChar(10)
3
Error detectedOutputChar(10)
4
Event dataInputChar(*)

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:

*MSGIDA match on a message ID and any associated comparison data specified on watch for message parameter occurred.
*LICLOGA match on a LIC log and any associated comparison data specified on the watch for LIC Log entry parameter occurred.
*PALA match on a PAL and any associated comparison data specified on the watch for PAL entry parameter occurred.
*STRWCHThe watch program is being called before starting watching for any event.
*ENDWCHThe 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:

*ERRORError 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
TypeField
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.

Internal Use Only

I5/OS (5761SS1WM)

[{"Product":{"code":"SGYQGH","label":"IBM i"},"Business Unit":{"code":"BU009","label":"Systems - Server"},"Component":"General","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.3;7.2;7.1","Edition":""},{"Product":{"code":"SSC5L9","label":"IBM i 7.2"},"Business Unit":{"code":"BU009","label":"Systems - Server"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":""},{"Product":{"code":"SSC52E","label":"IBM i 7.1"},"Business Unit":{"code":"BU009","label":"Systems - Server"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":""},{"Product":{"code":"SSC3X7","label":"IBM i 6.1"},"Business Unit":{"code":"BU009","label":"Systems - Server"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":""},{"Product":{"code":"SSTS2D","label":"IBM i 7.3"},"Business Unit":{"code":"BU009","label":"Systems - Server"},"Component":" ","Platform":[{"code":"","label":null}],"Version":"","Edition":""}]

Historical Number

597115389

Document Information

Modified date:
17 June 2018

UID

nas8N1011571