Retrieve System Status (QWCRSSTS) API

The Retrieve System Status (QWCRSSTS) API allows you to retrieve a group of statistics that represents the current status of the system.

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that will receive the system status information being retrieved. For the format, see Format of Data Returned.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable described in Format of Data Returned. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The format of the information to be returned. You must use one of the following format names:

SSTS0100	Basic system status information about the signed-on users and batch jobs in the system. The information returned in this format is similar to the basic display of the Display System Status (DSPSYSSTS) command.
SSTS0200	System status information. The information returned in this format is similar to the disk information of the intermediate or advanced display of the DSPSYSSTS command.
SSTS0300	System status information. The information returned in this format is similar to the pool information of the intermediate or advanced display of the DSPSYSSTS command.
SSTS0400	Pool status information. The information returned in this format is the SSTS0300 format information and additional pool information. The pool selection information parameter must be used when this format is used.
SSTS0500	Pool subsystem information. The information returned in this format is a list of active subsystems using a pool. The pool selection information parameter must be used to select one system pool when this format is used.
SSTS0600	Shared pool usage information. The information returned in this format is the list functions that have allocated a shared pool. The pool selection information parameter must be used to select one active shared pool when this format is used. The machine and base pools cannot be used with this format.

For more information about these formats, see Format of Data Returned.

Reset status statistics

INPUT; CHAR(10)

Whether the status statistics and elapsed time are reset to zero, as if this were the first call to the API. The statistics will be reset before new information is gathered. This parameter will also reset the status statistics on the DSPSYSSTS and Work with System Status (WRKSYSSTS) commands. This parameter is ignored for format SSTS0100, format SSTS0500, and format SSTS0600.

*YES	Statistics will be reset to zero.
*NO	Statistics will not be reset to zero.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Optional Parameter Group

Pool selection information

INPUT; CHAR(*)

Information that is used for selecting which pools to include in the list. This parameter only applies to the SSTS0400, SSTS0500, and SSTS0600 formats. See Format of Pool Selection Information for a description on the layout of this parameter. If this optional parameter is specified, the Size of pool selection information parameter must also be specified.

Size of pool selection information

INPUT; BINARY(4)

The size, in bytes, of the pool selection information parameter. If the value of this parameter is 0, the pool selection information is not used. The valid values for this parameter are 0, 20, or 24. If this parameter is not specified, the Size of pool selection information is defaulted to 0.

Format of Data Returned

The receiver variable holds the system status information returned.

SSTS0100 Format

The following table shows the information returned for the SSTS0100 format. For a detailed description of each field, see Field Descriptions.

SSTS0200 Format

The following table shows the information returned for the SSTS0200 format. For a detailed description of each field, see Field Descriptions.

SSTS0300 Format

The following table shows the information returned for the SSTS0300 format. For a detailed description of each field, see Field Descriptions.

SSTS0400 Format

The following table shows the information returned for the SSTS0400 format. For a detailed description of each field, see Field Descriptions.

SSTS0500 Format

The following table shows the information returned for the SSTS0500 format. For a detailed description of each field, see Field Descriptions.

SSTS0600 Format

The following table shows the information returned for the SSTS0600 format. For a detailed description of each field, see Field Descriptions.

Field Descriptions

% current interactive performance. The percentage of interactive performance assigned to this logical partition. This value is a percentage of the total interactive performance available to the entire physical system. For example, a value of 41 in binary would be 41 percent.

% DB capability. The percentage of processor database capability (in tenths) that was used during the elapsed time. Database capability is the maximum CPU utilization available for database processing on the system. -1 is returned if the system does not report the amount of CPU used for database processing. For example, a value of 411 in binary would be 41.1 percent.

% permanent addresses. The percentage (in thousandths) of the maximum possible addresses for permanent objects that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% permanent 256MB segments used. The percentage (in thousandths) of the maximum possible permanent 256MB segments that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% permanent 4GB segments used. The percentage (in thousandths) of the maximum possible permanent 4GB segements that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% processing unit used. The average (in tenths) of the elapsed time during which the processing units were in use. For example, a value of 411 in binary would be 41.1 percent. For an uncapped partition, this is the percentage (in tenths) of the configured uncapped shared processing capacity for the partition that was used during the elapsed time. This percentage could be greater than 100% for an uncapped partition.

