Each job has an associated job log that can contain the following for the job:
After the job ends, the job log can be written to either the output file QPJOBLOG or a database file. From the output file QPJOBLOG, the job log can be printed; from a database file, job log information can be queried using a database feature. You can also specify to not write job logs for jobs that have run successfully--a discussion about preventing job logs is presented later in this chapter.
IBM provides online information about how to write a job log to a database file that requires the use of the QMHCTLJL API. Refer to the CL section of the Programming category of the iSeries Information Center. When directing the job log to the database file, the system can generate one or two files. The primary file contains the essential information of a message such as message ID, message severity, message type, and message data. The secondary file contains the print images of the message text. Parameters on the QMHCTLJL API control the optional production of the secondary file. You can use database and query features on the system to externally describe and process both files. See Appendix B, Job Log Output Files for information on the formats of the primary and secondary files.
You can control what information the system writes in the job log. To do this, you specify the LOG parameter on the Create Job Description (CRTJOBD) command. You can change these levels by using the Change Job (CHGJOB) command or the Change Job Description (CHGJOBD) command. Three values make up the LOG parameter: Message level, message severity, and message text level. For more information on these commands, see the CL section of the Programming category of the iSeries Information Center.
The first value, message level, has the following levels:
The second value, message severity, specifies the severity level in conjunction with the log level that causes error messages to be logged in the job log. Values 0 through 99 are allowed.
The third value in the LOG parameter, message text level, specifies the level of message text that is written in the job log. The values are:
Before each new request is received by a request processing program, message filtering occurs. Message filtering is the process of removing messages from the job log based on the message logging level set for the job.
Filtering does not occur after every CL command is called within a program. Therefore, if a CL program is run interactively or submitted to batch, the filtering runs once after the program ends because the program is not a request processor.
The following example shows how the logging level affects the information that is stored in the job message queue and, therefore, written to the job log, if one is requested. The example also shows that when the command is run interactively, filtering occurs after each command.
+--------------------------------------------------------------------------------+ | Command Entry SYSTEM1 | | Request level: 1 | |Previous commands and messages: | | > CHGJOB LOG(2 50 *MSG) | | | +--------------------------------------------------------------------------------+
PGMB sends two informational messages with severity codes of 40 and 50 to its own call message queue. These are detailed messages. PGMB also sends one informational message with a severity code of 10 to *PRV.
Note that the CHGJOB command no longer appears on the display.
According to logging level 2, only requests for which a message has been
issued with a severity equal to or greater than that specified are saved for
the job log, and no messages were issued for this request. If such a
message had been issued, any detailed messages that had been issued would be
saved for the job log and could be displayed by pressing F10.
+--------------------------------------------------------------------------------+
| Command Entry SYSTEM1 |
| Request level: 1 |
|Previous commands and messages: |
| > CALL PGMA |
| Message sev 20 - PGMA |
| Message sev 50 - PGMA |
| Message sev 60 - PGMA |
| > CALL PGMB |
| Message sev 10 - PGMB |
| |
| |
| |
| |
| |
| |
| Bottom |
|Type command, press Enter. |
|===> _________________________________________________________________________ |
|______________________________________________________________________________ |
|______________________________________________________________________________ |
|_____________________________________________________________________________ |
| F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages |
| F11=Display full F12=Cancel F13=Information Assistant F24=More keys |
| |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+ | Command Entry SYSTEM1 | | Request level: 1 | |All previous commands and messages: | | > CALL PGMA | | Detailed message sev 20 - PGMA | | Detailed message sev 50 - PGMA | | Detailed message sev 60 - PGMA | | Message sev 20 - PGMA | | Message sev 50 - PGMA | | Message sev 60 - PGMA | | > CALL PGMB | | Detailed message sev 40 - PGMB | | Detailed message sev 50 - PGMB | | Message sev 10 - PGMB | | | | Bottom | |Type command, press Enter. | |===> _________________________________________________________________________ | |______________________________________________________________________________ | |______________________________________________________________________________ | |_____________________________________________________________________________ | | F3=Exit F4=Prompt F9=Retrieve F10=Exclude detailed messages | | F11=Display full F12=Cancel F13=Information Assistant F24=More Keys | | | +--------------------------------------------------------------------------------+
On the following display, the CHGJOB command specifies a logging level of 3, a message severity of 40, and that both the first- and second-level text of a message are to be written to the job log. When another command is entered, the CHGJOB command remains on the display because logging level 3 logs all requests.
PGMC sends two messages with severity codes of 30 and 40 to the call message queue of the program called before the specified call (*PRV).
PGMD sends a message with a severity of 10 to *PRV.
+--------------------------------------------------------------------------------+
| Command Entry SYSTEM1 |
| Request level: 1 |
|Previous commands and messages: |
| > CALL PGMA |
| Message sev 20 - PGMA |
| Message sev 50 - PGMA |
| Message sev 60 - PGMA |
| > CHGJOB LOG(3 40 *SECLVL) |
| > CALL PGMC |
| Message sev 30 - PGMC |
| Message sev 40 - PGMC |
| > CALL PGMD |
| Message sev 10 - PGMD |
| |
| |
| Bottom |
|Type command, press Enter. |
|===> _________________________________________________________________________ |
|______________________________________________________________________________ |
|______________________________________________________________________________ |
|_____________________________________________________________________________ |
| F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages |
| F11=Display full F12=Cancel F13=Information Assistant F24=More Keys |
| |
+--------------------------------------------------------------------------------+
The command SIGNOFF *LIST is entered to print the job
log.
+--------------------------------------------------------------------------------+
| Command Entry SYSTEM1 |
| Request level: 1 |
|Previous commands and messages: |
| > CHGJOB LOG(3 40 *SECLVL) |
| > CALL PGMC |
| Message sev 30 - PGMC |
| Message sev 40 - PGMC |
| > CALL PGMD |
| > CALL PGME |
| |
| |
| |
| |
| |
| |
| Bottom |
|Type command, press Enter. |
|===> SIGNOFF *LIST____________________________________________________________ |
|______________________________________________________________________________ |
|______________________________________________________________________________ |
|_____________________________________________________________________________ |
| F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages |
| F11=Display full F12=Cancel F13=Information assistant F24=More Keys |
| |
+--------------------------------------------------------------------------------+
The job log, which follows, contains all the requests and all the messages that have remained on the Command Entry display. In addition, the job log contains the message help associated with each message, as specified by the CHGJOB command. Notice that the job log contains the message help of any message issued during the job, not just for the messages issued since the second CHGJOB command was entered.
5722SS1 V5R2M0 020719 Job Log SYSAS727 06/25/02 07:58:53 Page 1 Job name . . . . . . . . . . : QPADEV0007 User . . . . . . : JOHNDOE Number . . . . . . . . . . . : 004201 Job description . . . . . . : QDFTJOBD Library . . . . . : QGPL MSGID TYPE SEV DATE TIME FROM PGM LIBRARY INST TO PGM LIBRARY INST CPF1124 Information 00 06/25/02 07:57:16.326128 QWTPIIPP QSYS 04FC *EXT 0000 Message . . . . : Job 004201/JOHNDOE/QPADEV0007 started on 06/25/02 at 07:57:16 in subsystem QINTER in QSYS. Job entered system on 06/25/02 at 07:57:16. *NONE Request 06/25/02 07:57:50.173112 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -call pgma CPF1001 Information 20 06/25/02 07:57:50.189536 PGMA JOHNDOE 000C PGMA JOHNDOE 000C Message . . . . : Detailed message sev 20 - PGMA CPF1001 second level text - PGMA CPF1002 Information 50 06/25/02 07:57:50.201712 PGMA JOHNDOE 0010 PGMA JOHNDOE 0010 Message . . . . : Detailed message sev 50 - PGMA CPF1002 second level text - PGMA CPF1003 Information 60 06/25/02 07:57:50.215968 PGMA JOHNDOE 0014 PGMA JOHNDOE 0014 Message . . . . : Detailed message sev 60 - PGMA CPF1003 second level text - PGMA CPF1004 Information 20 06/25/02 07:57:50.216728 PGMA JOHNDOE 0018 QCMD QSYS 00DE Message . . . . : Message sev 20 - PGMA CPF1004 second level text - PGMA CPF1005 Information 50 06/25/02 07:57:50.345512 PGMA JOHNDOE 001C QCMD QSYS 00DE Message . . . . : Message sev 50 - PGMA CPF1005 second level text - PGMA CPF1006 Information 60 06/25/02 07:57:50.474296 PGMA JOHNDOE 0020 QCMD QSYS 00DE Message . . . . : Message sev 60 - PGMA CPF1006 second level text - PGMA *NONE Request 06/25/02 07:58:31.181888 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -chgjob log(3 40 *seclvl) *NONE Request 06/25/02 07:58:34.201792 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -call pgmc CPF100F Information 30 06/25/02 07:58:34.330576 PGMC JOHNDOE 000C QCMD QSYS 00DE Message . . . . : Message sev 30 - PGMC CPF100F second level text - PGMC CPF1010 Information 40 06/25/02 07:58:34.459360 PGMC JOHNDOE 0010 QCMD QSYS 00DE Message . . . . : Message sev 40 - PGMC CPF1010 second level text - PGMC *NONE Request 06/25/02 07:58:38.128784 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -call pgmd *NONE Request 06/25/02 07:58:45.386352 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -call pgme *NONE Request 06/25/02 07:58:52.643920 QMHGSD QSYS 0322 QCMD QSYS 00B6 Message . . . . : -signoff *list CPF1164 Completion 00 06/25/02 07:58:52.772704 QWTMCEOJ QSYS 01EE *EXT 0000 Message . . . . : Job 004201/JOHNDOE/QPADEV0007 ended on 06/25/02 at 07:58:52; 3 seconds used; end code 0 . Cause . . . . . : Job 004201/JOHNDOE/QPADEV0007 completed on 06/25/02 at 07:58:52 after it used 3 seconds processing unit time. The job had ending code 0. The job ended after 1 routing steps with a secondary ending code of 0. The job ending codes and their meanings are as follows: 0 - The job completed normally. 10 - The job completed normally during controlled ending or controlled subsystem ending. 20 - The job exceeded end severity (ENDSEV job attribute). 30 - The job ended abnormally. 40 - The job ended before becoming active. 50 - The job ended while the job was active. 60 - The subsystem ended abnormally while the job was active. 70 - The system ended abnormally while the job was active. 80 - The job ended (ENDJOBABN command). 90 - The job was forced to end after the time limit ended (ENDJOBABN command). Recovery . . . : For more information, see the Work Management, SC41-8078.
The headings at the top of each page of the printed job log identify the job to which the job log applies and the characteristics of each entry:
When the sender or receiver is an ILE procedure, the message entry contains the full name of the procedure (procedure name, module name, and ILE program name). When the sender or receiver is an original program model (OPM) program, only the OPM program name is shown.
If the sender or receiver is an OPM program, the corresponding instruction number represents an instruction number. There is only one such number. If the sender or receiver is an ILE procedure, the instruction number represents a high level language statement number rather than an MI instruction number. If the ILE procedure has been optimized (maximum efficiency), there may be up to three numbers. It is not always possible to determine a single statement number for an optimized procedure. If there is more than one number given, each number represents a potential point where the procedure was when the message was sent. It is also possible that no number can be determined. If this the case, *N appears in the message rather than a number.
The logging levels affect a batch job log in the same way as shown in the preceding example. If the job uses APPC, the heading contains a line showing the unit of work identifier for APPC.
If the job log is directed to a database file through use of the QMHCTLJL API, additional message filtering can be specified. The message filtering specified through this API is applied when the job ends and the records for the messages are being written to the file. Up until this time, the messages which are now filtered have appeared. Thus they can be seen while the job is running. When the job log is written, the messages which are filtered will have no records written to the file for them. Thus, even though they appear while the job is running they will not appear in the final file that is produced.
The way to display a job log depends on the status of the job.
DSPSPLF FILE(QPJOBLOG) JOB(001293/FRED/WS3)
to display the job logs for job number 001293 associated with user FRED at display station WS3.
DSPJOBLOG JOB(nnnnnn/JSMITH/WS1)
where nnnnnn is the job number.
To display the job log of your own interactive job, do one of the following:
DSPJOBLOG
When you use the Display Job Log (DSPJOBLOG) command, you see the Job Log display. This display shows program names with special symbols, as follows:
On the Job Log display, you can do the following:
You may use the DSPJOBLOG command to direct the job to a database file instead of having it printed or displayed. There are two options available. In the first option, you may specify a file and member name on the command. In this option, the primary job log information is written to the database file specified on the command. In the second option you may use the command in conjunction with the information provided on the QMHCTLJL API which was run previously. In this option, the job log is written to the file(s) specified on the API call. With this option, both primary and secondary files can be produced and message filtering can be performed as the messages are written to the file. With both these options, when the DSPJOBLOG command completes, the output will not be displayed nor will there be a spooled file available for printing.
To prevent a job log from being produced at the completion of a batch job, you can specify *NOLIST for the message text-level value of the LOG parameter on the Batch Job (BCHJOB), Submit Job (SBMJOB), Change Job (CHGJOB), Create Job Description (CRTJOBD), or Change Job Description (CHGJOBD) command. If you specify *NOLIST for the message level value of the LOG parameter, the job log is not produced at the end of a job unless the job end code is 20 or greater. If the job end is 20 or greater, the job log is produced.
For an interactive job, the value specified for the LOG parameter on the SIGNOFF command takes precedence over the LOG parameter value specified for the job.
The following suggestions apply to using job logs:
CHGPRTF FILE(QSYS/QPJOBLOG) DEV (USRPRT) or CHGPRTF FILE(QSYS/QPJOBLOG) OUTQ(USROUTQ)
CHGJOB OUTQ(*JOB)
If you change the default OUTQ at the beginning of the job, all spooled files are affected. If you change it just before job completion, only the job log is affected. You cannot use the Override with Printer File (OVRPRTF) command to affect the job log.
CHGPRTF FILE(QSYS/QPJOBLOG) HOLD(*YES)
The IBM-supplied job descriptions QCTL, QINTER, and QPGMR all have a log level of LOG(4 0 *NOLIST); therefore, all messages and both first- and second-level text for the messages are written to the job log. However, the job logs are not printed unless you specify *LIST on the SIGNOFF command. To change the log level for interactive jobs, you can use the CHGJOB or CHGJOBD command.
If a display station user uses an IBM-supplied menu or the command entry display, all error messages are displayed. If the display station user uses a user-written initial program, any unmonitored message causes the initial program to end and a job log to be produced. However, if the initial program monitors for messages, it receives control when a message is received. In this case, it may be important to ensure that the job log is produced so you can determine the specific error that occurred. For example, assume that the initial program displays a menu that includes a sign-off option, which defaults to *NOLIST. The initial program monitors for all exceptions and includes a Change Variable (CHGVAR) command that changes the sign-off option to *LIST if an exception occurs:
PGM DCLF MENU DCL &SIGNOFFOPT TYPE(*CHAR) LEN(7) VALUE(*NOLIST) . . . MONMSG MSG(CPF0000) EXEC(GOTO ERROR) PROMPT: SNDRCVF RCDFMT(PROMPT) CHGVAR &IN41 '0' . . . IF (&OPTION *EQ '90') SIGNOFF LOG(&SIGNOFFOPT) . . . GOTO PROMPT ERROR: CHGVAR &SIGNOFFOPT '*LIST' CHGVAR &IN41 '1' GOTO PROMPT ENDPGM
If an exception occurs in the previous example, the CHGVAR command changes the option on the SIGNOFF command to *LIST and sets on an indicator. This indicator could be used to condition a constant that displays a message informing the display station user that an unexpected event has occurred and telling him what to do.
If the interactive job is running a CL program or procedure, the CL commands are logged only if the log level is 3 or 4 and one of the following is true:
You can set and change the LOGCLPGM job attribute by using the LOGCLPGM parameter on the SBMJOB, CRTJOBD, CRTJOBD, and CHGJOBD commands.
For your batch applications, you may want to change the amount of information logged. The log level (LOG(4 0 *NOLIST)) specified in the job description for the IBM-supplied subsystem QBATCH supplies a complete log if the job abnormally ends. If the job completes normally, no job log is produced.
If you want to print the job log in all cases, use the Change Job Description (CHGJOBD) command to change the job description, or specify a different LOG value on the BCHJOB or SBMJOB command. See Job Log for a description of logging levels.
If a batch job is running a CL program or procedure, the CL commands are always logged if you specify LOG(*YES) when you create modules or programs using the following commands:
CL commands are also logged if you specify LOGCLPGM(*YES) when you use the CHGJOB command and the SBMJOB command.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.