Work with Collector (QPMWKCOL) API

The Work with Collector (QPMWKCOL) API starts, ends, or changes the collection of performance data for a particular resource on your system. The performance collector used by the API has the following attributes:

• It collects data for user-specified resource types that can include job, pool, disk, input/output processor (IOP), and communications.
  
  
• It collects data at time intervals ranging from 15 seconds to four minutes.
  
  
• It deposits the collected data into user spaces.
  
  
• Multiple users can collect data at the same time.
  
  
• The same resource type data can be collected by different users with the same or different interval lengths.
  
  
• Different resources can be collected at different interval times.
  
  
• It will collect data until all collections have been explicitly ended or all of the user's jobs have ended.
  
  
• It does not calculate deltas on the data collected. For more information on deltas, see the List Performance Data (QPMLPFRD) API.
  
  
• It will report job data for a job or task that is active when the data is collected. A job or task that terminates during an interval will no longer be reported.
  
  
• Its intent is to provide performance data useful for real-time monitoring of system performance. Thus, it will not support all of the counters that collection services supports. It is not intended to be used in place of collection services for detailed performance analysis, capacity planning, and other such functions.

When the first user of the collector issues a call to the QPMWKCOL API, two jobs (QPMASERV and QPMACLCT) are submitted to batch. QPMASERV acts as a server, communicating between the APIs (QPMWKCOL and QPMLPFRD) and the QPMACLCT job, which does the actual data collection. These jobs run at priority 0 in subsystem QSYSWRK. No matter how many users are collecting data, there will only be one instance of each job running. The programs will continue to run until all users have ended all of their collections. They will also end if none of the users' jobs are still active.

To start a data collection for a resource, call the QPMWKCOL API using the following:

• The value *START for the type of action to perform parameter
  
  
• The type of resource data to collect (job, pool, disk, input/output processor (IOP), or communications)
  
  
• The length of time between collections (15, 30, 60, 120, or 240 seconds)
  
  
• The name and library of the user space the data should be copied into. The user space must be created in the system ASP or in a basic ASP and not in an independent ASP. This ensures that the server job QPMASERV, which processes the API request, can access the user space.
  
  
• The error code parameter

A separate request must be made for each resource desired. When the request is valid, the sequence number of the first collection will be passed back to the user. The sequence number is increased by the user-specified interval time and can be used to see if an interval collection was missed. For example, if 15 is the first sequence number received back from the QPMWKCOL API but 30 is the sequence number received back from the List Performance Data (QPMLPFRD) API, you missed the collection of data with a sequence number of 15.

By using *CHANGE for the type of action to perform parameter, the interval time or the user space for a resource can be changed.

To end a collection, use *END for the type of action to perform parameter. Because a collection will continue to be active until it is ended, it is important that any collections that are no longer needed be ended. If an *END request is from the last user of a resource, data collection of the resource stops. If not, the resource will still be collected, but this user will no longer have access to data until a *START request is issued again. After the last user of the collector ends all of his collections, the collector jobs (QPMASERV and QPMACLCT) end.

Because QPMWKCOL works with the QPMLPFRD API, the parameters selected for QPMWKCOL will affect QPMLPFRD. For example, the interval time selected determines how often QPMLPFRD should be called. Because the new data replaces old data, if QPMLPFRD is not called before the next interval is collected, the data from the previous interval will be lost, although the deltas may still be calculated for the longer interval. The qualified user space is also an important parameter to QPMLPFRD because this is the space that QPMLPFRD will copy the performance data into. If the space is not large enough to hold all the data or if the space is locked, an error message will be issued to the user.

Starting in Version 5 Release 1, performance data is collected by the performance data collector used by collection services. This has the following implications:

• The collection services performance data collector (QYPSPFRCOL) job runs in addition to the QPMASERV and QPMACLCT jobs.
  
  
• Performance data is stored in the management collection (*MGTCOL) object, allowing it to be processed by the create performance data (CRTPFRDTA) command.
  
  
• The collection services performance data collector supports data collection at one-minute intervals, but not at two- or four-minute intervals. Therefore, when the API user requests data at two- or four-minute intervals, the data will be collected at one-minute intervals, but reported back to the user every two or four minutes.

Authorities and Locks

User Space Authority

*CHANGE

Library Authority

*EXECUTE

User Space Lock

*EXCLRD

Required Parameter Group

Type of action to perform

INPUT; CHAR(10)

Whether you want to start, end, or change the collection of a resource. The following values may be specified:

*START	Start the collection of the specified resource.
*END	End the collection of the specified resource.
*CHANGE	Change the collection of the specified resource.

Type of resource

INPUT; CHAR(10)

The type of resource to start, end, or change. The following values may be specified.

*JOB	Job-related information
*POOL	Pool-related information
*DISK	Disk-related information
*IOP	IOP-related information
*COMM	Communications-related information

Time between collections

INPUT; BINARY(4)

The number of seconds between each new collection of data. The following values may be specified.

15	Collect every 15 seconds.
30	Collect every 30 seconds.
60	Collect every 60 seconds.
120	Collect every 120 seconds (2 minutes).
240	Collect every 240 seconds (4 minutes).

Notes:

1. The disk- and IOP-related data require a minimum of 30 seconds between collections.
   
   
2. The communication-related data requires a minimum of 60 seconds between collections.
   
   
3. The jobs-related data should be collected as infrequently as possible to minimize the impact on system performance.

Qualified user space name

INPUT; CHAR(20)

The name of the user space that is to receive the data for this type of resource. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. The user space must be created in the system ASP or in a basic ASP and not in an independent ASP. This ensures that the server job QPMASERV, which processes the API request, can access the user space. The special values for the library name are:

*LIBL	Library list is used.
*CURLIB	Current library is used.

The library name value is resolved when this API is called. If no library is specified as the current library for the job, QGPL is used. Both entries are left-justified.

First sequence number

OUTPUT; BINARY(4)

The sequence number of the first data collection that will be available for the user.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Usage Notes

The QPMWKCOL API has been classified as conditionally threadsafe. This classification is the result of a dependency on the Submit Job (SBMJOB) command, which has been classified conditionally threadsafe. Refer to the SBMJOB command in the Control Language information for restrictions.

Error Messages