Job Performance Information

Last week I wrote about the basic performance information that had been added to the CPF1240/CPF1241 messages, and in that blog also mentioned the basic performance information in the CPF1164 message that is sent to the history log.

As reader Tim Hawkins commented:

If you really want granular performance information (without the overhead of the Performance Tools assuming you have it), use the Job Accounting journals, there are several tools available to convert them to DB files. Then query the data using your favorite tool.

Tim, not realizing it, was the “straight-man” for this week's blog; although I didn't state it, when I was writing last week's blog, I was planning to write next about job performance data, the options available, and when you might chose which option.

IBM i has very rich features regarding performance metrics; while the capabilities are very comprehensive, it can sometimes be confusing as to what feature you should use when. Of course, the answer to every question related to performance is “It depends!” I've not written about much of these capabilities since I speak on them frequently, but you can be sure they are on my list of future topics.

This week, I'll review the basic options for job performance data and provide brief guidance for when you might consider each option.

• CPF1164, CPF1240/CPF1241 messages as reviewed last week.
  Active Jobs, Server Jobs, System Status, etc...

The commonly used interfaces used such as work with active jobs provide basic job performance information in an interactive interface (either via the command line interface or the graphical user interface). The GUI also has the ability to look at server jobs as a subset of active jobs. These interfaces are useful for a quick view of performance across a small set of jobs.

There are also API interfaces to retrieve this information programmatically.

• IBM i Job Notification Exit Point
  The Job Notification exit point can be used to log notification messages to data queues when IBM i jobs are placed on a job queue, a job starts, or a job ends.
  With the job notification exit point, when a job ends, you will have the date and time the job entered the system, when the job started, and when the job ended. You can also get the processing time used; no other performance data is available.
  
  The job notification exit point would be useful if all you need is awareness of jobs starting and ending, and possibly the processing time used.

• IBM i Job Accounting
  The When to Use Job Accounting article in the Information Center has a nice summarization of when you'd use job accounting data as opposed to when you would use the data in the CPF1164/CPF1240/CPF1241 messages.
  
  Job accounting data includes all the data in the above-listed messages. Job Accounting data includes additional metrics, such as print and communications information (note the communications information is for SNA communications).
  
  You would use job accounting if print and communications information is important to you or the ability to assign accounting codes is required.
  
  Also, the performance data in the CPF1164 message pre-dates the job accounting information and job accounting would be the preferred way to gather this type of job data today. If IBM were to add additional, basic performance metrics, it would be added to the job accounting data and not to the messages. IBM i developers are aware there are customers still using the old method of getting the basic performance data from the messages in QHST so it will continue to be supported.

• The Job Accounting Journal entry documentation details the information that is collected.
  Collection Services Performance data
  
  Collection Services, which runs 24x7 by default starting with the 6.1 release, has comprehensive job performance data collected. This data is stored in the QAPMJOBMI and QAPMJOBOS database files. In addition to the job performance metrics, Collection Services also collects save/restore metrics for a job in the QAPMJOBSR file. Finally, wait information is also collected by Collection Services and provides the ability to determine Why you are Waiting.
  
  If you need low-overhead performance data collection with detailed performance data, Collection Services provides the best solution; when you run Collection Services, it will collect and save detailed job performance data before you know you need it! You can query the data from the files directly, or you can use the Performance Data Investigator to graphically Investigate Collection Services data.

• PM for Power Systems
  You probably are familiar with PM for Power Systems from the “old” name of PM/400. PM for Power Systems summarizes data from Collection Services and optionally sends that summarized data to IBM. By choosing to use PM for Power Systems, you can get summarized trend analysis information on your system's utilization and performance, plus job information (most frequent, processor time, I/O and print) on the top 10 low priority jobs. Remaining capacity is constantly calculated and the data are readily available to the IBM Workload Estimator for sizing future needs.