% shared processor pool used. The percentage (in tenths) of the total shared processor pool capacity used by all partitions using the pool during the elapsed time. -1 is returned if this partition does not share processors. For example, a value of 411 in binary would be 41.1 percent.

% system ASP used. The percentage (in ten thousandths) of the system storage pool currently in use. For example, a value of 41123 in binary would be 4.1123 percent.

% temporary addresses. The percentage (in thousandths) of the maximum possible addresses for temporary objects that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% temporary 256MB segments used. The percentage (in thousandths) of the maximum possible temporary 256MB segments that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% temporary 4GB segments used. The percentage (in thousandths) of the maximum possible temporary 4GB segments that have been used. For example, a value of 41123 in binary would be 41.123 percent.

% uncapped CPU capacity used. The percentage (in tenths) of the uncapped shared processing capacity for the partition that was used during the elapsed time. -1 is returned if this partition can not use more than its configured processing capacity. For example, a value of 411 in binary would be 41.1 percent.

Active jobs in system. The number of jobs active in the system (jobs that have been started, but have not yet ended), including both user and system jobs.

Active threads in system. The number of initial and secondary threads in the system (threads that have been started, but have not yet ended), including both user and system threads.

Active to ineligible. The rate (in tenths), in transitions per minute, of transitions of threads from an active condition to an ineligible condition. For example, a value of 123 in binary would be 12.3 transitions per minute.

Active to wait. The rate (in tenths), in transitions per minute, of transitions of threads from an active condition to a waiting condition. For example, a value of 123 in binary would be 12.3 transitions per minute.

Batch jobs ended with printer output waiting to print. The number of completed batch jobs that produced printer output that is waiting to print.

Batch jobs ending. The number of batch jobs that are in the process of ending due to one of the following conditions:

• The job finishes processing normally.
• The job ends before its normal completion point and is being removed from the system.

Batch jobs held on a job queue. The number of batch jobs that were submitted, but were held before they could begin running.

Batch jobs held while running. The number of batch jobs that had started running, but are now held.

Batch jobs on a held job queue. The number of batch jobs on job queues that have been assigned to a subsystem, but are being held.

Batch jobs on an unassigned job queue. The number of batch jobs on job queues that have not been assigned to a subsystem.

Batch jobs running. The number of batch jobs currently running on the system.

Batch jobs waiting for messages. The number of batch jobs waiting for a reply to a message before they can continue to run.

Batch jobs waiting to run or already scheduled. The number of batch jobs on the system that are currently waiting to run, including those that were submitted to run at a future date and time. Jobs on the job schedule that have not been submitted are not included.

Bytes available. The length of all data available to return. All available data is returned if enough space is provided.

Bytes returned. The length of the data actually returned. The number of bytes returned is always less than or equal to both the number of bytes available and the receiving variable length.

Current date and time. The date and time when the status was gathered. This is in system timestamp format.

Current ineligible threads. The number of ineligible threads in the pool's activity level.

Current processing capacity. The amount (in hundredths) of current processing capacity of the partition. For a partition sharing physical processors, this attribute represents the share of the physical processors in the pool it is executing. For example, a value of 233 means that the partition's current processing capacity is equivalent to 2.33 physical processors. If the current number of processors in the partition is four, each virtual processor has 0.58 the computing capacity of a physical processor in the physical machine. For a partition using dedicated processors, the value represents the number of virtual processors that are currently active in the partition. For example, a partition using four dedicated processors will return a value of 400 for the current processing capacity.

Current threads. The number of threads currently using the pool's activity level.

Current unprotected storage used. The current amount of storage in use for temporary objects. This value is in millions (M) of bytes.

Database faults. The rate (in tenths), shown in page faults per second, of database page faults against pages containing either database data or access paths. A page fault is a program notification that occurs when a page that is marked as not in main storage is referred to by an active program. An access path is the means by which the system provides a logical organization to the data in a database file. For example, a value of 123 in binary would be 12.3 page faults per second.

Database pages. The rate (in tenths), in pages per second, at which database pages are brought into the storage pool. A page is a 4096-byte block of information that is transferable between auxiliary storage and main storage. For example, a value of 123 in binary would be 12.3 pages per second.

