chpriority (BPX1CHP, BPX4CHP) — Change the scheduling priority of a process

Function

The chpriority callable service changes the scheduling priority of a process, process group, or user.

Requirements

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.

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 changed. The Which parameter indicates how this parameter is to be interpreted. If this parameter is interpreted as a process group ID or user ID, all processes with the specified process group ID or user ID are to have their priority changed. A value of zero for this parameter specifies the current process, process group, or user ID.

PriorityType

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a value that indicates how the Priority parameter is to be interpreted. This parameter can have one of the following values:

• CPRIO_ABSOLUTE = Indicates that the Priority parameter is to be interpreted as an absolute value. This causes the priority value of the target processes to be set to the value specified by the Priority parameter.
• CPRIO_RELATIVE = Indicates that the Priority parameter is to be interpreted as a relative value. This causes the priority value of the target processes to be incremented or decremented by the value that is specified by the Priority parameter.

The CPRIO_ constants are defined in the BPXYCONS macro.

Priority

Supplied parameter

Type:

Signed Integer

Length:

Fullword

The name of a fullword that contains a value that indicates the priority value that the specific process or group of processes is to be set to or changed by.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chpriority service returns -1 if it is not successful. If it is successful, the chpriority service returns a value of zero.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chpriority service stores the return code. The chpriority service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The chpriority service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The priority is being changed to a lower value, and the current process does not have the appropriate privilege (see Authorization) to do so.
EPERM	A process was located, but the saved set-user-ID of the calling process does not match the saved set-user-ID of the process whose priority is being changed.
EINVAL	The value of the Which parameter was not recognized; the value of the Who parameter is not a valid process ID, process group ID or user ID; or the value of the PriorityType parameter is not supported.
ESRCH	No process could be located using the Which and Who parameter values specified.
EMVSSAF2ERR	A Security product internal error has occurred. Consult the Reason_code parameter for the exact reason for the error.
ENOSYS	The system does not support this function. Your installation has chosen not to enable this function.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chpriority service stores the reason code. The chpriority 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

1. If the supplied Who and Which values specify more than one process, each of the specified processes has its priority values set to the supplied value. If at least one of the specified processes has its priority value successfully changed, the chpriority service returns successfully.
2. The priority value of a process is an integer that can be in the range of -20 to 19. If the priority value that is supplied causes the priority value of a process to be outside this range, the priority of the process is set to the corresponding limit value. The default priority value for all processes is 0.
3. An increase in the priority value of a process results in a lower CPU priority for the process. A decrease in the priority value of a process results in a higher CPU priority for the process.
4. If the supplied priority value would result in a lower priority value for the specified processes, the caller must have appropriate privileges. Refer to Authorization for information about appropriate privileges. In addition to being able to lower the priority value, a caller with appropriate privileges can change the priority of any other process, regardless of the saved set-user-ID value of the process.
5. The setting of the priority value of a process has a corresponding effect on its nice value, as they both represent the relative CPU priority of the process. For example, if you use the chpriority service to change the priority value of a process to its maximum value (19), the nice value of the process is changed to its maximum value (2*NICE_ZERO)-1. This is reflected on the nice, getpriority, chpriority and setpriority services. The NICE_ZERO constant is defined in BPXYCONS.
6. If the ENOSYS return code is received, your installation does not support this service. Contact your system administrator if you require activation of this service.
7. If the supplied Who and Which values specify a process in a multiple—process address space, each of the processes in the address space will have their priority values set to the supplied value.
8. For information about the necessary system setup for this service, see the documentation for the BPXPRMxx parmlib member in Enabling nice(), setpriority(), and chpriority() support in z/OS UNIX System Services Planning.

Related services

• nice (BPX1NIC, BPX4NIC) — Change the nice value of a process
• getpriority (BPX1GPY, BPX4GPY) — Get the scheduling priority of a process
• setpriority (BPX1SPY, BPX4SPY) — Set the scheduling priority of a process

Characteristics and restrictions

There are no restrictions on the use of the chpriority service.