• Job Watcher Performance data
  The Job Watcher performance data collector was added to the operating system in the 6.1 release. It provides the ability to get detailed job performance data and collects much of the same job data as Collection Services does, but it also collects additional information, such as call stacks, SQL statements, objects being waited on, and more.
  
  Job Watcher is used for detailed job performance analysis and diagnostics. You can view Job Watcher data with the Performance Data Investigator or the iDoctor performance tool.
  
  

As you can see, there are a number of alternatives available. Which one you chose will depend upon the specific requirements you have for why you need job performance information.

Functional Usage Capabilities, Part 2

A reader comment from last week's blog asked the question: 

Where can I find detailed documentation that describes exactly what each of these FUNCTION IDs controls? Does one of the available function IDs allow me to control interactive SQL usage? I have some users (new programmers, support people, etc.) where I want to prohibit the DELETE, UPDATE, CREATE operations but allow a SELECT operation.

I'll answer the second part of the question first: No, function usage does not allow you to control interactive SQL use. You can control access to DB/SQL administration and monitoring facilities however; the DB/SQL function usage is new in the IBM i 7.1 release and Authority Options for SQL Analysis and Tuning describes the new function usage capabilities.

When I started to compose this article, I was thinking “This will be such an easy blog to write!” Was I wrong! I knew a lot of components had taken advantage of the function usage capability, but I didn't realize just how many. And of course, I also thought that the documentation on the various function IDs would be mostly a matter of pulling things together, but I was also wrong about that.

So where can you find some additional documentation?

Three places:

• If you use the Display Function Usage or Work with Function Usage commands, you can display information about each Function Usage ID. One piece of information is the Description, which provides a brief overview of what that Function Usage ID is for.
  
  However, the easier approach is to use the GUI. The Host Applications listed use the descriptive name which is much more meaningful than the QIBM... ID you find on the command-line interface. The screen capture below is an example of what you will see. Many of the functions are self-describing and you can pretty easily figure out what is controlled from the description.
  
  
  
  
  
• Search for the QIBM... string in the IBM i Information Center (I used 7.1). This search will return all the interfaces that check on the specified identifier and you will get a pretty good idea of what the function is for. However, it turns out that not all function IDs are documented in the Information Center, and those that are generally have information scattered.
  
  
• Internet search. Some of the functions have had articles written on them when they were first made available. An Internet search on the QIBM.... string may find some additional information beyond what is in the IBM i Information Center.
  
  

When I started to write this blog, my intent was to include the full set of documentation and chase down information on the IDs that are not documented in the Information Center. However, when the initial draft of this blog was at 16 pages (!). I realized this was a topic beyond what I can cover in the blog.

I will complete the documentation on the function IDs and it'll be published in some other way – either as an article here on the IBM Systems Magazine site, or perhaps something on the IBM i developerWorks site (or maybe both). I'll comment on this blog when that article is available.

Finally, there is an old Redbooks publication, Operations Navigator V5R1 Volume 1: Overview and More, that has a good chapter on Application Administration that is still applicable. Note that the Redbooks pub is based upon the Operations Navigator client, but the capabilities are the same, even in the browser (Director Navigator) added in 6.1.

 

Delete That Object

Did you know that in the IBM i 7.1 release, a new command was added to delete an object? I'm sure you can easily figure out what the name of the command is. Did you also know that in the 6.1 release, the API to delete an object was added?

The Delete Object (DLTOBJ) command (or the Delete Object API) is similar to the other object commands, for example Dump Object or Move Object, where you specify the name of the object along with the object type. Not all object types are supported by the generic Delete Object command or API, but many of them are. Some of the DLTxxx commands have additional parameters; if you use the generalized DLTOBJ interface to delete these objects, the system will use the default values that could have been specified on the more specific DLTxxx command (these default values are documented in the Delete Object API documentation). The Delete Object API also documents the object types that are supported by these interfaces.

There are a few advantages that you have when using the DLTOBJ command:

