CL Programming

Job Log

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:

Level
Description

0
No data is logged.

1
The only information to be logged is all messages sent to the job's external message queue with a severity greater than or equal to the message severity specified. Messages of this type indicate when the job started, when it ended, and its status at completion.

2
The following information is logged:

3
The following information is logged:

4
The following information is logged:

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:

*SAME
The current value for the message text level does not change.

*MSG
Only message text is written to the job log (message help is not included).

*SECLVL
The message and the message help (cause and recovery) are written to the job log.

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.

Note:
Since *NOLIST specifies that no job log is spooled for jobs that end normally, it is a waste of system resource in batch jobs to remove the messages from this log by specifying log level 0.

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.

Note:
Both high-level and detailed message logging levels are included in the examples. High-level messages are identified as Message; detailed messages are identified as Detailed Message.
  1. The CHGJOB command specifies a logging level of 2 and a message severity of 50, and that only messages are to be written to the job log (*MSG).
    +--------------------------------------------------------------------------------+
    |                               Command Entry                         SYSTEM1    |
    |                                                          Request level:   1    |
    |Previous commands and messages:                                                 |
    |     > CHGJOB LOG(2 50 *MSG)                                                    |
    |                                                                                |
    +--------------------------------------------------------------------------------+
  2. PGMA sends three informational messages with severity codes of 20, 50, and 60 to its own call message queue and to the call message queue of the program called before the specified call (*PRV). The messages that PGMA sends to its own call message queue are called detailed messages. Detailed messages are those messages that are sent to the call message queue of the lower-level program call.

    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  |
    |                                                                                |
    +--------------------------------------------------------------------------------+
  3. When F10=Include detailed messages is pressed from the Command Entry display, all the messages associated with the request are displayed. Press F10 again to exclude detailed messages.
    +--------------------------------------------------------------------------------+
    |                              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 |
    |                                                                                |
    +--------------------------------------------------------------------------------+
  4. When another command is entered (in this example, CHGJOB), the CALL PGMB command and all messages (including detailed messages) are removed. They are removed because the severity code for the high-level message associated with this request was not equal to or greater than the severity code specified in the CHGJOB command. The CALL PGMA command and its associated messages remain because at least one of the high-level messages issued for that request has a severity code equal to or greater than that specified.

    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 |
    |                                                                                |
    +--------------------------------------------------------------------------------+
  5. When another command is entered after the CALL PGMD command was entered, the CALL PGMD command remains on the display, but its associated message is deleted. The message is deleted because its severity code is not equal to or greater than the severity code specified on the LOG parameter of the CHGJOB command.

    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:

Sending or Receiving Program or Procedure

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.

Additional Message Filtering

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.

Displaying the Job Log

The way to display a job log depends on the status of the job.

To display the job log of your own interactive job, do one of the following:

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:

>>
The running command or the next command to be run. For example, if a program was called, the call to the program is shown.

>
The command has completed processing.

. .
The command has not yet been processed.

?
Reply message. This symbol marks both those messages needing a reply and those that have been answered.

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.

Preventing the Production of Job Logs

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.

Job Log Considerations

The following suggestions apply to using job logs:

Considerations for Interactive Job Logs

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:

Considerations for Batch Job Logs

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.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]