nice (BPX1NIC, BPX4NIC) — Change the nice value of a process

Function

The nice callable service changes the nice value of the calling process.

Requirements

Parameters

Nice_change

Supplied parameter

Type:

Signed Integer

Length:

Fullword

The name of a fullword that contains a value that indicates the relative change in the nice value of the calling process.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the nice service returns -1 if it is not successful. If it is successful, the nice service returns the new nice value minus NICE_ZERO. The constant NICE_ZERO is defined in the BPXYCONS macro (see BPXYCONS — Constants used by services).

Because the nice service can return the value -1 on successful completion, it is necessary to set the Return_code parameter to 0 before a call to nice. If nice returns the value -1, the Return_code parameter can be checked to see if an error occurred or if the service was successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the nice service stores the return code. The nice 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 nice service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EPERM	The nice_change value is negative, and the calling process does not have the appropriate privileges (see Authorization).
EMVSSAF2ERR	A security product internal error has occurred. Consult Reason_code for the exact reason for the error.
ENOSYS	The system does not support this function. Your installation has chosen not to enable it.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the nice service stores the reason code. The nice 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. A process's nice value is a non-negative integer for which a more positive value would result in a lower CPU priority. A minimum nice value of 0 and a maximum value of (2*NICE_ZERO)-1 are imposed on all processes. If the specified nice_change value would result in a nice value that is outside this range, the nice value is set to the limit value. The default nice value for all processes is set to the constant value NICE_ZERO, which is defined in BPXYCONS.
2. If the specified nice_change value is negative, the value would result in a lowering of a process's nice value, thus giving the process a higher CPU priority. Only processes with the appropriate privileges (see Authorization) can lower their nice values.
3. The changing of a process's nice value has the same effect on a process's priority value, because they both represent the process's relative CPU priority. For example, increasing the nice value of a process to its maximum value of (2*NICE_ZERO)-1 has the effect of setting its priority value via the setpriority service to its maximum value (19), and will be reflected on the nice, getpriority, and setpriority services.
4. If the calling process is in a multiple-process address space, each of the processes in the address space has its nice value changed by the call to the nice service.
5. 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.
6. To set up the nice service, see the documentation for parmlib member BPXPRMxx in Enabling nice(), setpriority(), and chpriority() support in z/OS UNIX System Services Planning.

Related services

• setpriority (BPX1SPY, BPX4SPY) — Set the scheduling priority of a process
• getpriority (BPX1GPY, BPX4GPY) — Get the scheduling priority of a process

Characteristics and restrictions

If the calling process is running in a multiple-process address space, the nice values of all the processes in the address space are changed upon successful completion of the nice service.