• You can delete multiple libraries (object type of *LIB) with one DLTOBJ command by specifying a generic name. Be careful!
• You can specify *ALL for the object name and have an easy way to delete all of the objects of a specific type from a library. Be careful!
• You can delete an object from a specific ASP or a group of ASPs by using the ASPDEV parameter.
  
  

And here's a little bit of trivia for you … the request for providing a generic delete command originated back in 1990; it may take IBM a little while, but good ideas are not forgotten, they sometimes just take some time to work their way to the top of the priority list.

 

Display Locks With Director Navigator

A few weeks ago I wrote about how you can Display File Usage Information to view information about what jobs are using a file within the Integrated File System. You can also view lock information from the GUI, and that too has existed since V5R1 and V5R2. For object locks, most everyone is aware of the Work with Object Locks (WRKOBJLCK) command. This blog will review how you can view object lock information from the GUI. You'll discover there are a few more capabilities through the GUI than there are via the command interface.

There is a lot of functionality built into the GUI for displaying object locks as well as database member and record locks. This blog is only going to review the object lock information.

First of all, start by reviewing the locks held by a job. This is similar to working with a job (WRKJOB), option 12, Work with locks.

Once you navigate to the job you are interested in, and take the pop-up box to go to Details then Locked Objects. 

 

You will then be shown a list of the object locks held by the job.

 

For any given object that is locked, you can then display either the Lock Holders or Properties.

 

Lock Holders will show you other jobs that are holding locks on that object; this is similar to what WRKOBJLCK will show you.

Properties provide additional information beyond what you can find on the command interface. Specifically, on the General tab, you will see additional information about the object lock that is held. A simple example is with the job's lock on the user profile object. On the green-screen interface, you will see the user profile object listed three times in the job's lock list. On the GUI, you will only see the user profile listed once, but the lock detail information will show you that the object has a total of three locks on it. Note that the information on the General tab can be included in the Locked Objects table view by customizing the Columns...

 

The Details tab contains information regarding the procedure, module, program, statements and instruction number where the lock was obtained. The information displayed here will depend upon the actual program that obtained the lock, but this information can be invaluable for debugging locking problems.

 

You can get additional locking information when you take the Include... option from the work management Locked Objects action drop-down. The Include... options allow you to display additional lock information that is not shown by default; the operating system has internal locking mechanisms – locks on internal system objects as well as space location locks – you can toggle these options on to display additional locking information which can be useful for diagnostic purposes.

 

You can also do these functions through programmatic interfaces. There are many APIs that provide lock information:

• List Object Locks (QWCLOBJL)
• Retrieve Job Locks (QWCRJBLK)
• Retrieve Lock Information (QWCRLCKI)
• Retrieve Lock Request Information (QWCRLRQI)
• Retrieve Lock Space Attributes (QTRXRLSA)
• Retrieve Lock Space Locks (QTRXRLSL)
• Retrieve Lock Space Records (QTRXRLRL)
• Retrieve Thread Attribute (QWTRTVTA)

 

 

 

 

IBM Improves the Handling of the Inactivity Timeout

The inactive job time-out (QINACTITV) system value defines the minimum amount of time that an interactive job can be inactive before an action is taken. The action that is taken is defined by the inactive job message queue (QINACTMSGQ) system value. A related system value, time interval before disconnected job ends (QDSCJOBITV), defines how long a job can be disconnected before the job is ended.

The handling of inactive job time out (QINACTITV) is being changed with a 7.1 PTF (the other system values are unaffected) to address two long-standing problems.

1. Accuracy. Prior to this change, a job can be inactive for up to twice the specified interval before an action is taken. For inactivity intervals measured in hours, this level of uncertainty is simply too high.
   
   
2. Performance. A large number of jobs can be ended at once when the subsystems check for inactivity. This can affect overall system performance at the time the jobs are being ended.

The change is available only for the 7.1 release with PTF SI46398. This is a delayed PTF, so it requires an IPL to put in on or to take it off.

First of us, let's review this change as it pertains to accuracy.