Defined size. The size of the pool, in kilobytes, as defined in the shared pool, subsystem description, or system value QMCHPOOL. -1 will be returned for pools without a defined size.

Description. The description of the shared pool. This field is blank for private pools defined in subsystem descriptions.

Elapsed time. The time that has elapsed between the measurement start time and the current system time. This value is in the format HHMMSS where HH is the hour, MM is the minute, and SS is the second.

Jobs in system. The total number of user jobs and system jobs that are currently in the system. The total includes:

• All jobs on job queues waiting to be processed.
• All jobs currently active (being processed).
• All jobs that have completed running but still have pending job logs or output on output queues to be produced.

Length of pool allocation entry. The length of the entry returned for each pool allocation. If the receiver variable was not sufficiently large to hold all of the pool allocation information, the amount of pool allocation information returned may be less than this value.

Length of pool information entry. The length of the information returned for each pool. If the receiver variable was not sufficiently large to hold all of the pool information, the amount of pool information returned may be less than this value.

Length of subsystem information entry. The length of the information returned for each subsystem. If the receiver variable was not sufficiently large to hold all of the information, the amount of information returned may be less than this value.

Main storage size. The amount of main storage, in kilobytes, in the system. On a partitioned system, the main storage size can change while the system is active. If the main storage size is larger than 2,147,483,647 kilobytes, this field will return a value of 2,147,483,647 (the maximum amount a 4-byte field can hold). The field "Main storage size (long)" should be used instead of this field, to return the actual size.

Main storage size (long). The amount of main storage, in kilobytes, in the system. On a partitioned system, the main storage size can change while the system is active.

Maximum active threads. The maximum number of threads that can be active in the pool at any one time.

Maximum jobs in system. The maximum number of jobs that are allowed on the system. When the number of jobs reaches this maximum, you can no longer submit or start more jobs on the system. The total includes:

• All jobs on job queues waiting to be processed.
• All jobs currently active (being processed).
• All jobs that have completed running but still have output on output queues to be produced.

Maximum unprotected storage used. The largest amount of storage for temporary objects used at any one time since the last IPL. This value is in millions (M) of bytes.

Minimum base pool size. The minimum size, in kilobytes, for the base pool. This value is the QBASPOOL system value.

Minimum machine pool size. The minimum size, in kilobytes, for the machine pool. This value is the minimum size required by the machine for the machine pool.

Nondatabase faults. The rate (in tenths), in page faults per second, of nondatabase page faults against pages other than those designated as database pages. For example, a value of 123 in binary would be 12.3 page faults per second.

Nondatabase pages. The rate (in tenths), in pages per second, at which nondatabase pages are brought into the storage pool. For example, a value of 123 in binary would be 12.3 pages per second.

Number of partitions. The number of partitions on the system. This includes partitions that are currently powered on (running) and partitions that are powered off.

Number of pools. The number of pools allocated when the information was gathered. This number may be larger than the number of pools information is returned for if the receiver variable is not large enough.

Number of pool allocations available. The number of allocations for the shared pool.

Number of pool allocations returned. The number of pool allocations returned in the receiver variable.

Number of processors. The number of processors that are currently active in this partition.

Number of subsystems available. The number of subsystems using the pool.

Number of subsystems returned. The number of subsystems returned in the receiver variable.

Offset to pool allocation information. The offset from the beginning of the structure to the start of the pool allocation information.

Offset to pool information. The offset from the beginning of the structure to the start of the pool information.

Offset to subsystem information. The offset from the beginning of the structure to the start of the subsystem information.

Paging option. Whether the system will dynamically adjust the paging characteristics of the storage pool for optimum performance. The following special values may be returned.

Partition identifier. The identifier for the current partition in which the API is running.

Pool allocation identifier. The identifier used when the shared pool was allocated.

Pool name. The name of this storage pool. The name may be a number, in which case it is a private pool associated with a subsystem. The following special values may be returned.

Pool size. The amount of main storage, in kilobytes, in the pool.

Processor sharing attribute. This attribute indicates whether this partition is sharing processors. If the value indicates the partition does not share physical processors, then this partition uses only dedicated processors. If the value indicates the partition shares physical processors, then this partition uses physical processors from a shared pool of physical processors. The following values are returned:

Reserved. An ignored field.

Reserved size. The amount of storage, in kilobytes, in the pool reserved for system use (for example, for save/restore operations). The system calculates this amount by using storage pool sizes and activity levels.

Restricted state flag. Whether the system is in restricted state. The following values are returned:

Status.The status of the pool:

Subsystem library name. The library containing the subsystem description. This field will be blank for shared pools (formats SSTS0300 and SSTS0400).

Subsystem name. The subsystem with which this storage pool is associated. This field will be blank for shared pools (formats SSTS0300 and SSTS0400).

System ASP. The storage capacity of the system auxiliary storage pool (ASP1). This value is in millions (M) of bytes.

System name. The name of the system where the statistics were collected.

System pool. The system-related pool identifier for each of the system storage pools that currently has main storage allocated to it.

Total auxiliary storage. The total auxiliary storage (in millions of bytes) on the system.

Tuning maximum activity level. The maximum value that the shared pool's activity level can be set to by the performance adjuster when the QPFRADJ system value is set to 2 or 3. This field is 0 for private pools defined in subsystem descriptions.

Tuning maximum faults. The maximum page faults per second (in hundredths) to use as a guideline for the shared storage pool. For example, a value of 1234 would be 12.34 page faults per second. This field is 0 for private pools defined in subsystem descriptions.

Tuning maximum pool size %. The maximum amount of storage to allocate to the shared storage pool (as a percentage of total main storage). The value returned is in hundredths. For example, a value of 1234 would be 12.34 percent. This field is 0 for private pools defined in subsystem descriptions.

Tuning minimum activity level. The minimum value that the shared pool's activity level can be set to by the performance adjuster when the QPFRADJ system value is set to 2 or 3. This field is 0 for private pools defined in subsystem descriptions.

Tuning minimum faults. The minimum page faults per second (in hundredths) to use as a guideline for the shared storage pool. For example, a value of 1234 would be 12.34 page faults per second. This field is 0 for private pools defined in subsystem descriptions.

Tuning minimum pool size %. The minimum amount of storage to allocate to the shared storage pool (as a percentage of total main storage). The value returned is in hundredths. For example, a value of 1234 would be 12.34 percent. This field is 0 for private pools defined in subsystem descriptions.

Tuning per-thread faults. The page faults per second (in hundredths) for each active thread to use as a guideline for the shared storage pool. For example, a value of 1234 would be 12.34 page faults per second. This field is 0 for private pools defined in subsystem descriptions.

Tuning priority. The priority of the shared storage pool used by the system when making automatic performance adjustments. This field is 0 for private pools defined in subsystem descriptions.

Users currently signed on. The number of users currently signed on the system. System request jobs and group jobs are not included in this number.

Users signed off with printer output waiting to print. The number of sessions that have ended with printer output files waiting to print.

Users suspended by group jobs. The number of user jobs that have been temporarily suspended by group jobs so that another job may be run.

Users suspended by system request. The number of user jobs that have been temporarily suspended by system request jobs so that another job may be run.

Users temporarily signed off (disconnected). The number of jobs that have been disconnected due to either the selection of option 80 (Temporary sign-off) or the entry of the Disconnect Job (DSCJOB) command.

Wait to ineligible. The rate (in tenths), in transitions per minute, of transitions of threads from a waiting condition to an ineligible condition. For example, a value of 123 in binary would be 12.3 transitions per minute.

Format of Pool Selection Information

Selection Field Descriptions

Shared pool name.This is used to select a shared pool when type of pool is *SHARED. The possible values are:

When *ALL is specified the pools are returned in the order *MACHINE, *BASE, *INTERACT, *SPOOL, and *SHRPOOL1-60. This field must be blank when *SYSTEM is specified for type of pool.

System pool identifier.This is used to select an active system pool when type of pool is *SYSTEM. The possible values are:

When -1 is specified only the active pools are returned in system pool identifier order. This field must be 0 when *SHARED is specified for type of pool.

Type of pool.The type of pools to include in the list. The possible special values follow:

Error Messages

[ Back to top | Work Management APIs | APIs by category ]