getpriority (BPX1GPY, BPX4GPY) — Get the scheduling priority of a process
Function
The getpriority callable service gets the scheduling priority of a specific process or group of processes.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1GPY): | 31-bit |
AMODE (BPX4GPY): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4GPY with the same parameters.
Parameters
- Which
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates how the Who parameter is to be interpreted. This parameter can have one of the following values:- PRIO_PROCESS = Indicates that the Who parameter is to be interpreted as a process ID
- PRIO_PGRP = Indicates that the Who parameter is to be interpreted as a process group ID
- PRIO_USER = Indicates that the Who parameter is to be interpreted as a user ID
The PRIO_ constants are defined in the BPXYCONS macro (see BPXYCONS — Constants used by services).
- Who
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates the exact process ID, process group ID or User ID whose priority is to be obtained. The Which parameter indicates how this parameter is to be interpreted. A value of zero for this parameter specifies the current process, process group or User ID.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getpriority service returns the priority value of the specified process, or -1 if it is not successful.
Because the getpriority service can return the value -1 on successful completion, it is necessary to set the Return_code parameter to 0 before a call to the getpriority service. If getpriority returns the value -1, the Return_code parameter can be checked to see if the service was successful, or if an error occurred.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getpriority service stores the return code. The getpriority service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The getpriority service can return one of the following values in the Return_code parameter:Return_code Explanation EINVAL The value of the Which parameter was not recognized; or the value of the Who parameter is not a valid process ID, process group ID or user ID. ESRCH No process could be located using the Which and Who parameter values that were specified. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getpriority service stores the reason code. The getpriority service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Usage notes
- If the supplied Who and Which values specify more than one process, the lowest priority value found among the specified processes is returned.
- The setting of a process's priority value has an equivalent effect on a process's nice value, as they both represent the process's relative CPU priority. For example, setting the priority value of a process via the setpriority service to its maximum value (19) has the effect of increasing its nice value to its maximum value (2*NICE_ZERO)-1, and is reflected on the nice, getpriority and setpriority services. The NICE_ZERO constant is defined in BPXYCONS. (See BPXYCONS — Constants used by services.)
Related services
Characteristics and restrictions
There are no restrictions on the use of the getpriority service.
Examples
See BPX1GPY (getpriority) example for an example using this callable service.