Prior to this change, the subsystem would wait for the QINACTITV number of minutes between the times it checked for inactive interactive jobs. Jobs can be inactive for nearly two intervals before the inactivity is detected; if a job runs just after the system checks for inactivity, at the next check it will not be inactive for the full interval, so the timeout will not occur until the following interval. For example, if you have QINACTITV set to 60 minutes, jobs may need to be inactive for nearly 120 minutes for the inactivity to be detected.

The PTF improves the timeliness in which inactivity is identified.

The QINACTITV function is still enforced by the subsystem code periodically checking for inactivity, but with the change, the subsystem tries to check more often to improve the accuracy. In most cases, the subsystem will now check for inactivity every 10 minutes and will keep track of how long a job has been inactive. If the QINACTITV system value is less than 15 minutes, the subsystem will continue to use the value specified by QINACTITV. (Checking for inactivity every 10 minutes only helps for the cases where QINACTITV is greater than or equal to 15 minutes).

A job can still be inactive for longer than the QINACTITV system value. For any given QINACTITV, you can work out an exact value for how long a job can be inactive before an action is taken. The job becomes inactive sometime during the 10 minutes between checks. So, in the simple case where the QINACTITV value is evenly divisible by 10, a job can be inactive for up to 10 minutes plus the QINACTITV value. But the QINACTITV value does not have to be evenly divisible by 10 and the subsystem cannot take action until the next time it checks for inactivity. For an QINACTITV value such as 101, a job can be inactive for at most the QINACTITV time plus 19 minutes.

Consider an example where QINACTITV is set to 90 minutes. With the old code, the subsystem would take the action defined by the QINACTMSGQ system value if a job was inactive anywhere from 90 minutes to 180 minutes. With the new code, the subsystem will take action if a job has been inactive anywhere from 90 minutes to 100 minutes.

Consider another example. In this case QINACTITV is set to 45 minutes. With the old code, the subsystem would take action if a job was inactive anywhere from 45 minutes to 90 minutes. With the new code, the subsystem will take action if a job has been inactive anywhere from 50 minutes to 60 minutes.

A job will be inactive for at least the QINACTITV value before action is taken. But sometimes you might be interested in "at most" rather than "at least". If you have a requirement that jobs must not be left inactive for longer than some specified value, you need to set the QINACTITV value to something less than the limit that you want to enforce. With the old code, the QINACTITV value had to be half of the limit that you wanted to enforce. With the new code, the QINACTITV value can be much closer to the limit that you want to enforce.

If system value QINACTMSGQ is set to the name of a message queue and the job identified by the CPI1126 message remains inactive and is not ended or disconnected, another CPI1126 is sent the next time the subsystem checks for inactivity. This behavior is unchanged, but the subsystem may be checking for inactivity much more often. This could affect the logic of whatever program is handling messages sent to that message queue. The program will have a lot less time before it gets another CPI1126 message for a given job.

It can still be useful to set the QINACTMSGQ (Inactive job message queue) system value to the name of a message queue so that you can control which jobs get ended or disconnected and how many jobs get processed at a time. Activity can be uneven and can be influenced by external factors such as lunchtime. A significant number of jobs can become inactive within the same 10-minute interval. This is less of a problem with a 10-minute interval than it is with an interval measured in hours. Also, due to other changes in the code, this is less of a problem when the interactive work is spread across multiple subsystems.

Now on to the performance improvements provided by this PTF.

Subsystems that are started at the same time will no longer check for inactivity at the same time. When the subsystems start or when the QINACTITV system value is changed, the subsystems now use a small but variable delay when setting up the checking for inactivity. This helps reduce the number of jobs that are disconnected or ended at a single time. With the old code, you could introduce delays between starting subsystems and these delays would translate more or less directly into delays between the times the different subsystems would check for inactivity. With the new code, every subsystem has to check every 10 minutes, but the system takes care of spreading out the work. Now, the only reason to have delays between starting subsystems would be to manage the amount of work done when starting the subsystems.

When a subsystem sets up its checking for inactivity, it has no idea how many other subsystems will need to do this same type of work. In addition to checking for inactive interactive jobs, subsystems also check the number of prestart jobs that are not being used. PTF SI46398 spreads out the work for ending of inactive interactive jobs and for ending of unused prestart jobs.

Because it is still the subsystem that checks for inactivity, much remains the same. But the system now reacts to inactivity sooner and spreads out the work better. This makes the enforcement of QINACTITV more predictable and reduces the impact on overall system performance.

 

I'd like to thank Dan Tarara for this blog; Dan is a member of the IBM i work management team. Thanks, Dan!

 

Lesser-Known Features of Work With System Activity

Hopefully most of you now know that in the 6.1 release, IBM moved the Work with System Activity (WRKSYSACT) command from the Performance Tools licensed program product into the base operating system. WRKSYSACT has been around for a long time, but it has a few features that you may not be aware of.

Work with System Activity is a great tool for getting a basic understanding of what is happening on your partition in terms of performance. WRKSYSACT will show you jobs, threads, and tasks that are using system resources – CPU utilization, synchronous and asynchronous I/O, storage allocation information, etc. WRKSYSACT is the only green-screen command interface in the operating system where you will find information about tasks. Other command interfaces – such as WRKACTJOB – only show information about jobs and threads.

It would take far too much space to write about all of the things you can see through WRKSYSACT; rather, there are a few features that I want to discuss in more detail.

 

WRKSYSACT in Batch Mode

First of all, did you know that you can run WRKSYSACT in a batch monitoring mode and write the performance data to a file? You enable the batch mode with the OUTPUT parameter; by default this is * and the information is presented on your display. But there are two additional options, *FILE and *BOTH, which will write the performance data to a database file (QAITMON in QPFRDATA by default). You can specify the sample intervals with the INTERVAL parameter (which also controls the auto-refresh intervals as well) and how many intervals are collected (NBRITV parameter). When you take the option to write the data to a file, a job named WRKSYSACT is submitted to QBATCH to collect the performance data.

The Print Activity Report (PRTACTRPT) command can then be used to print out a report from the sample data collected by WRKSYSACT. The PRTACTRPT command can generate a summary report as well as a detailed report and has options to allow you to specify a timeframe of interest, specific jobs you may want in the report, as well as what criteria the report should use in ordering.

 

Wait Information

Wait information will tell you what a particular job, thread or task is waiting on when it is waiting to do more work. I wrote about wait accounting in “i Can Tell You Why You're Waiting” some time ago. You can also see wait information using WRKSYSACT; you simply need to determine which job/thread/task you want to look at, and use option 6, Wait detail, for that job or task. Option 6 will bring up a display that will list the wait categories for that job/thread/task. Be aware that this is a high-level summary of the kinds of wait for that job or task. However, it make give you some clues about what job or task you need more detailed information for; you can then use the Performance Data Investigator with Collection Services or Job Watcher data to view detailed wait information.

 

Storage Allocated/Deallocated

WRKSYSACT will also show the storage allocated or deallocated by a job/thread/task by pressing the F11 key to get to View 4. I wrote about “Understanding Disk Space Usage” and in that blog reviewed WRKSYSACT and the storage allocated/deallocated information.

 

Scaled CPU

Scaled CPU time is a metric that can be used to determine if energy management features, such as power capping or power savings, are in effect on your IBM i partition. These energy management capabilities can be turned on through Active Energy Manager, which is a plug-in to IBM Systems Director. When you use these energy management features, the system's processor may run at lower or higher frequencies, which can affect your partition's performance. I wrote about this topic at length in the blog “i Can Understand Scaled CPU Time.”

On the WRKSYSACT display, the value “Average CPU rate” will be displayed if you are using energy management capabilities. This rate is an easy way to determine if your processor has been slowed down due to power capping or power savings.

One final note – one thing that has not changed with WRKSYSACT is the limit of one user at any given time. WRKSYSACT collects a lot of information from critical interfaces in the operating system and the limit of one user ensures limited contention on those critical interfaces.

 

 

 

 

Instrument Your Applications for IBM i Job Trace

Last week I wrote about the IBM i Job Trace capabilities.In that article, I briefly mentioned that you can instrument your own application so you can collect your own trace data as part of a job trace.

The secret to this support is something called the “QTRC APIs,” which were introduced with the 6.1 release. These APIs are documented under the “Problem Management” category of APIs in the IBM i Information Center. The QTRC API documentation section has much more information than just the programming interfaces; it discusses how you use these APIs and covers the related information you need to know to fully utilize these programming interfaces.

An important concept in how the QTRC APIs work is something called the “component.” The component is a parameter you specify on each of the QTRC APIs to identify the trace collection, and the component is the parameter on the STRTRC command that will turn trace on or off for your component. Below is the documentation taken from the Information Center on a QTRC Component:

Component

A 10-byte character string which names the application component. Each Trace Point has an associated component that is specified on the QTRC Trace APIs. The component name is also shown in the trace output for each Trace Record that is written. A component is defined to the QTRC Trace environment when specified on the Start Trace (STRTRC) CL command. Component names should only contain characters in the invariant character set. Avoid using lowercase a through z. Application component names should contain an abbreviated company name along with the application name. Component names starting with an asterisk (*) are reserved for the operating system. Component names starting with Q are reserved for IBM licensed programs.

There are three basic steps to collect diagnostic data from your application as part of a job trace:

1. Instrument your application to collect the desired diagnostic information.

This is the step that will require the most thought. What kind of data will you need for diagnostic purposes? What are the performance implications of collecting additional data? Do you have different types of data you would need for different kinds of problems?

You use the QTRC APIs to collect the data you need.

• Use the Check Trace Level API to determine the trace level that has been set for your component trace. This check will determine whether trace has been turned on for your component; if the required trace is not active, you can easily bypass the data collection logic in your application and avoid adding overhead to your application when trace has not been turned on.
• Based upon the trace level, you then write trace records; you can collect text data, hexadecimal data, and the call stack. The QTRC API documentation in the IBM i Information Center describes how to use these APIs.

2. Collect your trace data using the STRTRC command.

The magic to using the STRTRC command to collect your own trace data is on the TRCTYPE parameter. While IBM has defined special values to start trace collection for components within the operating system, the TRCTYPE keyword is not restricted to just these special values; you can specify your own component name on the TRCTYPE parameter.

The operating system components that you can trace with the TRCTYPE parameter are using the QTRC APIs as well – the QTRC APIs allow you to instrument your applications in the exact same way that IBM developers have instrumented the operating system.

3. Interpret the collected data by printing out the trace with the PRTTRC command.

There will be trace information included automatically by the system in addition to the component-specific data you add by using the APIs.

Traces can be large so you want to ensure that you clean up after yourself. Once you have completed diagnostics with the trace data, be sure to delete the trace data with the DLTTRC command. You should also delete any spooled trace files when you are done with them as well.

Adding diagnostic information to an application can be time-consuming, but the improved diagnostic capabilities provided by having trace data can ultimately save you a lot of time when problems arise. IBM i has significant tracing capabilities built into the operating system and you can be sure that every developer thinks about how they are going to debug problems that may arise. And with the QTRC APIs, you can do the same thing with your application.

 

 

 

Working With Your Spooled Output

In recent blog articles I wrote about Job Log Pending and the Job Log Output attribute that can be used to prevent the generation of spooled job logs. In addition, in a prior blog, I also wrote how to Detach Spooled Files from a job.

These all can be very helpful features, but one common concern I hear when I discuss these configuration options with clients is how to find their spooled files and job logs. Taking advantage of these features means you will likely need to change your approach to finding spooled files, but the capability to do so has been built into the operating system.

Everyone who has been using IBM i's character-based user interface (the “green screen”) is familiar with the Work with Spooled Files (WRKSPLF) command. This command has been part of the operating system “forever.” However, when a function is part of the base operating system, we don't always realize enhancements have been added because IBM always does it in a way that is upwardly compatible. That is, you can keep on using WRKSPLF just as you always have and not even realize that new features are available. And IBM does not change-flag enhancements to CL commands in the Information Center, which makes it all the harder to know what has changed. And the IBMers that talk about the latest and greatest additions to the operating system generally don't get too excited about incremental enhancements to that “old stuff”.... So while WRKSPLF command has been around “forever” and although the major enhancements were made to it in 5.4 (a “long” time ago), I've discovered that many people are still not aware of these changes.

As a quick exercise, let's look at the command parameters between V5R2 and 7.1.

Here is the Work with Spooled Files Command syntax diagram from the V5R2 Information Center (remember those?!)

>>-WRKSPLF------------------------------------------------------>

>--+-----------------------------------------------------------------+-->

   |          .-*CURRENT--.  .-*ALL--------.  .-*ALL------.  .-*ALL------.  .-*ALL-------.    |

   '-SELECT(--+-*ALL------+--+-*OUTQ-------+--+-*STD------+--+-user-data-+--+-ASP-number-+--)-'

              '-user-name-'  '-device-name-'  '-form-type-'

 

                               (1)

>--+-------------------------+---------------------------------->

   |          .-*INLENV-.    |

   '-DSPFMT(--+-*S36FMT-+--)-'

              '-*NORMAL-'

 

>--+---------------------------+--+------------------------+---><

   |          .-*PRV------.    |  |          .-*------.    |

   '-ASTLVL(--+-*USRPRF---+--)-'  '-OUTPUT(--+-*PRINT-+--)-'

              +-*BASIC----+

              '-*INTERMED-'

Below are the Work with Spooled Files Command parameters from the 7.1 Information Center, but I've changed the Notes column to identify changes to the WRKSPLF command. You'll observe that major changes were done in the 5.4 release.

 

 

Keyword	Description	Choices	Notes
SELECT	Select files for	Element list
	Element 1: User	Generic name, name, *CURRENT, *ALL	Generic name support added in 5.4
	Element 2: Print device	Name, *ALL, *OUTQ
	Element 3: Form type	Character value, *ALL, *STD
	Element 4: User data	Character value, *ALL	Generic support added in 5.4
	Element 5: ASP	1-32, *ALL, *ASPDEV	*ASPDEV added, extended to 32 in V5R3 for IASP support
	Element 6: Spooled file	Generic name, name, *ALL	Added in 5.4
JOB	Job name	Single values: *ALL Other values: Qualified job name	Added in 5.4
	Qualifier 1: Job name	Generic name, name
	Qualifier 2: User	Generic name, name, *ALL
	Qualifier 3: Number	000000-999999, *ALL
PERIOD	Time period	Element list	Added in 5.4
	Element 1: Start time and date	Element list
	Element 1: Beginning time	Time, *AVAIL
	Element 2: Beginning date	Date, *BEGIN
	Element 2: End time and date	Element list
	Element 1: Ending time	Time, *AVAIL
	Element 2: Ending date	Date, *END
ASPDEV	ASP device	Name, *, *SYSBAS, *CURASPGRP	Added in V5R3 for IASP Support
OUTPUT	Output	*, *PRINT
DSPFMT	Display format	*INLENV, *S36FMT, *NORMAL
ASTLVL	Assistance level	*PRV, *USRPRF, *BASIC, *INTERMED

How can these additional parameters help you?

You can use the WRKSPLF command to list spooled files by their file type – e.g., on the command prompt if you type QPJOB* for the Spooled File element on the SELECT parameter, you will display all the spooled files that begin with QPJOB* for your user profile (i.e., all your spooled job logs).

You can use the WRKSPLF command with the JOB parameter to work with the spooled files for a specific job or a generic job specification. For example, if you are detaching spooled files from their jobs, you can use the JOB parameter on the WRKSPLF command to locate the spooled files, even through the job is no longer in the system. Note the JOB parameter requires the USER element of the SELECT parameter to be *ALL.

You can use the WRKSPLF command with the PERIOD parameter to find spooled files from a specific timeframe. You can combine the JOB and PERIOD parameters to further refine the search criteria on which spooled files you are looking for.

And remember, too, that the Work with Job Logs (WRKJOBLOG) command was also added in the 5.4 release to make finding and working with spooled and pending job logs easier.

 

 

 

Job Log Output

Last week I wrote about Job Log Pending. With job log pending, you do not have to write job logs to spooled files.

At the end of that blog, I mentioned how you can use the Log Output (QLOGOUTPUT) system value or job attribute to take advantage of job log pending. This week, I'll explain the values available for “Log output” and give some general recommendations.

There are three options for the log output system value: 

• *JOBEND – the job log is written to a spooled file when the job is ended. This is the default value and is compatible with prior releases and how job logs were generated.
  
  
• *JOBLOGSVR – when the job ends, the job log remains in a pending status until the job log is written to a spooled file by the job log server.
  
  
• *PND – the job log is not written to a spooled file, but remains in a pending status.

While the shipped value for log output is *JOBEND, IBM recommends that you use the job log server. Using the job log server has a major advantage - the generation of the spooled job logs is handled in a more controlled manner. Remember the scenarios I described in last week's blog where you could potentially have hundreds or thousands of jobs writing job logs at the same time? That is a significant drain on system resources. By having the job log server generate the spooled job logs, the system controls the amount of work that is done at one point in time; if there are a lot of job logs to be written, the job logs will remain in a pending state until the job log server can write the job log to the spooled file.

But do you really need all those job logs written to spooled files? If you don't, you should think about using the pending attribute. Job logs that are in pending status will never have their job log written to a spooled file unless you take explicit action to do so. The system's automatic cleanup function will removing pending job logs in the same manner as it removes spooled job logs. If you need to display or print a pending job log, you can use one of the following methods: 

• Use the Display Job Log (DSPJOBLOG) command and direct the output as required.
• Use the WRKJOB or WRKUSRJOB command on ended jobs with pending job logs, similar to how you would work with an active job.
• Use the Work with Job Logs (WRKJOBLOG) command.
• Use the Change Job (CHGJOB) command to change the Log Output value from *PND to *JOBEND. This will write the job log to a spooled file and move the job to output queue status.

 

Job Log Pending

Job log pending has long been a possible state for a job log. When a job has a pending job log, the job has ended but the job log has not yet been written to an spooled file. In older releases of IBM i, this could occur when you powered down the system – the job logs would be saved in a pending state and the job logs would be written to spool files when the system was powered back up.

Every job on the system has a set of job structures, as I described in the IBM i Job Structures blog earlier this year. Job log messages are stored in an internal structure that is called the “job message queue.” The “traditional” behavior is for job log messages to be written a spooled file when the job ends.

However, think about certain scenarios: You end a subsystem that ends many jobs. You have a network failure that causes all Telnet sessions to be terminated. You have a runaway job in a loop that creates an unexpected number of jobs that do a small amount of work and then end. Or other situations where a large number of jobs are ended at about the same time.

In each of these scenarios, you can potentially have hundreds or even thousands of jobs that will all end at about the same time. If all of these jobs that are ending are also writing their job logs to spooled files, you can imagine the additional workload that would put on the system - writing job logs is a fairly expensive operation. Do you need to have all those job logs written? Do you have a need to save those job logs at all?

In the 5.4 release, IBM made job log pending a much more valuable and available option to use for job logs.

Rather than writing job logs to spooled files, job log pending allows you to keep the job logs in the internal form that is used when a job is active. No additional system resources are required to keep a job log in pending form (other than the job structure used to store information about the ended job).

Job log pending is controlled by the Job log output system value (QLOGOUTPUT) or the Job log output attribute on job descriptions.

There is much more to be written about job log pending, which I will do in subsequent blogs.